Gateway WebSocket Protocol

The Gateway WebSocket Protocol defines how clients communicate with agents through the Aigentic gateway. Use this protocol to build custom frontends, automation scripts, or integrations that interact with agents outside of the Aigentic console.

Connection Flow

1. Authenticate

Establish an authenticated session with the Aigentic platform before opening a WebSocket connection. The specific authentication mechanism depends on your integration type.

2. Open WebSocket Connection

Connect to the gateway WebSocket endpoint:

wss://aigentic.life/ws?token=<session_token>

3. Connection Acknowledgment

Upon successful connection, the server sends an acknowledgment:

{
  "type": "connection.ack",
  "data": {
    "session_id": "sess_abc123",
    "connected_agents": [
      {
        "agent_id": "agent-001",
        "agent_name": "Research Assistant",
        "status": "running"
      }
    ]
  }
}

4. Connection Lifecycle

Client                          Gateway                         Agent
  │                                │                               │
  │──── WebSocket connect ────────►│                               │
  │◄─── connection.ack ──────────│                               │
  │                                │                               │
  │──── chat.message ─────────────►│──── forward to agent ────────►│
  │                                │                               │
  │◄─── chat.stream.start ───────│◄─── response stream ──────────│
  │◄─── chat.stream.delta ───────│                               │
  │◄─── chat.stream.delta ───────│                               │
  │◄─── chat.stream.end ─────────│                               │
  │                                │                               │
  │──── connection.close ─────────►│                               │

Message Types

All messages are JSON objects with a type field and a data field.

Client-to-Server Messages

chat.message

Send a message to an agent.

{
  "type": "chat.message",
  "data": {
    "agent_id": "agent-001",
    "content": "What are the latest trends in AI safety research?",
    "session_id": "sess_abc123"
  }
}

Field	Type	Required	Description
agent_id	string	Yes	The target agent’s ID
content	string	Yes	The message text
session_id	string	No	Conversation session (auto-generated if omitted)

chat.cancel

Cancel an in-progress response.

{
  "type": "chat.cancel",
  "data": {
    "agent_id": "agent-001",
    "session_id": "sess_abc123"
  }
}

connection.ping

Keep-alive ping. The server responds with connection.pong.

{
  "type": "connection.ping",
  "data": {}
}

Server-to-Client Messages

chat.stream.start

Indicates the agent has started generating a response.

{
  "type": "chat.stream.start",
  "data": {
    "agent_id": "agent-001",
    "session_id": "sess_abc123",
    "message_id": "msg_xyz789"
  }
}

chat.stream.delta

A chunk of the agent’s response. These arrive incrementally as the model generates text.

{
  "type": "chat.stream.delta",
  "data": {
    "agent_id": "agent-001",
    "message_id": "msg_xyz789",
    "content": "Based on recent research",
    "index": 0
  }
}

Concatenate all content values from delta messages in order to reconstruct the full response.

chat.stream.end

The response is complete.

{
  "type": "chat.stream.end",
  "data": {
    "agent_id": "agent-001",
    "message_id": "msg_xyz789",
    "finish_reason": "complete",
    "usage": {
      "input_tokens": 1250,
      "output_tokens": 487
    }
  }
}

finish_reason	Meaning
complete	The model finished its response naturally
max_tokens	Response reached the maximum token limit
cancelled	Response was cancelled by the client
error	An error occurred during generation

tool.invocation

Notifies the client that the agent is invoking a tool.

{
  "type": "tool.invocation",
  "data": {
    "agent_id": "agent-001",
    "message_id": "msg_xyz789",
    "tool_name": "web_search",
    "tool_input": {
      "query": "AI safety research 2026"
    },
    "invocation_id": "inv_abc123"
  }
}

tool.result

The result of a tool invocation.

{
  "type": "tool.result",
  "data": {
    "agent_id": "agent-001",
    "invocation_id": "inv_abc123",
    "status": "success",
    "output": {
      "results": [
        {"title": "...", "url": "...", "snippet": "..."}
      ]
    },
    "duration_ms": 1200
  }
}

event.error

An error occurred.

{
  "type": "event.error",
  "data": {
    "code": "AGENT_UNAVAILABLE",
    "message": "Agent agent-001 is not available.",
    "agent_id": "agent-001",
    "recoverable": true
  }
}

Common error codes:

Code	Description
AGENT_UNAVAILABLE	Target agent is not available
AUTH_EXPIRED	Session token has expired
RATE_LIMITED	Too many requests
TOOL_DENIED	Tool invocation was blocked by permissions
INTERNAL_ERROR	Unexpected server error

connection.pong

Response to a connection.ping.

{
  "type": "connection.pong",
  "data": {
    "timestamp": "2026-01-15T08:30:00Z"
  }
}

Keep-Alive

Send connection.ping messages at least every 30 seconds to keep the connection alive. If the server does not receive a ping within 60 seconds, it closes the connection.

Rate Limiting

The gateway rate-limits client messages to prevent overload:

Limit	Value
Messages per second	10
Messages per minute	120
Concurrent streams per agent	1

If rate-limited, the server sends an event.error with code RATE_LIMITED.

Protocol Versioning

The current protocol version is v1. The version is included in the connection acknowledgment message.