AgentX

Model-agnostic, lightweight AI Agent framework

English | 中文

---

AgentX is a Python framework for building AI agents. Write once, swap models freely — Claude, OpenAI, Gemini, Ollama, DeepSeek, and 100+ models via LiteLLM.

From a 5-line chatbot to multi-agent orchestration with guardrails, checkpoints, and desktop automation — all with the same clean API.

Features

	Feature	Description
🔄	Model-agnostic	Claude / GPT / Gemini / Ollama / DeepSeek / LiteLLM — switch with one string
🛠	Function tools	@tool decorator with auto type inference + JSON Schema generation
🤝	Multi-agent	Handoff collaboration, Agent-as-Tool delegation, ping-pong loop detection
🛡	Guardrails	Input / output / tool — three layers with built-in PII, SQL injection, path traversal
💾	State management	LLM-driven context compression + SQLite/Redis checkpoint persistence
⚡	Streaming	Async event stream with token-by-token output
🖥	Computer Use	Browser/desktop automation via Claude, OpenAI CUA, or generic vision adapters
🔌	MCP	Model Context Protocol client (stdio / HTTP+SSE)
📊	Observability	OpenTelemetry tracing + Prometheus metrics + cost estimation
🎯	Structured output	Pydantic output_type with automatic validation
🔁	Retry & resilience	Exponential backoff, jitter, status code filtering
💻	CLI	agentx init / agentx run / agentx config

Quick Start

pip install agentx

Hello World (5 lines)

import asyncio
from agentx import Agent, Runner

agent = Agent(name="assistant", model="claude-sonnet-4-6")
result = asyncio.run(Runner.run(agent, "Hello, tell me about yourself"))
print(result.final_output)

Agent with Tools

from agentx import Agent, Runner
from agentx.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"{city}: Sunny, 25°C"

agent = Agent(
    name="weather-bot",
    model="claude-sonnet-4-6",  # or "gpt-4o", "gemini-2.0-flash", ...
    tools=[get_weather],
)

result = await Runner.run(agent, "What's the weather in Beijing?")

Multi-Agent Collaboration

researcher = Agent(name="researcher", tools=[search])
writer = Agent(name="writer", tools=[])

researcher.handoffs = [writer]  # researcher → writer handoff
writer.handoffs = [researcher]  # writer → researcher handoff

result = await Runner.run(researcher, "Research AI agents and write a report")

Streaming

async for event in Runner.stream(agent, "Tell me a story"):
    if hasattr(event, "delta"):
        print(event.delta, end="", flush=True)

Supported Models

Provider	Models	Env Variable
ClaudeProvider	claude-sonnet-4-6, claude-opus-4, ...	ANTHROPIC_API_KEY
OpenAIProvider	gpt-4o, o3-mini, ...	OPENAI_API_KEY
GeminiProvider	gemini-2.0-flash, ...	GOOGLE_API_KEY
OllamaProvider	ollama/llama3.2, ...	(local, no key)
DeepSeekProvider	deepseek-chat, ...	DEEPSEEK_API_KEY
LiteLLMProvider	100+ models	(varies)

Switch models with a single string — no code changes needed:

agent = Agent(name="bot", model="claude-sonnet-4-6")  # Claude
agent = Agent(name="bot", model="gpt-4o")             # OpenAI
agent = Agent(name="bot", model="gemini-2.0-flash")    # Gemini
agent = Agent(name="bot", model="ollama/llama3.2")     # Local

Architecture

agentx/
├── loop/           # Agent execution engine (Runner, Agent, LoopGuard, Retry)
├── providers/      # Model adapters (Claude, OpenAI, Gemini, Ollama, DeepSeek, LiteLLM)
├── tools/          # Tool system (@tool decorator, Schema, Executor)
├── guardrails/     # Safety guardrails (PII, SQL injection, keywords, path traversal)
├── state/          # State management (LLM compression, SQLite/Redis checkpoints)
├── handoffs/       # Multi-agent coordination (HandoffConfig, Tracker)
├── streaming/      # Streaming output (StreamingRunner, Buffer)
├── tracing/        # Observability (Cost, Spans, Metrics)
├── computer_use/   # Desktop automation (Interface, Platforms, Adapters)
├── mcp/            # MCP client (stdio, HTTP+SSE)
├── cli/            # CLI tools (init, run, config)
└── types.py        # Shared type definitions

CLI

agentx init my-project -t tools --model claude   # Scaffold a project
agentx run agent.py --input "Hello"              # Run an agent
agentx run agent.py -i                           # Interactive mode
agentx run agent.py -s --input "Search AI news"  # Streaming mode

Optional Dependencies

pip install agentx[tracing]              # OpenTelemetry
pip install agentx[redis]                # Redis checkpoints
pip install agentx[mcp]                  # MCP support
pip install agentx[litellm]              # LiteLLM (100+ models)
pip install agentx[computer-use-browser] # Browser automation (Playwright)
pip install agentx[computer-use-mac]     # macOS automation (PyAutoGUI)

Documentation

📖 English | 中文文档

Topic	EN	中文
Getting Started	Link	链接
Core Concepts	Link	链接
Tools	Link	链接
Multi-Agent	Link	链接
Guardrails	Link	链接
Models	Link	链接
Streaming	Link	链接
State Management	Link	链接
Computer Use	Link	链接
MCP Integration	Link	链接
Observability	Link	链接
CLI	Link	链接
API Reference	Link	链接
Architecture	Link	链接
Contributing	Link	链接

Development

git clone https://github.com/PM-Shawn/AgentX.git
cd AgentX
uv sync                                            # Install dependencies
uv run pytest tests/ --ignore=tests/integration -q  # Run tests (378 passed)
uv run agentx --version                             # Verify CLI

Tech Stack

• Python ≥ 3.11
• Core: anthropic, openai, pydantic, aiosqlite, click
• Testing: pytest + pytest-asyncio (378 tests, 100% core path coverage)

License

MIT

---

特性

AgentX 是一个 Python AI Agent 框架。一次编写，自由切换模型 — Claude、OpenAI、Gemini、Ollama、DeepSeek，以及 100+ 模型（通过 LiteLLM）。

	特性	说明
🔄	模型无关	Claude / GPT / Gemini / Ollama / DeepSeek / LiteLLM，一行切换
🛠	函数工具	@tool 装饰器，自动参数推导 + JSON Schema 生成
🤝	多 Agent	Handoff 协作、Agent-as-Tool 委派、乒乓循环检测
🛡	安全护栏	输入/输出/工具三层护栏，内置 PII、SQL 注入、路径遍历检测
💾	状态管理	LLM 压缩 + SQLite/Redis 检查点持久化
⚡	流式输出	异步事件流，逐 token 输出
🖥	Computer Use	浏览器/桌面自动化，支持 Claude/OpenAI CUA/通用视觉适配器
🔌	MCP 支持	Model Context Protocol 客户端（stdio / HTTP+SSE）
📊	可观测性	OpenTelemetry 追踪 + Prometheus 指标 + 成本估算
🎯	结构化输出	Pydantic output_type 自动验证
🔁	重试韧性	指数退避、随机抖动、状态码过滤
💻	CLI 工具	agentx init / agentx run / agentx config

快速开始

pip install agentx

import asyncio
from agentx import Agent, Runner

agent = Agent(name="assistant", model="claude-sonnet-4-6")
result = asyncio.run(Runner.run(agent, "你好，介绍一下你自己"))
print(result.final_output)

完整中文文档 → docs/zh/README.md