WebSocket Protocol Reference

This document describes the WebSocket protocol used by Omnia agent facades.

Connection

URL Format

ws://host:port?agent=<agent-name>&namespace=<namespace>
ParameterRequiredDescription
agentYesName of the AgentRuntime
namespaceNoNamespace (defaults to default)

Example

websocat "ws://localhost:8080?agent=my-agent&namespace=production"

Message Types

Client Messages

Messages sent from client to server.

Message

Send a user message to the agent:

{
  "type": "message",
  "content": "Hello, how are you?",
  "session_id": "optional-session-id",
  "metadata": {
    "user_id": "user-123"
  }
}
FieldTypeRequiredDescription
typestringYesMust be "message"
contentstringYesUser message content
session_idstringNoResume existing session
metadataobjectNoCustom metadata

Server Messages

Messages sent from server to client.

Connected

Sent immediately after connection:

{
  "type": "connected",
  "session_id": "sess-abc123"
}

Chunk

Streaming response chunk:

{
  "type": "chunk",
  "content": "Hello! I'm doing"
}

Done

Final response completion:

{
  "type": "done",
  "content": "Hello! I'm doing great, thank you for asking!"
}

Tool Call

Agent is calling a tool:

{
  "type": "tool_call",
  "tool_call": {
    "id": "tc-123",
    "name": "weather",
    "arguments": {
      "location": "San Francisco"
    }
  }
}

Tool Result

Result from a tool call:

{
  "type": "tool_result",
  "tool_result": {
    "id": "tc-123",
    "result": "72°F, Sunny"
  }
}

Error

Error message:

{
  "type": "error",
  "error": {
    "code": "INVALID_MESSAGE",
    "message": "Failed to parse message"
  }
}

Error Codes

CodeDescription
INVALID_MESSAGEMessage format is invalid
SESSION_NOT_FOUNDSpecified session doesn’t exist
PROVIDER_ERRORLLM provider returned an error
TOOL_ERRORTool execution failed
INTERNAL_ERRORInternal server error

Message Flow

New Conversation

Client                          Server
   |                               |
   |-- connect ------------------>|
   |<-- connected (session_id) ---|
   |                               |
   |-- message ------------------->|
   |<-- chunk --------------------|
   |<-- chunk --------------------|
   |<-- done ---------------------|

With Tool Calls

Client                          Server
   |                               |
   |-- message ------------------->|
   |<-- tool_call ----------------|
   |<-- tool_result --------------|
   |<-- chunk --------------------|
   |<-- done ---------------------|

Session Resumption

Client                          Server
   |                               |
   |-- connect ------------------>|
   |<-- connected (session_id) ---|
   |                               |
   |-- message (session_id) ----->|
   |<-- done ---------------------|

Session Handling

New Session

Omit session_id to create a new session:

{"type": "message", "content": "Hello"}

The server responds with a connected message containing the new session ID.

Resume Session

Include session_id to resume:

{
  "type": "message",
  "session_id": "sess-abc123",
  "content": "Continue our conversation"
}

If the session exists and hasn’t expired, conversation history is preserved.

Session Expiration

Sessions expire based on the AgentRuntime’s session.ttl configuration. Attempting to resume an expired session creates a new one.

Connection Health

The server sends WebSocket ping frames to maintain connection health. Clients should respond with pong frames automatically (most WebSocket libraries handle this).

Default timeouts: