Invoke, Chat & Streaming

Agents support three interaction patterns.

Invoke

Invoke is for processing structured input and returning output.

Request

POST /agent/{name}/invoke
{
  "input": { "key": "value" },
  "stream": false,
  "context": {
    "conversation_id": "conv_123",
    "user_id": "user_456",
    "custom": { "tenant_id": "acme" }
  }
}

The context field is optional and passed to your agent handler for tracking conversations, identifying users, or passing custom data.

Response

{
  "output": "result"
}

When to Use

• Data processing and transformation
• API-like operations
• One-shot tasks without conversation history

Chat

Chat is for conversational interactions with message history.

Request

POST /agent/{name}/chat
{
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "context": {
    "conversation_id": "conv_123",
    "user_id": "user_456"
  }
}

The context field is optional and useful for tracking multi-turn conversations or identifying users.

Response

{
  "message": {
    "role": "assistant",
    "content": "Hello! How can I help?"
  }
}

Message Roles

When to Use

• Conversational AI and chatbots
• Multi-turn dialogues
• Interactions requiring context from previous messages

Streaming

Both invoke and chat can stream responses for real-time output.

Request

Set stream: true in the request body:

{
  "input": {...},
  "stream": true
}

Response (Server-Sent Events)

data: {"chunk": "Hello "}

data: {"chunk": "World!"}

data: [DONE]

When to Use

• Long-running generation tasks
• Real-time typing effects
• Large responses where users benefit from incremental display

Non-Streaming Fallback

When a streaming handler receives stream: false:

1. All chunks are collected
2. Concatenated into a single response
3. Returned as a regular JSON response

Error Responses

Next Steps

• What are Agents? — Agent fundamentals
• Python Runtime — Implement handlers in Python
• TypeScript Runtime — Implement handlers in TypeScript