Stream an agent reply via SSE (A2A)

curl --request POST \
  --url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/messages/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "message_id": "<string>",
    "contextId": "<string>",
    "taskId": "<string>",
    "metadata": {
      "clientMessageId": "<string>",
      "locale": "<string>"
    },
    "parts": [
      {}
    ]
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: {
      message_id: '<string>',
      contextId: '<string>',
      taskId: '<string>',
      metadata: {clientMessageId: '<string>', locale: '<string>'},
      parts: [{}]
    }
  })
};

fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/messages/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/messages/stream"

payload = { "message": {
        "message_id": "<string>",
        "contextId": "<string>",
        "taskId": "<string>",
        "metadata": {
            "clientMessageId": "<string>",
            "locale": "<string>"
        },
        "parts": [{}]
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<string>

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Messages

Stream an agent reply via SSE (A2A)

A2A-compliant streaming send. The request body uses the same MessageSendParams shape as messages/send. The response is delivered as Server-Sent Events (text/event-stream). Each frame is a data: <json> line; the server emits no native SSE event: field. Lifecycle frames use {"event":"<name>","data":{...}}.

The lifecycle sequence starts with task.status, emits zero or more task.output.delta events, and reaches its terminal state with task.output.completed. Clients must inspect data.status.state on that event: completed, failed, or input-required.

Between frames, the server sends : keepalive SSE comment lines to keep the connection open. Ignore every line starting with :, as EventSource does.

Frames without an event property are transport frames. Discard only the literal {"keepAlive": true} frame, the keep-alive older servers send instead of the comment line. The server closes the stream with a summary frame shaped as {"error":...,"task":{"status":{"state":...}}}. Inspect that frame: an early authorization failure is delivered there, with its code in error.error and HTTP 200 already committed. Never treat HTTP 200 alone as success.

The x-draft-mode: true header bypasses published_config resolution. The same HITL approval flow as messages/send applies - a streaming task may park in input-required until resolved.

POST

agents

{agentId}

messages

stream

Stream an agent reply via SSE (A2A)

curl --request POST \
  --url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/messages/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "message_id": "<string>",
    "contextId": "<string>",
    "taskId": "<string>",
    "metadata": {
      "clientMessageId": "<string>",
      "locale": "<string>"
    },
    "parts": [
      {}
    ]
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: {
      message_id: '<string>',
      contextId: '<string>',
      taskId: '<string>',
      metadata: {clientMessageId: '<string>', locale: '<string>'},
      parts: [{}]
    }
  })
};

fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/messages/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/messages/stream"

payload = { "message": {
        "message_id": "<string>",
        "contextId": "<string>",
        "taskId": "<string>",
        "metadata": {
            "clientMessageId": "<string>",
            "locale": "<string>"
        },
        "parts": [{}]
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<string>

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

User-bound credential carrying an identity: either a session JWT or a user access token (at:*) generated from the user settings UI. Send as Authorization: Bearer <token>. Org API keys (iak_*) are not accepted here - they carry no user identity. Use the x-prismeai-api-key header instead (see OrgApiKeyAuth).

Headers

x-draft-mode

boolean

When true, the stream exercises the agent's live (draft) config instead of published_config. Owners/writers only.

Path Parameters

agentId

string

required

Maximum string length: 64

Body

application/json

message

object

required

A2A v0.3 flat message envelope.

Hide child attributes

message.message_id

string

Client-chosen message identifier, echoed for correlation only. It is not used to deduplicate: the server mints its own msg_* ids for the stored history. To make a send idempotent, use metadata.clientMessageId.

Maximum string length: 256

message.role

enum<string>

Available options:

user,

agent

message.contextId

string

Conversation the message belongs to. Omit it to start a new conversation, then send the contextId returned by the first reply with every following message. Each message opens a new task in the conversation, and the agent receives the earlier turns of that conversation.

Maximum string length: 64

message.taskId

string

Only to answer a task waiting for the user (input-required), for example a tool-call approval sent as a DataPart {"approved": true, "toolCallId": "..."} together with contextId. A message without taskId opens a new task.

message.metadata

object

Message-level metadata. Recognised keys below; any other key is accepted and ignored.

Hide child attributes

message.metadata.clientMessageId

string

Opt-in idempotency key, scoped to (caller, agent). The client picks it and keeps it stable across retries of the same logical message, typically a local id minted before the first attempt.

Replaying a send with the same key returns the first answer verbatim (with task.replayed: true) instead of running the agent again, so a client killed before it could read the response can retry without opening a second conversation. A replay that arrives while the first run is still in flight gets 409 MESSAGE_IN_PROGRESS.

The key alone identifies the message: the body of a replay is not compared with the first one. A replay carrying a different text, other parts or another contextId still gets the first answer, silently. A client that changes the message must mint a new key, and reuse a key only to retry the exact same send. A replay still counts against the rate limits like any other call (it is checked before the key is looked up), and one that is over the limit gets 429, not the stored answer.

Honoured only for a caller authenticated as a user. An org API key with no user behind it resolves to a single shared identity, so the key would be shared by every caller of that key: it is ignored there and the message is sent normally (the format check below still applies).

Keys are kept for 7 days by default (config.idempotency.receipt_retention_days); after that the same key is treated as new. An invalid value is rejected with 400 VALIDATION_ERROR: omit the field to keep the previous (non-idempotent) behaviour. Not supported on messages/stream.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9._:-]{1,128}$

message.metadata.locale

string

BCP-47 code of the user's interface language (fr, fr-FR, pt-BR), used as the default response language only when the message itself does not make the language clear. Also accepted per part; the message level wins. Falls back to the Accept-Language header; an unrecognised code is ignored.

message.parts

object[]

Response

Server-Sent Events stream of A2A task lifecycle events. task.output.completed is the terminal lifecycle event. Its data.status.state reports whether the task completed, failed, or requires user input. A transport summary frame follows; inspect its error and task.status.state fields before closing the stream.

Stream of data: <json> lines. Lifecycle frames use {"event":"<name>","data":{...}}; the server does not emit native SSE event: fields. Ignore : keepalive comment lines, and discard the literal {"keepAlive": true} frame sent by older servers. The final summary frame has no event; inspect error.error for an early authorization failure and task.status.state for the final task state.

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

Collections API

Stream an agent reply via SSE (A2A)

Authorizations

Headers

Path Parameters

Body

Response