chat_with_agent
Send messages to a published agent to execute it and retrieve responses while preserving conversation context through reusable session IDs and idempotent retries.
Instructions
Send a message to a published agent. This executes the agent, consumes tokens and may cause external side effects. Reuse session_id for conversation context and client_message_id for idempotent retries. Shared admin/owner integrations must provide consumer_key to enable person-scoped memory. Returns response, execution/session identifiers, usage and structured blocks. See https://docs.zihin.ai/agents/invocation-contract.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"agent_id": "<agent_id>",
"message": "<message>"
},
"name": "chat_with_agent"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Source-system data available to the agent (for example, userName). Flat scalar values only, up to 2000 characters. Sent with the user message, never in the system prompt. Secret-named fields are redacted. Requires an admin or owner key. | |
| message | Yes | Message to send to the agent | |
| agent_id | Yes | Agent UUID | |
| bindings | No | Values injected into agent tool arguments through defaults_from_context or ${context.x}. Never sent to the model or stored. Requires an admin or owner key. | |
| metadata | No | Opaque correlation metadata, such as trace_id. Never sent to the model; stored with secret redaction in the execution. list_executions can filter trace_id. Flat scalars only, at most 20 keys and 4 KB. | |
| session_id | No | Session ID from a previous call. Reuse it to retain conversation context; omit for the first message. | |
| timeout_ms | No | Requested turn deadline in milliseconds; can only shorten the channel deadline. Values below 1000 are ignored and reported in ignored_fields. Expiry returns TIMEOUT/TURN_TIMEOUT. | |
| attachments | No | Attachments by bucket path only; URLs and base64 are not accepted. Available only to the person who owns the file, through a member key or personal OAuth. Other keys receive this field in ignored_fields. | |
| consumer_key | No | Identity of the person represented by the message, such as an external user ID or digits-only phone number. Scopes personal memory and engagement. Only admin/owner keys may declare it; editor keys ignore it, while member keys and personal OAuth already identify their person. Without it, operator keys run without memory. Reusing another person's session_id returns CONFLICT; omit it for a new conversation. A session without an identity adopts the first declared identity and remains bound to it. | |
| session_from | No | Names of context/bindings fields defining the conversation, for example ["customerId"]. Creates a session on first use and reuses the same derived identity. Do not combine with session_id. Requires an admin or owner key. | |
| consumer_channel | No | Original consumer channel, such as whatsapp, email, web or api. Requires consumer_key and an admin/owner key. Lowercase free text; defaults to mcp. Distinct from the MCP transport. | |
| client_message_id | No | Client-generated UUID for 24-hour idempotency per agent and person/key. Reusing the same ID and message replays the response without execution; an active turn returns SESSION_BUSY; a different message returns IDEMPOTENCY_CONFLICT. | |
| consumer_display_name | No | Display name for consumer_key. Requires consumer_key and an admin/owner key. Updates the profile and current conversation; completed conversations retain their historical name. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gated | No | ||
| usage | No | ||
| blocks | No | ||
| outcome | No | ||
| success | No | ||
| response | No | ||
| cancelled | No | ||
| timed_out | No | ||
| truncated | No | ||
| iterations | No | ||
| model_used | No | ||
| session_id | No | ||
| tool_calls | No | ||
| tools_used | No | ||
| execution_id | No | ||
| finish_reason | No | ||
| provider_used | No | ||
| ignored_fields | No | ||
| accepted_fields | No | ||
| user_message_id | No | ||
| client_message_id | No | ||
| idempotent_replay | No | ||
| truncated_tool_call | No | ||
| assistant_message_id | No |