Skip to main content
AgentOS clones a fresh agent for each POST /api/chat, so concurrent callers never share chat_history and the agent you passed into AgentOS(agents=[…]) is never mutated by request traffic.

​
Quick Start

1

Serve an Agent

2

Chat With a Session

Supply a session_id to continue the same conversation across calls. Omit it to make each call a fresh session.
Two concurrent clients using different session_ids never see each other’s transcripts.

​
How It Works

Each request resolves a per-request agent, resets its transcript, binds the session, and runs one turn. The handler reuses the wrapper’s existing helpers (_supports_session_isolation, _clone_agent from praisonai.api.agent_invoke) rather than reinventing cloning.

​
Session Contract

The response model is unchanged: {response, agent_name, session_id}. Only the internal binding of session_id and the concurrency semantics changed.
An agent configured with handoffs=[…] is not cloned per request. It stays on the shared template, so chat_history is shared and session_id is not bound. This is deliberate — cloning would drop the handoffs. Use a session-aware backend (e.g. praisonai_mcp.serve_agents) if you need both handoffs and session isolation.
If cloning fails, /api/chat returns HTTP 500 with detail "Failed to isolate agent for session: {reason}". It is retry-safe and typically indicates a non-copyable custom object on the agent (e.g. a live socket).

​
When Cloning Applies

Only real Agent instances that expose the per-session machinery are cloned. Plain mocks and lightweight callables fall back to the shared template.

​
Best Practices

Supplying the same session_id on each turn is how a client continues one conversation. Omitting it starts a fresh session on a fresh clone every time.
Agents with handoffs stay on the shared template and are not session-isolated over /chat. Reach for serve_agents([...]) when you need handoffs and per-session isolation together.
A 500 — Failed to isolate agent for session means the clone step raised, usually from a non-copyable object on the agent. It is safe to retry after removing the offending object.
This clone model isolates concurrent in-process requests. It does not persist sessions across process restarts — use a session store backend for durable history.

Serve Agents

serve_agents([...]) — per-session isolation with handoff support, useful for comparison

PraisonAI Call

The call server that hosts the n8n agent-invoke router