AgentForge SDK

A professional AI Agent development framework with configuration-as-code, dynamic Skills, MCP integration, and multi-agent orchestration.

Features

• Configuration-as-Code: Define agents with JSON/YAML configuration files validated by Pydantic v2
• Dynamic Skills System: Modular skills with auto-activation, discovery, and hot-reload
• MCP Integration: Full Model Context Protocol support with client, server manager, and elicitation
• Multi-Agent Swarm: Orchestrate multiple agents with routing, load balancing, and circuit breakers
• Integrated Debugging: Breakpoints, snapshots, replay, hot-reload, and visualization
• Deployment Tools: Packaging, registry, orchestration, and monitoring
• Multiple Providers: Built-in support for Anthropic, OpenAI, and custom providers
• Event-Driven Architecture: Powerful event bus for agent lifecycle and communication

Installation

Prerequisites: Python 3.12+ and uv

# Install uv (if not already installed)
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

Install AgentForge:

# Clone the repository
git clone https://github.com/AstroAir/agentforge.git
cd agentforge

# Install dependencies
uv sync --all-groups

Optional dependencies:

# Full installation (FastAPI server)
uv pip install agentforge[full]

# Swarm features (Redis, monitoring)
uv pip install agentforge[swarm]

# Monitoring only
uv pip install agentforge[monitoring]

Quick Start

1. Initialize a new project

agentforge init my-agent
cd my-agent

This creates:

my-agent/
├─ agent.json      # Agent configuration
├─ launch.json     # Launch configuration
├─ debug.json      # Debug configuration
├─ prompts/
│  └─ system.md    # System prompt
├─ skills/         # Custom skills
├─ mcp/            # MCP server configs
└─ tests/          # Tests

2. Configure your agent

Edit agent.json:

{
    "id": "my-agent",
    "name": "My Agent",
    "version": "0.1.0",
    "model": {
        "provider": "anthropic",
        "name": "claude-sonnet-4-20250514",
        "parameters": {
            "temperature": 0.7
        }
    },
    "prompts": {
        "system": "You are a helpful AI assistant."
    }
}

3. Run the agent

# Interactive CLI
agentforge run

# With specific skills
agentforge run --skill web-search --skill code-analysis

4. Use programmatically

import asyncio
from agentforge import Agent

async def main():
    # Load agent from config
    agent = Agent("agent.json")
    await agent.start()
    
    # Create a session
    session = agent.create_session()
    
    # Chat with streaming
    async for chunk in session.stream("Hello, AgentForge!"):
        print(chunk, end="", flush=True)
    
    await agent.stop()

asyncio.run(main())

Core Concepts

Agent Configuration

Agents are configured via JSON files with Pydantic validation:

from agentforge import AgentConfig, load_config

config = load_config("agent.json", AgentConfig)
print(config.model.provider)  # "anthropic"

Skills System

Skills are modular capabilities that can be dynamically loaded:

from agentforge import SkillManager, Skill

# Create skill manager
manager = SkillManager()

# Discover and load skills
await manager.discover("./skills")
await manager.activate("web-search")

# Get active skills
active = manager.get_active_skills()

MCP Integration

Full Model Context Protocol support:

from agentforge import MCPClient, MCPServerManager

# Connect to MCP servers
manager = MCPServerManager()
await manager.add_server("filesystem", {"command": "npx", "args": ["-y", "@anthropic/mcp-filesystem"]})

# Use MCP client
client = MCPClient()
tools = await client.list_tools()

Multi-Agent Swarm

Orchestrate multiple agents:

from agentforge import Swarm, Router

# Create swarm with routing
swarm = Swarm()
swarm.add_agent("specialist", specialist_agent)
swarm.add_agent("support", support_agent)

# Route messages intelligently
router = Router(swarm)
result = await router.route("I need technical help")

Debugging

Built-in debugging tools:

from agentforge import Debugger, BreakpointManager

debugger = Debugger()

# Set breakpoints
debugger.breakpoints.add("before_model_call")
debugger.breakpoints.add("after_tool_execution")

# Take snapshots
snapshot = debugger.snapshot()

# Replay sessions
await debugger.replay(session_id="abc123")

Project Structure

agentforge/
├─ src/agentforge/
│  ├─ cli/           # Command-line interface
│  ├─ config/        # Configuration schemas and loader
│  ├─ core/          # Core types, events, exceptions
│  ├─ runtime/       # Agent, Session, Memory, Providers
│  ├─ skills/        # Skills manager, loader, discovery
│  ├─ mcp/           # MCP client, server manager, auth
│  ├─ swarm/         # Router, Swarm, Communicator, Load balancer
│  ├─ debug/         # Debugger, Evaluator, Hot-reload, Replay
│  └─ deploy/        # Packager, Registry, Orchestrator
├─ examples/         # Example agents and configs
├─ tests/            # Test suite
└─ docs/             # Documentation

CLI Commands

agentforge init [path]        # Initialize new project
agentforge run                # Run agent interactively
agentforge run --skill <id>   # Run with specific skills
agentforge deploy             # Deploy agent
agentforge skill list         # List available skills
agentforge skill install <id> # Install a skill

Development

# Format code
uv run black .

# Lint
uv run ruff check .

# Type-check
uv run mypy .

# Run tests
uv run pytest -q

# Build package
uv build

# Serve docs locally
uv run mkdocs serve -a localhost:8000

Documentation

• Getting Started: docs/getting-started.md
• API Reference: docs/api.md
• Architecture: llmdoc/architecture/
• Guides: llmdoc/guides/

Build and serve documentation:

uv run mkdocs build --strict
uv run mkdocs serve -a localhost:8000

Contributing

See CONTRIBUTING.md for guidelines. Issues and PRs are welcome.

License

MIT — see LICENSE.