Conversas
Endpoints do conversation-service, que guarda conversas e mensagens e executa a troca com o agente.
O conversation-service guarda as conversas com agentes e as mensagens de cada uma. Quando você envia uma mensagem, ele chama o agente, grava a resposta e devolve o par pergunta e resposta.
Uma conversa sempre pertence a um agente (assistant_id). Uma mensagem tem um role (user ou assistant) e um status que vai de pending a completed ou failed.
Enviando mensagens
Há duas formas de enviar uma mensagem, com o mesmo corpo:
POST .../messages: espera o agente terminar e retorna a mensagem do usuário e a resposta, nessa ordem.POST .../messages/stream: retorna um fluxotext/event-streamcom a resposta aos pedaços.
As duas aceitam Idempotency-Key. A credencial precisa de conversations:write, assistants:read e models:read.
Eventos do streaming
Cada evento tem um nome em event: e um JSON em data:, cujo campo type repete o nome.
| Evento | Quando chega | Conteúdo |
|---|---|---|
started | Primeiro evento do fluxo. | correlation_id da requisição. |
message | Ao criar a mensagem do usuário e a do agente. | message: a mensagem completa. |
chunk | A cada pedaço de texto gerado. | message_id e content, o trecho novo. Concatene na ordem. |
docs_used | Quando o agente consulta uma coleção. | message_id e a consulta usada. |
tool_response | Quando uma ferramenta devolve resultado. | message_id e tool_response. |
mcp_progress | Durante uma ferramenta MCP demorada. | message_id, message e progress. |
attachment_warnings | Quando um anexo não pôde ser usado. | message_id e warnings. |
done | Resposta concluída. | message: a resposta final do agente. |
error | Falha durante o fluxo. | status_code e data com error_code e message. |
heartbeat | Depois de done, antes de fechar. | Nada além de type. |
Depois que o fluxo começa, o status HTTP já é 200, então falhas chegam como evento error. Os error_code possíveis são NOT_FOUND, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN e INTERNAL_ERROR.
Se o cliente desconectar no meio do fluxo, a plataforma ainda grava a resposta do agente no estado em que parou.