Skip to main content
POST
Escribirle al agente y ver que responde
Runs one turn against the agent and returns its reply. Use it to verify a change with the case that motivated it, before calling it done. It always runs in test mode, and that is not configurable. The tools that write — booking, charging, opening a ticket — are simulated and touch nothing real, and the conversation is not kept in the business history. A public endpoint that ran them for real would give any PAT the ability to create appointments and charges on behalf of the business, without the token’s scopes having any say: what a tool does is governed by the agent, not by the token. Real customer conversations go through the channels, not through this.

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 the agents: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

  • reply is 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_simulated is 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 in tools_called and not in tools_simulated ran for real, and only read tools do.
  • A session_id from 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

Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Path Parameters

id
string
required

Body

application/json
message
string
required

Lo que le escribiria un cliente.

Maximum string length: 2000
Example:

"hola, tienen hora para mañana?"

session_id
string

Para seguir una conversacion de prueba ya empezada. Solo acepta un id devuelto por este mismo endpoint; sin esto se abre una nueva.

channel_type
string

Canal a simular. Cambia el largo y el formato de la respuesta: un correo no se escribe como un WhatsApp.

Example:

"whatsapp"

Response

200 - application/json
session_id
string
required

Identificador de esta conversacion de prueba. Mandalo de vuelta para seguirla.

status
string
required
Example:

"completed"

reply
string[]
required

Los mensajes de texto que respondio, en orden. Un agente de WhatsApp suele responder en varios cortos.

tools_called
string[]
required

Las herramientas que llamo durante el turno.

tools_simulated
string[]
required

Cuales de esas se simularon. Todas las que escriben lo estan: por esta ruta el agente no toca los datos del negocio.

duration_ms
number