Structured Output

When you disable streaming for an agent, it returns structured JSON responses instead of streamed text. You can optionally define a response schema so the JSON shape stays predictable and machine-readable every time, rather than open-ended prose.

What is Structured Output?

Structured Output means:

✅ Agent returns complete response at once (not streamed)
✅ Response is formatted as JSON (not raw text)
✅ Can be used as a tool in other agents
✅ Can be used in workflows
✅ Can be called via API

Input:
"Analyze this customer feedback: [text]"

Output (Structured JSON):
{
  "sentiment": "positive",
  "confidence": 0.92,
  "topics": ["product_quality", "shipping_time"],
  "recommendations": ["Fast shipping appreciated"],
  "action_required": false
}

Three Ways to Use Structured Output Agents

1. As a Tool in Other Agents

Use one agent as a tool that another agent can call: Scenario: Sales Agent needs help with lead scoring.

Sales Agent receives lead info
Calls “Lead Scorer” agent as a tool
Gets structured score & analysis back
Uses the score to prioritize the lead

Configuration:

Main Agent: Has “Lead Scorer” as a tool
Lead Scorer: Non-streaming agent returning score JSON

Example:

Main Agent workflow:
Receive lead data
Call "Lead Scorer" tool
Get response: { score: 8, category: "hot" }
Route to appropriate team based on score

2. In Workflows

Use agent in workflows for multi-step automation: Scenario: Daily data processing workflow.

Extract Data (API → Raw data)
Validate Agent (Non-streaming) → { valid: true, ... }
Transform Agent (Non-streaming) → { normalized: {...} }
Load to Database (API call)
Result: Clean data loaded

Use cases:

Data validation and cleaning
Content analysis and categorization
Document extraction
Quality assurance checks

3. Via API

Call agent directly through REST API:

curl -X POST https://api.plai.com/agents/{slug}/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Summarize this article...",
    "agent_id": "content-summarizer"
  }'

Response:
{
  "id": "inv_12345",
  "status": "success",
  "output": {
    "summary": "This article discusses...",
    "key_points": [...],
    "confidence": 0.95
  },
  "metadata": {
    "tokens_used": 234,
    "duration_ms": 1200,
    "model": "claude-3.5-sonnet"
  }
}

Configuring Structured Output

In Agent Settings

Go to agent configuration
Find Streaming setting
Disable streaming
Optionally define response schema (JSON structure)

Response Schema (Optional)

Define the expected JSON structure:

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string",
      "enum": ["positive", "negative", "neutral"]
    },
    "score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "topics": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["sentiment", "score"]
}

Benefits:

✅ Agent response always matches schema
✅ Easier to parse in code
✅ Better tool integration
✅ API contracts clearly defined

Using as a Tool

Adding Agent as Tool to Another Agent

Go to Main Agent Settings

Open the agent that will call other agents

Open Tools Tab

Navigate to Tools configuration

Add New Tool

Select “Agent” as tool type

Select Agent

Choose which agent to use as tool

Configure Parameters

Define what input to pass and how to use output

Save

Agent now available as tool

Example: Agent Calling Agent

Scenario: Support Bot needs Lead Scoring Agent.

Support Bot Config:
- Name: Support Bot
- Tools:
  - Help Desk API (for creating tickets)
  - Email Tool (for sending emails)
  - Lead Scorer Agent (for evaluating customers)
- Prompt: “If customer mentions a sales opportunity, use the Lead Scorer agent to evaluate whether they’re a good sales lead”

Flow example:

User: “I’m interested in your enterprise plan”
Support Bot thinks: “This is a sales opportunity”
Support Bot calls Lead Scorer Agent
- Input: “Customer details and interest”
- Output: { lead_score: 9, category: "hot", rec: "route_to_sales" }
Support Bot responds: “Great! I’m connecting you with our sales team”

Using in Workflows

Workflow Integration

Example workflow: Customer Feedback Analysis

Receive Feedback
- Input: Customer feedback text
- Variable: customer_feedback
Analyze with Agent
- Agent: “Feedback Analyzer” (non-streaming)
- Input: customer_feedback
- Output: { sentiment, topics, action_needed }
Route Based on Analysis
- If action_needed == true — create ticket in Help Desk
- If sentiment == "negative" — alert support team
- Else — archive
Notify Stakeholders
- Send report with analysis
- Done

Conditional Routing with Agent Output

Agent returns:

{
  "priority": "high",
  "category": "billing",
  "needs_escalation": true
}

Workflow routes:

If priority == "high" AND needs_escalation — escalate to manager
Elif category == "billing" — route to billing team
Else — route to general support

API Usage

REST API Endpoint

POST /api/agents/{agent_slug}/invoke
Authorization: Bearer {api_key}
Content-Type: application/json

Request Body:
{
  "input": "Your input text or data",
  "context": {
    "user_id": "optional_user_identifier",
    "session_id": "optional_session_id"
  }
}

