POST /v1/agents/{id}/query
Write to the agent as if you were a customer and see what it answers.
Endpoint
Required scope
agents:read
Path parameters
Body
Example request
Response
200 OK
400 Bad Request
MESSAGE_REQUIRED when the message is empty, MESSAGE_TOO_LONG over 2000 characters, or SESSION_NOT_A_TEST_CONVERSATION when the session_id did not come from this endpoint.
401 Unauthorized
Missing, invalid, revoked, or expired token.403 Forbidden
The token does not have theagents:read scope.
404 Not Found
AGENT_NOT_FOUND: no agent with that id in the token’s company and project.
502 Bad Gateway
The agent service is unreachable.Operational notes
replyis a list because that is how the agent talks. On WhatsApp it answers in several short messages; joining them into one paragraph is not what the customer sees.tools_simulatedis the one to read. Every write tool the agent called appears there — if it is empty, the turn did not try to change anything. A tool intools_calledand not intools_simulatedran for real, and only read tools do.- A
session_idfrom somewhere else is rejected. Accepting one would attach the turn to a real customer thread and write into its memory. - This costs model tokens like any other turn, and takes as long as a real one — a few seconds, sometimes more when the agent calls tools.
- It reads the agent as it is saved. A section you have not saved yet is not part of the test.
Authorizations
Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.
Path Parameters
Body
Lo que le escribiria un cliente.
2000"hola, tienen hora para mañana?"
Para seguir una conversacion de prueba ya empezada. Solo acepta un id devuelto por este mismo endpoint; sin esto se abre una nueva.
Canal a simular. Cambia el largo y el formato de la respuesta: un correo no se escribe como un WhatsApp.
"whatsapp"
Response
Identificador de esta conversacion de prueba. Mandalo de vuelta para seguirla.
"completed"
Los mensajes de texto que respondio, en orden. Un agente de WhatsApp suele responder en varios cortos.
Las herramientas que llamo durante el turno.
Cuales de esas se simularon. Todas las que escriben lo estan: por esta ruta el agente no toca los datos del negocio.