conversation-routing

Chat

Main entry point for all user chat messages.

Implements the two-hop routing pattern: looks up the organization’s main agent and streams the response. In v1, this forwards directly to the main agent’s runner streaming. Future versions will add non-streaming routing hop where the main agent selects a target instance before streaming.

The tenant SurrealDB namespace keyed by the authenticated caller’s organization is the isolation boundary for both the agent type and the agent resource lookups the runner resolution traverses.

Returns: SSE stream of the agent’s response.

Raises: NotFoundError: If no main router agent seeded for the organization.

POST

agents

chat

Chat

curl --request POST \
  --url https://api.example.com/agents/chat \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "session_id": "<string>"
}
'

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Body

application/json

Request body for the main chat entry point.

Attributes: message: The user message to send. session_id: Session ID for conversation continuity. New session if None.

message

string

required

session_id

string | null

Response

Successful Response

Event StreamStream resource state changes via Server-Sent Events. Subscribes to NATS state notifications for the authenticated organization and forwards them as SSE events. Each event contains the full resource JSON after a state transition, with optional event metadata (from_state, event_type) when available. SSE events use `event: state_change` when lifecycle event metadata is present, otherwise a generic message event. The connection stays open until the client disconnects. Returns: SSE stream of resource state change events.

Chat

curl --request POST \
  --url https://api.example.com/agents/chat \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "session_id": "<string>"
}
'

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Documentation Index

Body

Response