Serve Agents

Publish your PraisonAI agents to Claude, Cursor, and any MCP client in one line

Publish one or more agents to any MCP client as ask_{name} tools with a single serve_agents([...]) call.

from praisonaiagents import Agent
from praisonai_mcp import serve_agents

support = Agent(name="Support", instructions="Help users with support tickets.")
billing = Agent(name="Billing", instructions="Answer billing questions.")

serve_agents([support, billing], port=7777)

Quick Start

1. Install

   pip install praisonai-mcp

   pip install praisonai-mcp alone is enough for the default http-stream transport. Add praisonai-mcp[all] only if you need extra transports.

2. Serve One Agent

   Pass a single agent — serve_agents wraps it in a list for you.

   from praisonaiagents import Agent
   from praisonai_mcp import serve_agents
   
   support = Agent(name="Support", instructions="Help users with support tickets.")
   
   serve_agents(support, port=7777)

3. Serve Multiple Agents

   Pass a list to publish every agent on one endpoint.

   from praisonaiagents import Agent
   from praisonai_mcp import serve_agents
   
   support = Agent(name="Support", instructions="Help users with support tickets.")
   billing = Agent(name="Billing", instructions="Answer billing questions.")
   
   serve_agents([support, billing], port=7777)

4. Serve Over stdio

   Use stdio when the MCP client launches your process locally (Claude Desktop).

   from praisonaiagents import Agent
   from praisonai_mcp import serve_agents
   
   support = Agent(name="Support", instructions="Help users with support tickets.")
   
   serve_agents([support], transport="stdio")

How It Works

Each ask_* call loads that session’s transcript, runs one turn on an isolated copy of your agent, appends the turn, and returns the reply.

Pick a transport based on where the client runs.

Configuration Options

serve_agents(...) returns the underlying MCPServer instance, which is handy for tests and orchestration.

Published Tools

serve_agents([...]) registers one ask_{agent_name} tool per agent plus a single list_agents() discovery tool.

ask_{agent_name}

Input schema:

{
  "type": "object",
  "properties": {
    "message":    {"type": "string", "description": "Message for the agent."},
    "session_id": {"type": "string", "description": "Opaque session id for conversation continuity. Omit to start a new session."},
    "user_id":    {"type": "string", "description": "Optional caller id."}
  },
  "required": ["message"]
}

Return value:

{
  "text": "<agent reply>",
  "structuredContent": {"session_id": "<echoed or minted id>", "status": "ok"}
}

list_agents

Returns the agents available on the endpoint:

{"agents": [{"name": "Support", "description": "..."}, {"name": "Billing", "description": "..."}]}

The description falls back through agent.role → the first line of agent.instructions → "Ask the {name} agent.".

Session Model

Sessions are opaque, isolated, and server-owned — the client controls continuity by echoing back the session_id, nothing more.

• session_id is opaque and client-supplied. When present, the adapter loads that session’s transcript, applies it to an isolated per-call agent copy, runs one turn, and appends the user + assistant turns.
• Omitting session_id mints a fresh id per call. It never falls back to a shared sticky session, so history never leaks across clients. Verified by test_omitted_session_mints_fresh_id_and_no_shared_history.
• Transcripts are namespaced per tool. The internal store key is f"{tool_name}:{session_id}", so reusing one session_id across ask_support and ask_billing does not mix their histories. Verified by test_same_session_id_across_agents_does_not_leak_history.
• Per-session serialization. Each session holds a threading.Lock, so overlapping calls to the same session can’t clobber each other’s saved turn. Different sessions never contend.
• Per-turn agent isolation. Each turn runs on a shallow copy.copy(agent) with the session’s history swapped in; the original Agent is never mutated by concurrent sessions.
• Server-owned persona. There is no tool parameter that lets the client set instructions or persona. Verified by test_no_client_instructions_parameter.
• AgentOS /chat now uses the same per-request clone model as serve_agents, but drops back to the shared template when the agent has handoffs. See AgentOS Chat Session Isolation.

Client-side continuity pattern — store the returned session_id and send it back on the next turn:

first = call_tool("ask_support", {"message": "My order is late."})
session = first["structuredContent"]["session_id"]

follow_up = call_tool("ask_support", {"message": "Any update?", "session_id": session})

Naming and Disambiguation

Agent names become tool suffixes deterministically. Collisions get a numeric suffix.

Verified by test_normalized_name_collision_registers_distinct_tools and test_unnamed_agents_do_not_collide.

What Clients See

With support and billing served, list_agents() returns:

{"agents": [{"name": "Support", "description": "..."}, {"name": "Billing", "description": "..."}]}

and the tool list contains ask_support, ask_billing, and list_agents.

Call an agent over the http-stream endpoint:

curl -X POST http://127.0.0.1:7777/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {"name": "ask_support", "arguments": {"message": "My order is late."}},
    "id": 1
  }'

Client Integration

{
  "mcpServers": {
    "praisonai-agents": {
      "command": "python",
      "args": ["serve_agents_app.py"]
    }
  }
}

from praisonaiagents import Agent
from praisonai_mcp import serve_agents

support = Agent(name="Support", instructions="Help users with support tickets.")

serve_agents([support], transport="stdio")

from praisonaiagents import Agent
from praisonai_mcp import serve_agents

support = Agent(name="Support", instructions="Help users with support tickets.")
billing = Agent(name="Billing", instructions="Answer billing questions.")

serve_agents([support, billing], port=7777)

{
  "mcpServers": {
    "praisonai-agents": {
      "url": "http://127.0.0.1:7777/mcp",
      "transport": "http-stream"
    }
  }
}

Best Practices

Related