Run Message Workflow

Runtime contract

The generated OpenAPI operation omits the JSON request body. Send the body shown here; an empty body is not a valid request. The generated response example also does not fully reflect the current A2A envelope.

Start the example A2A server and set the same OS_SECURITY_KEY in the client terminal. These examples target reference-workflow on port 7777. On deployments using scoped bearer authorization, this operation requires workflows:run (or a matching broader grant). The authenticated principal determines user identity; X-User-ID is only anonymous attribution and cannot override it.

The outer id correlates the request and response. messageId identifies the submitted message. contextId becomes the Agno session ID; omit it to let the server create a session, or reuse a session owned by the same principal and component.

Request

curl -X POST "http://localhost:7777/a2a/workflows/reference-workflow/v1/message:send" \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "message-1",
      "contextId": "workflow-session",
      "parts": [
        {
          "kind": "text",
          "text": "Hello"
        }
      ]
    }
  }
}'

Response

The response result is the Task itself: use result.id for the Agno run ID, result.contextId for its session, and result.status.state for status. There is no result.task wrapper. JSON field names use camelCase. A representative envelope is:

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "result": {
    "id": "returned-run-id",
    "contextId": "workflow-session",
    "kind": "task",
    "status": {
      "state": "completed"
    },
    "history": [
      {
        "role": "agent",
        "messageId": "returned-message-id",
        "kind": "message",
        "contextId": "workflow-session",
        "taskId": "returned-run-id",
        "parts": [
          {
            "kind": "text",
            "text": "Example answer"
          }
        ]
      }
    ]
  }
}

Text output is carried in result.history[*].parts; media can also appear in result.artifacts. Optional fields may be absent or null.

This workflow send route does not implement the agent/team configuration.blocking=false option. There are no workflow A2A task-polling or cancellation routes; use the native AgentOS workflow API when those controls are needed.

curl --request POST 'https://example.com/a2a/workflows/string/v1/message:send'

{  "jsonrpc": "2.0",  "id": "request-123",  "result": {    "task": {      "id": "task-456",      "context_id": "context-789",      "status": "completed",      "history": [        {          "message_id": "msg-1",          "role": "agent",          "parts": [            {              "kind": "text",              "text": "Response from agent"            }          ]        }      ]    }  }}

{  "detail": [    {      "loc": [        "string"      ],      "msg": "string",      "type": "string",      "input": null,      "ctx": {}    }  ]}