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, mock, 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

agentforge init now generates a runnable scaffold that uses the built-in mock provider, so you can start the project locally without setting API keys first.

Default agent.json:

{
    "id": "my-agent",
    "name": "My Agent",
    "version": "0.1.0",
    "description": "An AI agent built with AgentForge",
    "model": {
        "provider": "mock",
        "name": "mock-model",
        "parameters": {
            "temperature": 0.7
        }
    },
    "prompts": {
        "system": "./prompts/system.md"
    }
}

When you are ready to connect a real model, replace mock with anthropic or openai and add the required credentials.

3. Run the agent

# Interactive CLI
agentforge run

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

4. Use programmatically

from agentforge import Agent

import asyncio


async def main():
    agent = Agent("agent.json")
    await agent.start()

    session = agent.create_session()
    result = await session.chat("Hello, AgentForge!")
    print(result.response)

    await agent.stop()


asyncio.run(main())

Core Concepts

Agent Configuration

Agents are configured via JSON files with Pydantic validation:

from agentforge import load_config

config = load_config("agent.json")
print(config.model.provider)  # "mock"

Skills System

Skills are modular capabilities that can be dynamically loaded:

from agentforge import SkillManager

manager = SkillManager(
    skills_config=["./skills/web-search"],
    base_path=".",
    auto_activate=True,
)

await manager.load_all()
await manager.activate("web-search")

active = manager.get_active_skills()

MCP Integration

Full Model Context Protocol support:

from agentforge import MCPServerManager

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

tools = manager.client.list_tools() if manager.client else []

Multi-Agent Swarm

Orchestrate multiple agents:

from agentforge import Swarm

swarm = Swarm("swarm.json")
await swarm.start()

result = await swarm.handle_request("I need technical help", session_id="demo-session")
print(result["response"])

await swarm.stop()

Debugging

Built-in debugging tools:

from agentforge import Debugger, BreakpointManager

debugger = Debugger()

# Set breakpoints
debugger.add_breakpoint("before_model_call")
debugger.add_breakpoint("after_tool_call")

# Take snapshots
snapshot_id = debugger.save_snapshot("checkpoint", agent_id="agent-1", session_id="s1", state={})

# Inspect saved replays
replays = debugger.list_replays()

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 create <name> # Create a new 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.