conversation-routing

Send Instance Message

Stream a message to a specific agent instance.

Resolves the agent instance’s runner URL and streams the SSE response back to the client. This is the second hop in the two-hop routing pattern.

Agent instances, agent types, and agent resources all live in the tenant SurrealDB namespace; the dependency on get_surrealdb_client resolves the right namespace through the auth chain, and the namespace itself is the organization boundary.

Returns: SSE stream of the agent’s response.

Raises: NotFoundError: If instance not found in this namespace. AgentInvokerError: If runner resolution or streaming fails.

POST

agents

instances

{instance_id}

messages

Send Instance Message

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

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

Path Parameters

instance_id

string

required

Body

application/json

Request body for sending a message to a specific agent instance.

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

ChatMain 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.

Send Instance Message

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

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

Documentation Index

Path Parameters

Body

Response