Response:
{
  "id": "invocation_id",
  "status": "success|error|pending",
  "output": { /* agent response */ },
  "metadata": {
    "duration_ms": 1200,
    "tokens_used": 234,
    "model": "claude-3.5-sonnet"
  }
}

Example: Node.js

const response = await fetch(
  'https://api.plai.com/agents/analyze-sentiment/invoke',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      input: 'This product exceeded expectations!',
      context: { user_id: 'user_123' }
    })
  }
);

const result = await response.json();
console.log(result.output);
// { sentiment: 'positive', confidence: 0.98, score: 9 }

Example: Python

import requests

response = requests.post(
  'https://api.plai.com/agents/summarize-article/invoke',
  headers={
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
  },
  json={
    'input': 'Article text here...',
    'context': {'article_id': 'art_456'}
  }
)

result = response.json()
print(result['output'])
# { 'summary': '...', 'key_points': [...] }

Response Handling

Successful Response

{
  "id": "inv_789",
  "status": "success",
  "output": {
    "result": "processed data",
    "confidence": 0.92
  },
  "metadata": {
    "tokens_used": 145,
    "duration_ms": 850,
    "timestamp": "2024-09-07T14:45:23Z"
  }
}

Error Response

{
  "id": "inv_790",
  "status": "error",
  "error": {
    "code": "INVALID_INPUT",
    "message": "Input validation failed",
    "details": "Required field 'category' missing"
  },
  "metadata": {
    "timestamp": "2024-09-07T14:46:10Z"
  }
}

Best Practices

Define Clear Schema

Specify response format so consumers know what to expect

Handle Errors

Always check status and error fields in responses

Use Context

Pass user_id, session_id, or other context for better tracking

Monitor Usage

Track API calls and token usage in project monitoring

API Security

✅ Use API keys with appropriate permissions
✅ Rotate keys regularly
✅ Don’t embed keys in frontend code
✅ Use environment variables or secrets manager
✅ Monitor for unusual API usage

Comparing with Chat Mode

Aspect	Structured Output	Chat (Streaming)
Response	Complete JSON	Streamed text
Interface	API/Tools/Workflows	PLai Chat UI
Conversation	No history	Persistent history
Use Cases	Automation	User interaction
Multiple Calls	Sequential	Sequential in UI
Response Time	One request → one response	Real-time streaming

🔗 Learn about Chat Mode: Conversational Chat

Troubleshooting

Agent returns empty response

Check:

Input format correct
Agent has proper datasources/tools
Response schema doesn’t reject valid data

Schema validation fails

Solutions:

Review expected schema
Check agent prompt includes format instructions
Adjust schema to be less restrictive

API call times out

Causes:

Agent processing complex request
Tool calls taking too long
External API delays

Solution: Increase timeout or optimize agent

Tool call from another agent fails

Check:

Tool agent is non-streaming
Tool agent is in same project
Tool agent has required datasources
Input format matches tool expectations

Next Steps

Configure Agent - Set up structured output
Workflows, Jobs & Triggers - Use in workflows
Use as Tool - Agent calling agent
API Documentation - Full API reference

Getting Started

Concepts

Agents

Tools

Datasources

Workflows

Jobs

Triggers

Monitor

What is Structured Output?

Three Ways to Use Structured Output Agents

1. As a Tool in Other Agents

2. In Workflows

3. Via API

Configuring Structured Output

In Agent Settings

Response Schema (Optional)

Using as a Tool

Adding Agent as Tool to Another Agent

Example: Agent Calling Agent

Using in Workflows

Workflow Integration

Conditional Routing with Agent Output

API Usage

REST API Endpoint

Example: Node.js

Example: Python

Response Handling

Successful Response

Error Response

Best Practices

Define Clear Schema

Handle Errors

Use Context

Monitor Usage

API Security

Comparing with Chat Mode

Troubleshooting

Next Steps

​What is Structured Output?

​Three Ways to Use Structured Output Agents

​1. As a Tool in Other Agents

​2. In Workflows

​3. Via API

​Configuring Structured Output

​In Agent Settings

​Response Schema (Optional)

​Using as a Tool

​Adding Agent as Tool to Another Agent

​Example: Agent Calling Agent

​Using in Workflows

​Workflow Integration

​Conditional Routing with Agent Output

​API Usage

​REST API Endpoint

​Example: Node.js

​Example: Python

​Response Handling

​Successful Response

​Error Response

​Best Practices

Define Clear Schema

Handle Errors

Use Context

Monitor Usage

​API Security

​Comparing with Chat Mode

​Troubleshooting

​Next Steps

What is Structured Output?

Three Ways to Use Structured Output Agents

1. As a Tool in Other Agents

2. In Workflows

3. Via API

Configuring Structured Output

In Agent Settings

Response Schema (Optional)

Using as a Tool

Adding Agent as Tool to Another Agent

Example: Agent Calling Agent

Using in Workflows

Workflow Integration

Conditional Routing with Agent Output

API Usage

REST API Endpoint

Example: Node.js

Example: Python

Response Handling

Successful Response

Error Response

Best Practices

API Security

Comparing with Chat Mode

Troubleshooting

Next Steps