Skip to main content
Glama

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

NameRequiredDescriptionDefault
contextNoSource-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.
messageYesMessage to send to the agent
agent_idYesAgent UUID
bindingsNoValues 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.
metadataNoOpaque 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_idNoSession ID from a previous call. Reuse it to retain conversation context; omit for the first message.
timeout_msNoRequested 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.
attachmentsNoAttachments 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_keyNoIdentity 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_fromNoNames 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_channelNoOriginal 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_idNoClient-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_nameNoDisplay 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

NameRequiredDescriptionDefault
gatedNo
usageNo
blocksNo
outcomeNo
successNo
responseNo
cancelledNo
timed_outNo
truncatedNo
iterationsNo
model_usedNo
session_idNo
tool_callsNo
tools_usedNo
execution_idNo
finish_reasonNo
provider_usedNo
ignored_fieldsNo
accepted_fieldsNo
user_message_idNo
client_message_idNo
idempotent_replayNo
truncated_tool_callNo
assistant_message_idNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv2.2.4
    • changedInput schema / properties / agent_id / description
      Previous value: -"UUID do agente"New value: +"Agent UUID"
    • changedInput schema / properties / attachments / description
      Previous value: -"Anexos por REFERÊNCIA (só path do bucket; url/base64 não são aceitos aqui). Só para a própria pessoa — key de papel member ou login de pessoa (OAuth), dona do arquivo; a autorização é a MESMA do /stream (dono + vínculo à conversa). Outras keys: campo vai para ignored_fields."New value: +"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."
    • addedInput schema / properties / attachments / items / properties / content_type / description
      Added value: +"Tipo MIME (ex.: application/pdf, image/png)"
    • addedInput schema / properties / attachments / items / properties / filename / description
      Added value: +"File name shown in the conversation"
    • changedInput schema / properties / attachments / items / properties / path / description
      Previous value: -"Caminho no bucket chat-attachments ({tenant}/{user}/{arquivo}), obtido no upload"New value: +"Uploaded attachment path, formatted as tenant/user/file"
    • addedInput schema / properties / attachments / items / properties / size_bytes / description
      Added value: +"Size in bytes"
    • changedInput schema / properties / bindings / description
      Previous value: -"Argumentos autoritativos das tools (defaults_from_context / ${context.x}), ex.: idSolicitante. Nunca vão ao modelo nem ficam gravados. Só key admin/owner."New value: +"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."
    • changedInput schema / properties / client_message_id / description
      Previous value: -"UUID gerado pelo cliente para idempotência do envio (24 h, por agente e por pessoa/chave). Mesmo id + mesma mensagem = replay da resposta gravada (idempotent_replay: true) sem rodar o agente; turno em voo = SESSION_BUSY; outra mensagem = IDEMPOTENCY_CONFLICT. Use em retries."New value: +"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."
    • changedInput schema / properties / consumer_channel / description
      Previous value: -"Canal ORIGINAL da pessoa (ex.: whatsapp, email, web, api) — não o transporte (o transporte já é mcp_server). Só com consumer_key e key admin/owner. Texto livre em minúsculas; sem ele, fica \"mcp\"."New value: +"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."
    • changedInput schema / properties / consumer_display_name / description
      Previous value: -"Nome de exibição da pessoa identificada por consumer_key. Só com consumer_key e key admin/owner. Vale do presente em diante (cadastro e conversa ATUAL); conversas encerradas guardam o nome da época."New value: +"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."
    • changedInput schema / properties / consumer_key / description
      Previous value: -"Identidade do consumidor final em nome de quem a mensagem é enviada (ex.: id do usuário no seu sistema, telefone só-dígitos). Escopa memória e controle de engajamento por pessoa. Sem ela, integrações com key admin/owner rodam SEM memória (falha fechada, doc 38 D5). Keys de papel member e o login de pessoa (OAuth, qualquer papel) já identificam a pessoa e NÃO podem falar por outra (no login, o campo vai para ignored_fields com person_identity_is_the_key_owner). Key de papel editor: o campo é IGNORADO. Sob admin/owner a identidade é DECLARADA: reusar o session_id de OUTRA pessoa é recusado com code CONFLICT (omita o session_id para abrir uma conversa nova); uma conversa que ainda não tem identidade é ADOTADA pela primeira declaração e fica travada nela."New value: +"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."
    • changedInput schema / properties / context / description
      Previous value: -"Dados do sistema de origem que o agente lê (ex.: userName). Plano, só escalares, até 2000 caracteres. Vai junto da mensagem do usuário, nunca no system prompt. Chave com nome de segredo é redigida. Só key admin/owner."New value: +"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."
    • changedInput schema / properties / message / description
      Previous value: -"Mensagem para enviar ao agente"New value: +"Message to send to the agent"
    • changedInput schema / properties / metadata / description
      Previous value: -"Dados opacos de correlação (ex.: trace_id). Nunca vão ao modelo; gravados (redigidos) em agent_executions.metadata — consultáveis por trace_id. Objeto plano de escalares, até 20 chaves e 4 KB."New value: +"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."
    • changedInput schema / properties / session_from / description
      Previous value: -"Nomes de campos de context/bindings que definem a conversa (ex.: [\"hashFornecedor\"]). A sessão é criada na 1ª vez e reaproveitada — mesmo hash do webhook (session_strategy derive). Não combine com session_id. Só key admin/owner."New value: +"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."
    • changedInput schema / properties / session_id / description
      Previous value: -"ID da sessão retornado por uma chamada anterior. Envie para manter contexto. Omita na primeira mensagem."New value: +"Session ID from a previous call. Reuse it to retain conversation context; omit for the first message."
    • changedInput schema / properties / timeout_ms / description
      Previous value: -"Prazo máximo pedido para o turno, em ms (só ENCURTA o prazo do canal; abaixo de 1000 é ignorado e reportado em ignored_fields). Estourou = outcome TIMEOUT/TURN_TIMEOUT como de costume."New value: +"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."
  2. Changed7 schema fields changedv2.2.3
    • addedInput schema / properties / attachments
      Added value: +{
      +  "description": "Anexos por REFERÊNCIA (só path do bucket; url/base64 não são aceitos aqui). Só para a própria pessoa — key de papel member ou login de pessoa (OAuth), dona do arquivo; a autorização é a MESMA do /stream (dono + vínculo à conversa). Outras keys: campo vai para ignored_fields.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "content_type": {
      +        "type": "string"
      +      },
      +      "filename": {
      +        "type": "string"
      +      },
      +      "path": {
      +        "description": "Caminho no bucket chat-attachments ({tenant}/{user}/{arquivo}), obtido no upload",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "size_bytes": {
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "path"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
    • addedInput schema / properties / client_message_id
      Added value: +{
      +  "description": "UUID gerado pelo cliente para idempotência do envio (24 h, por agente e por pessoa/chave). Mesmo id + mesma mensagem = replay da resposta gravada (idempotent_replay: true) sem rodar o agente; turno em voo = SESSION_BUSY; outra mensagem = IDEMPOTENCY_CONFLICT. Use em retries.",
      +  "format": "uuid",
      +  "type": "string"
      +}
    • addedInput schema / properties / consumer_channel
      Added value: +{
      +  "description": "Canal ORIGINAL da pessoa (ex.: whatsapp, email, web, api) — não o transporte (o transporte já é mcp_server). Só com consumer_key e key admin/owner. Texto livre em minúsculas; sem ele, fica \"mcp\".",
      +  "maxLength": 50,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / consumer_display_name
      Added value: +{
      +  "description": "Nome de exibição da pessoa identificada por consumer_key. Só com consumer_key e key admin/owner. Vale do presente em diante (cadastro e conversa ATUAL); conversas encerradas guardam o nome da época.",
      +  "maxLength": 255,
      +  "type": "string"
      +}
    • changedInput schema / properties / consumer_key / description
      Previous value: -"Identidade do consumidor final em nome de quem a mensagem é enviada (ex.: id do usuário no seu sistema, telefone só-dígitos). Escopa memória e controle de engajamento por pessoa. Sem ela, integrações com key admin/owner rodam SEM memória (falha fechada, doc 38 D5). Keys de papel member já identificam a pessoa e NÃO podem falar por outra. Key de papel editor: o campo é IGNORADO. Sob admin/owner a identidade é DECLARADA: reusar o session_id de OUTRA pessoa é recusado com code CONFLICT (omita o session_id para abrir uma conversa nova); uma conversa que ainda não tem identidade é ADOTADA pela primeira declaração e fica travada nela."New value: +"Identidade do consumidor final em nome de quem a mensagem é enviada (ex.: id do usuário no seu sistema, telefone só-dígitos). Escopa memória e controle de engajamento por pessoa. Sem ela, integrações com key admin/owner rodam SEM memória (falha fechada, doc 38 D5). Keys de papel member e o login de pessoa (OAuth, qualquer papel) já identificam a pessoa e NÃO podem falar por outra (no login, o campo vai para ignored_fields com person_identity_is_the_key_owner). Key de papel editor: o campo é IGNORADO. Sob admin/owner a identidade é DECLARADA: reusar o session_id de OUTRA pessoa é recusado com code CONFLICT (omita o session_id para abrir uma conversa nova); uma conversa que ainda não tem identidade é ADOTADA pela primeira declaração e fica travada nela."
    • addedInput schema / properties / timeout_ms
      Added value: +{
      +  "description": "Prazo máximo pedido para o turno, em ms (só ENCURTA o prazo do canal; abaixo de 1000 é ignorado e reportado em ignored_fields). Estourou = outcome TIMEOUT/TURN_TIMEOUT como de costume.",
      +  "type": "number"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "anyOf": [
      +    {
      +      "required": [
      +        "success"
      +      ]
      +    },
      +    {
      +      "properties": {
      +        "error": {
      +          "additionalProperties": true,
      +          "properties": {
      +            "code": {
      +              "type": "string"
      +            },
      +            "message": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "code",
      +            "message"
      +          ],
      +          "type": "object"
      +        },
      +        "success": {
      +          "const": false
      +        }
      +      },
      +      "required": [
      +        "success",
      +        "error"
      +      ],
      +      "type": "object"
      +    }
      +  ],
      +  "properties": {
      +    "accepted_fields": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "assistant_message_id": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "blocks": {
      +      "items": {
      +        "additionalProperties": true,
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "cancelled": {
      +      "type": "boolean"
      +    },
      +    "client_message_id": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "execution_id": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "finish_reason": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "gated": {
      +      "type": "boolean"
      +    },
      +    "idempotent_replay": {
      +      "type": "boolean"
      +    },
      +    "ignored_fields": {
      +      "items": {
      +        "additionalProperties": true,
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "iterations": {
      +      "type": "integer"
      +    },
      +    "model_used": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "outcome": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "provider_used": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "response": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "session_id": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "success": {
      +      "type": "boolean"
      +    },
      +    "timed_out": {
      +      "type": "boolean"
      +    },
      +    "tool_calls": {
      +      "items": {
      +        "additionalProperties": true,
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "tools_used": {
      +      "items": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "type": "array"
      +    },
      +    "truncated": {
      +      "type": "boolean"
      +    },
      +    "truncated_tool_call": {},
      +    "usage": {
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "user_message_id": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    }
      +  },
      +  "type": "object"
      +}
  3. Changed5 schema fields changedv2.2.2
    • addedInput schema / properties / bindings
      Added value: +{
      +  "additionalProperties": {
      +    "type": [
      +      "string",
      +      "number",
      +      "boolean",
      +      "null"
      +    ]
      +  },
      +  "description": "Argumentos autoritativos das tools (defaults_from_context / ${context.x}), ex.: idSolicitante. Nunca vão ao modelo nem ficam gravados. Só key admin/owner.",
      +  "type": "object"
      +}
    • addedInput schema / properties / consumer_key
      Added value: +{
      +  "description": "Identidade do consumidor final em nome de quem a mensagem é enviada (ex.: id do usuário no seu sistema, telefone só-dígitos). Escopa memória e controle de engajamento por pessoa. Sem ela, integrações com key admin/owner rodam SEM memória (falha fechada, doc 38 D5). Keys de papel member já identificam a pessoa e NÃO podem falar por outra. Key de papel editor: o campo é IGNORADO. Sob admin/owner a identidade é DECLARADA: reusar o session_id de OUTRA pessoa é recusado com code CONFLICT (omita o session_id para abrir uma conversa nova); uma conversa que ainda não tem identidade é ADOTADA pela primeira declaração e fica travada nela.",
      +  "maxLength": 200,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / context
      Added value: +{
      +  "additionalProperties": {
      +    "type": [
      +      "string",
      +      "number",
      +      "boolean",
      +      "null"
      +    ]
      +  },
      +  "description": "Dados do sistema de origem que o agente lê (ex.: userName). Plano, só escalares, até 2000 caracteres. Vai junto da mensagem do usuário, nunca no system prompt. Chave com nome de segredo é redigida. Só key admin/owner.",
      +  "type": "object"
      +}
    • addedInput schema / properties / metadata
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Dados opacos de correlação (ex.: trace_id). Nunca vão ao modelo; gravados (redigidos) em agent_executions.metadata — consultáveis por trace_id. Objeto plano de escalares, até 20 chaves e 4 KB.",
      +  "type": "object"
      +}
    • addedInput schema / properties / session_from
      Added value: +{
      +  "description": "Nomes de campos de context/bindings que definem a conversa (ex.: [\"hashFornecedor\"]). A sessão é criada na 1ª vez e reaproveitada — mesmo hash do webhook (session_strategy derive). Não combine com session_id. Só key admin/owner.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  4. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations it discloses that invocation executes the agent, consumes tokens, and may cause external side effects, plus what is returned (response, execution/session identifiers, usage, structured blocks). It also surfaces failure semantics an agent must plan around — TIMEOUT/TURN_TIMEOUT, CONFLICT on cross-person session reuse, and the 24-hour idempotency replay window — which annotations alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Five short sentences, front-loaded with purpose and cost, then key parameter usage, then return shape, then a contract link. No sentence is redundant and the cost/side-effect warning arrives before the parameter guidance, which is the right order for a token-consuming call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter, side-effecting tool with nested objects, the description covers the essentials an agent needs before calling: cost, side effects, session continuity, identity scoping, idempotency, and error classes. An output schema exists, so the brief return summary is a bonus rather than a gap, and the invocation-contract link covers residual depth.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the parameter docs are already unusually detailed, so the description mostly reinforces rather than adds. The one genuinely additive piece is the cross-parameter guidance that session_id carries conversation context while client_message_id governs idempotent retries, but the consumer_key and session_from nuances are documented more fully in the schema itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource ('Send a message to a published agent'), and 'published' scopes it so the agent can tell it apart from create_agent, get_agent, or publish_agent siblings. An agent knows immediately this is the invocation path, not a management path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when to use it (messaging a published agent) and gives concrete selection rules among parameters: reuse session_id for continuity, omit it for a first message, use client_message_id for idempotent retries, and supply consumer_key when sharing an admin/owner integration. It stops short of naming sibling alternatives such as cancel_agent_turn or list_agent_sessions for inspecting a run, so it is clear but not fully routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools