import json
import os
import websocket
base_url = os.environ["ATAI_API_ENDPOINT"].replace("https://", "wss://", 1)
api_key = os.environ["ATAI_API_KEY"]
socket = websocket.create_connection(
f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/connect",
header={"Authorization": f"Bearer {api_key}"},
)
opened = json.loads(socket.recv())
print(f"{opened['status']}: {opened['agent_id']}")
socket.send(json.dumps({
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
}))
frame = json.loads(socket.recv())
if frame["status"] == "completed":
print(frame["response"])
else:
print(f"Error: {frame['error']}")
socket.close()
{
"status": "connected",
"agent_id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f"
}
{
"status": "completed",
"response": {
"predicted_state": "running",
"p_running": 0.94,
"p_idle": 0.06
},
"query_response_time_ms": 38.4
}
{
"status": "failed",
"error": "<reason>"
}
{
"errors": [
{
"code": "<error_code>",
"message": "No agent with this id in the caller's org.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent was not run in serving mode, or is no longer running.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "node_at_capacity",
"message": "This node is already holding as many sessions as it will.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Instances
Connect to Agent
Open a websocket session with a serving agent
GET
/
agents
/
instances
/
{agent_id}
/
connect
import json
import os
import websocket
base_url = os.environ["ATAI_API_ENDPOINT"].replace("https://", "wss://", 1)
api_key = os.environ["ATAI_API_KEY"]
socket = websocket.create_connection(
f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/connect",
header={"Authorization": f"Bearer {api_key}"},
)
opened = json.loads(socket.recv())
print(f"{opened['status']}: {opened['agent_id']}")
socket.send(json.dumps({
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
}))
frame = json.loads(socket.recv())
if frame["status"] == "completed":
print(frame["response"])
else:
print(f"Error: {frame['error']}")
socket.close()
{
"status": "connected",
"agent_id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f"
}
{
"status": "completed",
"response": {
"predicted_state": "running",
"p_running": 0.94,
"p_idle": 0.06
},
"query_response_time_ms": 38.4
}
{
"status": "failed",
"error": "<reason>"
}
{
"errors": [
{
"code": "<error_code>",
"message": "No agent with this id in the caller's org.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent was not run in serving mode, or is no longer running.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "node_at_capacity",
"message": "This node is already holding as many sessions as it will.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.13 or later of the Archetype platform.
Starting with version 2.0.1, this endpoint is removed from the platform. Run packages through deployments and sessions instead: deploy a package with Create Deployment, then open a session on it with Create Session. To move existing code, see Migrating from Bundles and Instances.
Overview
This endpoint upgrades the connection to a websocket against an agent that was run withmode: serving. Each text frame the client sends is relayed to the agent and answered with one
frame carrying the agent’s answer; what counts as an answer, and when, is the agent’s decision.
The agent is checked before the upgrade, so 404, 409, and 503 arrive as ordinary HTTP
responses rather than as an accepted socket that closes. Send the bearer token as an
Authorization header on the upgrade request.
Request
Frame protocol
The protocol is JSON text. Every frame the server sends is JSON carrying astatus, so a client
reads that one field to tell any frame from any other:
connected— sent once, when the session opens.completed— the answer to one text frame the client sent. It has the same shape as the Query Agent response.failed— a frame the server will not act on (malformed JSON, or a binary frame) is answered with afailedframe, and the session continues; one bad frame is not a broken session. The same frame is sent, and the session then closes, when the agent stops serving or when its state cannot be read for long enough to stop vouching for it.
Session-open frame
Answer frame
The agent’s answer, passed through as it came back. Its shape belongs to the blueprint’s
connectors.
Failure frame
import json
import os
import websocket
base_url = os.environ["ATAI_API_ENDPOINT"].replace("https://", "wss://", 1)
api_key = os.environ["ATAI_API_KEY"]
socket = websocket.create_connection(
f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/connect",
header={"Authorization": f"Bearer {api_key}"},
)
opened = json.loads(socket.recv())
print(f"{opened['status']}: {opened['agent_id']}")
socket.send(json.dumps({
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
}))
frame = json.loads(socket.recv())
if frame["status"] == "completed":
print(frame["response"])
else:
print(f"Error: {frame['error']}")
socket.close()
{
"status": "connected",
"agent_id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f"
}
{
"status": "completed",
"response": {
"predicted_state": "running",
"p_running": 0.94,
"p_idle": 0.06
},
"query_response_time_ms": 38.4
}
{
"status": "failed",
"error": "<reason>"
}
{
"errors": [
{
"code": "<error_code>",
"message": "No agent with this id in the caller's org.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent was not run in serving mode, or is no longer running.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "node_at_capacity",
"message": "This node is already holding as many sessions as it will.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- Start the agent with
mode: servingon Run Bundle. Abatchrun never accepts a session. - Use Query Agent for a single request and answer; use this endpoint for one open session over many payloads.
- A
503carries aRetry-Afterheader giving the number of seconds to wait before opening a session again. - Over a session,
statusis how you tell an answer from a failure, since there is no HTTP status line per frame.
Was this page helpful?