# Run Message Workflow (/reference-api/schema/a2a/run-message-workflow)

## Runtime contract [#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](/reference-api/schema/a2a/run-message-agent#example-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 [#request]

```bash
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 [#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:

```json
{
  "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.

## `POST /a2a/workflows/{id}/v1/message:send`

**Summary:** Run Message Workflow

**Description:** Send a message to an Agno Workflow (non-streaming). The Workflow is identified via the path parameter '{id}'. Optional: Pass user ID via X-User-ID header (recommended) or 'userId' in params.message.metadata.

### Authentication

Not specified.

### Parameters
- `id` (path; string; required)

### Request body

None.

### Responses

#### `200`

Message sent successfully

**`application/json`**

Schema `SendMessageSuccessResponse` (object).

**Top-level fields**
- `id` (string | integer | null; optional)
- `jsonrpc` (string; optional; default `"2.0"`)
- `result` (Task | Message; required)

**Example**

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

#### Other responses

- `400` — Invalid request
- `404` — Workflow not found
- `422` — Validation Error `application/json`: Schema `HTTPValidationError` (object).