Metadata-Version: 2.4
Name: runagents
Version: 0.2.0
Summary: RunAgents Python SDK — deploy, manage, and build AI agents
Author-email: RunAgents <try@runagents.io>
License: Apache-2.0
Project-URL: Homepage, https://runagents.io
Project-URL: Documentation, https://docs.runagents.io
Project-URL: Repository, https://github.com/runagents-io/runagents
Project-URL: Issues, https://github.com/runagents-io/runagents/issues
Keywords: ai,agents,runagents,llm,tool-calling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: watchdog>=3.0; extra == "dev"

# RunAgents Python SDK

Everything you need to build, test, and deploy AI agents on [RunAgents](https://runagents.io) — in one package.

## Install

```bash
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

```bash
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

```python
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

```python
from runagents import Agent, tool

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

# Call a platform tool (mesh 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

```python
from runagents import tool

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

## CLI Commands

| Command | Description |
|---------|-------------|
| `runagents init [name]` | Scaffold a new agent project |
| `runagents dev` | Start local dev server with mock tools |
| `runagents deploy` | Deploy an agent (delegates to Go CLI) |
| `runagents agents list` | List agents |
| `runagents tools list` | List tools |
| `runagents runs list` | List runs |
| `runagents config` | Manage configuration |

## 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`.

```python
# Backward compatible — still works
import runagents_runtime
```

## MCP Server

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

14 tools for AI coding assistants (Claude Code, Cursor, Codex). See [AI Assistant Setup](https://docs.runagents.io/cli/ai-assistant-setup/).

## Configuration

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

| Variable | Description | Default |
|----------|-------------|---------|
| `RUNAGENTS_ENDPOINT` | Platform API URL | `http://localhost:8092` |
| `RUNAGENTS_API_KEY` | API key or workspace key | — |
| `RUNAGENTS_NAMESPACE` | Target namespace | `default` |

## Documentation

- [RunAgents Docs](https://docs.runagents.io)
- [Writing Agents](https://docs.runagents.io/getting-started/writing-agents/)
- [Agent Runtime](https://docs.runagents.io/platform/agent-runtime/)
- [AI Assistant Setup](https://docs.runagents.io/cli/ai-assistant-setup/)
- [CLI Commands](https://docs.runagents.io/cli/commands/)

## License

Apache-2.0
