PyAgents

A lightweight, Pythonic framework for building AI agents.

Build intelligent agents with tool use, memory, planning, and multi-agent orchestration — in just a few lines of code.

Why PyAgents?

Existing agent frameworks are either too complex (LangChain) or too limited. PyAgents hits the sweet spot:

• 5-line quickstart — Get a working agent running immediately
• Decorator-based tools — @tool decorator with auto-generated schemas from type hints
• Async-first — Native async/await for concurrent tool execution
• Pluggable everything — Swap LLM backends, memory, planners without changing agent code
• Multi-agent teams — Orchestrate agents working sequentially, in parallel, or with routing
• Built-in guardrails — Cost limits, content filtering, and output validation
• Zero lock-in — Works with OpenAI, Anthropic, or any OpenAI-compatible API

Installation

# Core (no LLM backend)
pip install pyagents-ai

# With OpenAI support
pip install pyagents-ai[openai]

# With Anthropic support
pip install pyagents-ai[anthropic]

# Everything
pip install pyagents-ai[all]

Quick Start

1. Your First Agent (5 lines)

import asyncio
from pyagents import Agent, tool
from pyagents.llm.openai import OpenAIBackend

@tool(description="Add two numbers together")
def add(a: int, b: int) -> int:
    return a + b

@tool(description="Multiply two numbers")
def multiply(a: int, b: int) -> int:
    return a * b

agent = Agent(
    llm=OpenAIBackend(model="gpt-4o"),
    tools=[add, multiply],
    system_prompt="You are a helpful math assistant. Use tools for calculations.",
)

result = asyncio.run(agent.run("What is (12 + 8) * 3?"))
print(result.output)
# → "The result of (12 + 8) × 3 is 60."

2. Using Anthropic Claude

from pyagents import Agent
from pyagents.llm.anthropic import AnthropicBackend

agent = Agent(
    llm=AnthropicBackend(model="claude-sonnet-4-20250514"),
    system_prompt="You are a helpful assistant.",
)

result = asyncio.run(agent.run("Explain quantum computing in simple terms."))
print(result.output)

3. Tools with Async Support

import httpx
from pyagents import tool

@tool(description="Fetch the content of a webpage")
async def fetch_url(url: str) -> str:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text[:2000]

@tool(description="Search for information on a topic")
async def web_search(query: str, max_results: int = 3) -> str:
    # Your search implementation here
    return f"Results for: {query}"

4. Multi-Agent Teams

from pyagents import Agent, Orchestrator, TeamConfig
from pyagents.orchestrator import DelegationStrategy

researcher = Agent(
    llm=llm,
    name="Researcher",
    tools=[web_search],
    system_prompt="You research topics thoroughly and provide detailed findings.",
)

writer = Agent(
    llm=llm,
    name="Writer",
    system_prompt="You write clear, engaging content based on research provided to you.",
)

team = Orchestrator(
    agents=[researcher, writer],
    config=TeamConfig(
        name="Content Team",
        strategy=DelegationStrategy.SEQUENTIAL,
        shared_context=True,
    ),
)

result = asyncio.run(team.run("Write a blog post about the future of AI agents"))
print(result.final_output)

5. Guardrails

from pyagents import Agent, CostGuardrail, ContentGuardrail

agent = Agent(
    llm=llm,
    guardrails=[
        CostGuardrail(max_tokens=100_000, max_cost_usd=1.0),
        ContentGuardrail(
            blocked_terms=["password", "secret_key"],
            redact=True,  # Replaces with [REDACTED] instead of raising error
        ),
    ],
)

6. Memory

from pyagents import Agent
from pyagents.memory.sqlite import SQLiteMemory

# Persistent memory across sessions
agent = Agent(
    llm=llm,
    memory=SQLiteMemory(db_path="my_agent_memory.db"),
    system_prompt="You remember previous conversations.",
)

# First conversation
await agent.run("My name is Abhishek and I work in finance.")

# Later conversation — agent remembers!
result = await agent.run("What do you know about me?")
# → "You told me your name is Abhishek and you work in finance."

7. Observability & Logging

from pyagents.logging import setup_logging, ExecutionTracer
import logging

# Enable colored console logging
setup_logging(level=logging.DEBUG)

# Or JSON logging for production
setup_logging(json_mode=True)

# Trace execution
tracer = ExecutionTracer()
with tracer.span("agent_run", agent="my_agent"):
    result = await agent.run("Do something complex")

print(tracer.report())
# → {"total_duration_ms": 1234.56, "spans": [...], "span_count": 1}

Architecture

pyagents/
├── agent.py          # Core Agent class with run loop
├── tools.py          # @tool decorator & ToolRegistry
├── orchestrator.py   # Multi-agent orchestration
├── guardrails.py     # Input/output validation & cost limits
├── logging.py        # Structured logging & tracing
├── llm/
│   ├── base.py       # Abstract LLM backend interface
│   ├── openai.py     # OpenAI / GPT backend
│   └── anthropic.py  # Anthropic / Claude backend
├── memory/
│   ├── base.py       # Abstract memory interface
│   ├── local.py      # In-memory storage
│   └── sqlite.py     # SQLite persistent storage
└── planner/
    ├── base.py       # Abstract planner interface
    └── react.py      # ReAct & Plan-and-Execute strategies

Roadmap

• Streaming responses
• Built-in tool library (web search, file I/O, code execution)
• Redis memory backend
• Embedding-based semantic memory
• OpenTelemetry integration
• Agent-to-agent communication protocol
• Web UI dashboard for monitoring
• LiteLLM backend for 100+ model providers

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/abhishekjain/pyagents.git
cd pyagents

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src/
mypy src/

License

MIT License — see LICENSE for details.