AgentForge

Project Introduction / 项目介绍

English: AgentForge is a modular, extensible framework for building and orchestrating AI agents. It provides clean abstractions for agents, tools, memory, LLM providers, and multi-agent coordination, so developers can assemble production-minded agent workflows with minimal boilerplate.

中文： AgentForge 是一个模块化、可扩展的 AI 智能体构建与编排框架。它为智能体、工具、记忆系统、LLM 提供商和多智能体协作提供清晰抽象，帮助开发者用较少样板代码搭建面向实际应用的智能体工作流。

Features

• Modular Agent System — Build agents with composable tools, memory, and LLM backends
• Extensible Tool Framework — Easy-to-write tools with automatic parameter validation
• Flexible Memory — Short-term (in-memory buffer) and long-term (file-persisted) storage
• Multi-Agent Orchestration — Sequential, parallel, and hierarchical coordination patterns
• Multiple LLM Providers — Built-in support for Claude (Anthropic) and OpenAI
• CLI Interface — Interactive and headless modes for running agents from the terminal
• Minimal Dependencies — Lightweight core with optional provider packages

Quick Start

# Install from source
cd agentforge
pip install -e .

# With optional LLM providers:
pip install -e ".[claude]"    # For Claude / Anthropic
pip install -e ".[openai]"    # For OpenAI

Set your API key:

export ANTHROPIC_API_KEY=sk-...   # for Claude
# or
export OPENAI_API_KEY=sk-...       # for OpenAI

Basic Usage

from agentforge.core.agent import Agent
from agentforge.llm.claude_provider import ClaudeProvider
from agentforge.tools import CalculatorTool

# Create an agent with a tool
agent = Agent(
    name="MathBot",
    role="a helpful math assistant",
    llm_provider=ClaudeProvider(),
    tools=[CalculatorTool()],
)

# Run a task
result = agent.run("Calculate the compound interest on $1000 at 5% for 3 years")
print(result)

Multi-Agent Research Team

from agentforge.core.agent import Agent
from agentforge.core.orchestrator import Orchestrator
from agentforge.llm.claude_provider import ClaudeProvider

researcher = Agent(name="Researcher", role="researcher", llm_provider=ClaudeProvider())
writer = Agent(name="Writer", role="technical writer", llm_provider=ClaudeProvider())
reviewer = Agent(name="Reviewer", role="reviewer", llm_provider=ClaudeProvider())

orchestrator = Orchestrator(agents=[researcher, writer, reviewer])
results = orchestrator.sequential("Research RAG advancements", ["Researcher", "Writer", "Reviewer"])

Architecture

┌──────────────────────────────────────────────┐
│               Orchestrator                    │
│   (sequential / parallel / hierarchical)      │
├──────────────────────────────────────────────┤
│                   Agent                       │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  Tools   │  │  Memory  │  │  LLM Prov. │  │
│  └──────────┘  └──────────┘  └────────────┘  │
└──────────────────────────────────────────────┘

Built-in Tools

Tool	Description
CalculatorTool	Safe evaluation of mathematical expressions using AST
FileOpsTool	Read, write, and list files within a workspace
WebSearchTool	Fetch web pages by URL (extensible to full search)
PythonExecutorTool	Execute Python code and capture stdout/stderr

Memory Systems

• ShortTermMemory — In-memory ring buffer with configurable turn limit
• LongTermMemory — File-based JSONL persistence for cross-session recall

LLM Providers

Provider	Package	Model Default
Claude	agentforge[claude]	claude-sonnet-4-20250514
OpenAI	agentforge[openai]	gpt-4o

CLI Usage

# Interactive chat session
agentforge interact

# Run a single task
agentforge run "What is the capital of France?"

# Run with custom agent name
agentforge run --name "Researcher" --role "research scientist" \
    "Summarise the latest advances in LLM reasoning"

# List available tools
agentforge tools

Configuration

AgentForge reads configuration from environment variables, JSON, or YAML files:

export AGENTFORGE_LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-...

Or create agentforge.yaml:

llm:
  provider: claude
  model: claude-sonnet-4-20250514
memory:
  type: long_term
  path: ./data/memory

Pass it with the --config flag:

agentforge --config agentforge.yaml run "Hello"

Custom Tools

from agentforge.tools.base_tool import BaseTool

class WeatherTool(BaseTool):
    def __init__(self):
        super().__init__(
            name="get_weather",
            description="Get current weather for a city",
            parameters={
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name"}
                },
                "required": ["city"],
            },
        )

    def execute(self, city: str) -> str:
        return f"Weather in {city}: 22°C, partly cloudy"

agent.register_tool(WeatherTool())

Running Tests

pip install pytest
pytest tests/

Project Structure

agentforge/
├── agentforge/
│   ├── core/          # Agent, Orchestrator, Config
│   ├── tools/         # Built-in tools
│   ├── memory/        # Memory backends
│   ├── llm/           # LLM providers
│   └── cli/           # CLI interface
├── examples/          # Usage examples
├── tests/             # Test suite
└── pyproject.toml     # Project metadata

License

MIT