Coming from the OpenAI Agents SDK or LangGraph

View as Markdown · Docs index for coding agents

The concepts mostly carry over. The main difference is where the agent lives. In the OpenAI Agents SDK and LangGraph, the loop runs in your process, and its state lives in a session or checkpointer that you run. In camelRun the loop runs in camelRun, and so do the agent's history and files. Your process provides the tools and starts runs.

This page maps each concept. It also lists what camelRun does not have, so you know before porting.

The same agent, ported

OpenAI Agents SDK:

from agents import Agent, Runner, SQLiteSession, function_tool

@function_tool
def lookup_order(order_id: str) -> dict:
    """Look up an order by id."""
    return orders.get(order_id)

agent = Agent(name="Support", instructions="You help with orders.", tools=[lookup_order])
result = await Runner.run(agent, "Where is order 42?", session=SQLiteSession("user-123"))
print(result.final_output)

camelRun:

from camelai_run import Agents, tool

@tool
def lookup_order(order_id: str) -> dict:
    """Look up an order by id."""
    return orders.get(order_id)

async with Agents() as agents:  # reads CAMELAI_API_KEY
    agent = await agents.upsert("user-123", instructions="You help with orders.", tools=[lookup_order])
    run = await agent.run("Where is order 42?")
    print(run.text)

The key ("user-123") does the job of the session: the same key is the same agent, with its history, from any process. upsert creates the agent the first time and later brings it to the configuration you pass. Nothing is stored on your side.

from camelai_run import serve_tools

# In your web app (pip install "camelai-run[server]"): every worker serves the same tools.
tools_app = serve_tools([lookup_order], runtime="https://run.camelai.com", tenant="acme")  # mount at /mcp

# Once, at deploy time: a definition naming the server.
definition = await agents.runtime.upsert_definition("support", name="Support", systemPrompt="You help with orders.",
    mcpServers=[{"name": "shop", "url": "https://app.example.com/mcp", "auth": {"type": "runtime"}}])

# In any worker or task: no tools here, so no worker holds them.
agent = await agents.upsert("user-123", definition=definition["id"])
run = await agent.run("Where is order 42?")

tenant is your account's id (GET /v1/me). One long-lived process that holds the tools, with every other process upserting with attach=False, works too; see Tools.

OpenAI Agents SDK

LangGraph

Handoffs and multi-agent

camelRun has no handoffs: an agent cannot pass its conversation to another agent, and there is no graph. Use one of these instead.

Delegate. The agent hands a task to a sub-agent and gets its answer back as the call's result, while the conversation stays with it: the Agents SDK's as_tool, or a LangGraph supervisor. The sub-agent is an agent of its own, made from a definition for each call, and the parent's limits cover it. See Multi-agent.

await agents.runtime.upsert_definition("billing-specialist", name="Billing specialist",
    description="Answers questions about invoices, refunds and charges", systemPrompt="You answer billing questions.")
support = await agents.upsert("support-user-123", instructions="You help customers.",
    delegate={"agents": ["billing-specialist"]})

Several delegate calls in one response run in parallel. To keep one specialist's history across calls, name an existing agent instead of a definition: {"agent": f"billing-{user_id}"}.

Route. Your code picks the agent for each message. A small agent with structured output can make the decision:

class Route(BaseModel):
    team: Literal["billing", "technical", "general"]

router = await agents.upsert("router", instructions="Pick the team that should answer this message.")
team = (await router.run(message, output=Route)).output.team
answer = await (await agents.upsert(f"{team}-user-123", instructions=PROMPTS[team])).run(message)

What does not carry over: in a handoff, the receiving agent takes over the conversation and sees its history. In camelRun each agent has its own history, so pass what the other agent needs in the task or the message.

Bringing conversations over

Existing conversations can continue in camelRun. Create the agent with its history in initialMessages, converted to the runtime's message format (user, assistant with tool calls, tool results). See Bringing in existing conversations.

What camelRun adds

• Durable runs. A run survives your process restarting and the runtime's nodes being replaced. A run waiting on a person waits for days at no cost.
• Tools anywhere. Tools run in your process (attached) or behind an HTTPS endpoint (served, for serverless and many workers), and the model can call many of them from code in js_exec. See Tools.
• Channels and schedules. Slack, Telegram, Discord, GitHub and email can reach an agent directly, and agents can wake themselves. See Channels.