RunAgents Python SDK

Everything you need to build, test, and deploy AI agents on RunAgents — in one package.

The public source for this package lives in sdk/python/ in the runagents-io/runagents repository so the CLI, SDK, MCP server, docs, and skills ship together.

Install

pip install runagents        # Core SDK + CLI + runtime (zero deps)
pip install runagents[mcp]   # + MCP server for AI coding assistants
pip install runagents[dev]   # + hot-reload for local dev

Quickstart

runagents init my-agent      # Scaffold a project
cd my-agent
runagents dev                # Local dev server with mock tools
runagents deploy             # Ship to the platform

Python API

Client — manage platform resources

from runagents import Client

client = Client()  # reads ~/.runagents/config.json + env vars

agents = client.agents.list()
tools = client.tools.list()
runs = client.runs.list(agent="payment-agent")

result = client.agents.deploy(
    name="my-agent",
    source_files={"agent.py": open("agent.py").read()},
    required_tools=["stripe-api"],
    llm_configs=[{"provider": "openai", "model": "gpt-4o-mini", "role": "default"}],
)

Agent — write agent code

from runagents import Agent, tool

agent = Agent()  # reads TOOL_URL_*, LLM_GATEWAY_URL, LLM_MODEL from env

# Call a platform tool (platform egress layer handles auth)
result = agent.call_tool("echo-tool", "/echo", {"message": "hello"})

# Chat via LLM gateway
response = agent.chat("What is 2+2?", tools=[...])

# Custom handler (Tier 2)
def handler(request, ctx):
    message = request["message"]
    result = agent.chat(message)
    return result["choices"][0]["message"]["content"]

@tool decorator

from runagents import tool

@tool(name="calculator", description="Evaluate math expressions")
def calculate(expression: str) -> str:
    return str(eval(expression))

CLI Commands

Runtime

The runtime provides the HTTP server for deployed agents — tool calling loop, SSE streaming, health checks, OAuth consent, and JIT approvals. It runs automatically inside the platform; for local development use runagents dev.

Policy enforcement remains active at runtime. Agents need bound policy rules (allow or approval_required) for tool calls.

# Backward compatible — still works
import runagents_runtime

MCP Server

pip install runagents[mcp]
runagents-mcp  # starts on stdio

Assistant tools for deployment, catalog inspection, policies, approval connectors, runs, and approvals. See AI Assistant Setup.

Configuration

Reads from ~/.runagents/config.json with env var overrides:

Documentation

• RunAgents Docs
• Writing Agents
• Agent Runtime
• AI Assistant Setup
• CLI Commands

License

Apache-2.0