> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send a message to an agent (A2A, non-streaming) > A2A-compliant message send. The body follows the A2A flat `MessageSendParams` shape - a `message` envelope with `message_id`, `role`, `parts[]`, and an optional `contextId`. Parts are discriminated by field presence: `TextPart` (`text`), `FilePart` (`url` or `raw`), `DataPart` (`data`). An always-on rate-limit floor (200/h per user) applies, plus any agent-configured limit. The HITL approval flow is supported and will park the task in `input-required` until resolved through `/v1/agents/{agentId}/tasks/{taskId}/resolve`. Send the `x-draft-mode: true` header to bypass `published_config` resolution and exercise live (draft) configuration - owners and agent-factory writers only. ## OpenAPI ````yaml /api-reference/agent-factory/swagger.yml post /v1/agents/{agentId}/messages/send openapi: 3.0.3 info: version: 1.0.0 title: Agent Factory API description: | Public REST API for the Agent Factory workspace - agents, conversations, messages, tools, artifacts, sharing, ratings, and discovery. Powered by Prisme.ai's runtime; all endpoints are exposed under each workspace's webhook namespace. contact: name: Prisme.ai url: https://prisme.ai servers: - url: https://{host}/v2/workspaces/slug:agent-factory/webhooks description: Prisme.ai workspace webhooks variables: host: default: api.studio.prisme.ai description: API host (override for self-hosted or sandbox) security: - BearerAuth: [] - OrgApiKeyAuth: [] tags: - name: Agents description: Agent CRUD, discovery, AGENTS.md import/export. - name: Access description: Agent access bindings, sharing, and access requests. - name: ApiKeys description: Agent-scoped API key management (mint, revoke, rotate). - name: Publishing description: Publish or discard draft changes on an agent. - name: Ratings description: User ratings on published agents. - name: Profiles description: >- Agent profiles/presets catalog (simple, workflow, agent_light, agent_full, orchestrator). - name: Activity description: Activity feed for agents (events, errors, lifecycle changes). - name: Analytics description: Agent usage analytics (series + summary). - name: Conversations description: Conversations on an agent (CRUD, archive, star). - name: Messages description: Send messages to an agent (synchronous send + SSE stream). - name: Tasks description: Async task lifecycle (list, fetch, cancel, resolve, subscribe). - name: Artifacts description: Generated artifacts (files, code, content) attached to a task. - name: Shares description: Conversation, message, and artifact share-link snapshots. - name: A2A description: Agent-to-agent JSON-RPC 2.0 gateway (well-known agent.json + RPC). - name: Tools description: Per-agent tool catalogue (system tools, MCP servers, function tools). - name: Retention description: Per-agent and org-wide conversation retention policies. - name: Evaluations description: Agent evaluation runs and results. paths: /v1/agents/{agentId}/messages/send: post: tags: - Messages summary: Send a message to an agent (A2A, non-streaming) description: | A2A-compliant message send. The body follows the A2A flat `MessageSendParams` shape - a `message` envelope with `message_id`, `role`, `parts[]`, and an optional `contextId`. Parts are discriminated by field presence: `TextPart` (`text`), `FilePart` (`url` or `raw`), `DataPart` (`data`). An always-on rate-limit floor (200/h per user) applies, plus any agent-configured limit. The HITL approval flow is supported and will park the task in `input-required` until resolved through `/v1/agents/{agentId}/tasks/{taskId}/resolve`. Send the `x-draft-mode: true` header to bypass `published_config` resolution and exercise live (draft) configuration - owners and agent-factory writers only. operationId: sendMessage parameters: - name: agentId in: path required: true schema: type: string maxLength: 64 - name: x-draft-mode in: header required: false schema: type: boolean description: | When true, the call exercises the agent's live (draft) config instead of `published_config`. Reserved for owners/writers. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MessageSendInput' example: message: message_id: msg-test-2 role: user parts: - text: What is 2+2? Reply with just the number. responses: '200': description: Completed task with the agent's reply. content: application/json: schema: $ref: '#/components/schemas/MessageSendResponse' '400': description: Validation error (e.g. missing `agent_id`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Agent not found. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded (200/h floor or agent-configured). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: MessageSendInput: type: object required: - message properties: message: $ref: '#/components/schemas/Message' MessageSendResponse: type: object properties: error: type: object nullable: true additionalProperties: true task: type: object properties: id: type: string contextId: type: string status: $ref: '#/components/schemas/TaskStatus' output: type: object properties: messages: type: array items: $ref: '#/components/schemas/Message' usage: type: object additionalProperties: true tool_calls: type: array items: $ref: '#/components/schemas/ToolCallSummary' Error: type: object required: - error - message properties: error: type: string description: >- Stable PascalCase or SNAKE_CASE error code (e.g. AgentNotFound, VALIDATION_ERROR, FORBIDDEN, METHOD_NOT_ALLOWED). message: type: string description: Human-readable error message. details: type: object description: Optional structured context for the error. additionalProperties: true Message: type: object description: A2A v0.3 flat message envelope. properties: message_id: type: string maxLength: 256 role: type: string enum: - user - agent contextId: type: string maxLength: 64 taskId: type: string parts: type: array items: $ref: '#/components/schemas/MessagePart' TaskStatus: type: object properties: state: $ref: '#/components/schemas/TaskState' timestamp: type: string message: type: object additionalProperties: true ToolCallSummary: type: object properties: name: type: string arguments: type: object additionalProperties: true status: type: string MessagePart: type: object description: | A2A message part. Discriminated by field presence: `TextPart` (`text`), `FilePart` (`url`/`raw`, `mediaType`, `filename`), `DataPart` (`data`, `mediaType`). additionalProperties: true TaskState: type: string description: A2A task state. enum: - working - completed - canceled - failed - input-required securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | 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 `. Org API keys (`iak_*`) are **not** accepted here - they carry no user identity. Use the `x-prismeai-api-key` header instead (see `OrgApiKeyAuth`). OrgApiKeyAuth: type: apiKey in: header name: x-prismeai-api-key description: | Organization API key (`iak_{orgSlug}_{uuid}`). Unlike `Authorization: Bearer`, this credential is **not** tied to a user identity - it is bound to the org and its effective access is defined by the scopes / permission rules attached to it (it can be restricted to a single project, or kept broader). For Agent Factory, these keys can be generated directly from the Agent Factory UI (in addition to the AI Governance settings). Send as `x-prismeai-api-key: iak_...`. ````