ag2

📚 Documentation | 💡 Playground | 💡 Examples | 🤝 Contributing | 📝 Cite paper | 💬 Join Discord | 🏛️ AG2 Classic

AG2: Open-Source AgentOS for AI Agents

AG2 is an open-source programming framework for building AI agents and facilitating cooperation among multiple agents to solve tasks. AG2 aims to streamline the development and research of agentic AI. It offers features such as agents capable of interacting with each other, facilitates the use of various large language models (LLMs) and tool use support, autonomous and human-in-the-loop workflows, and multi-agent conversation patterns.

The project is currently maintained by a dynamic group of volunteers from several organizations. Contact project administrators Chi Wang and Qingyun Wu via [email protected] if you are interested in becoming a maintainer.

Table of contents

• AG2: Open-Source AgentOS for AI Agents
  • Table of contents
  • AG2 Classic (the autogen.* namespace)
  • Getting started
    • Installation
    • Setup your API keys
    • Run your first agent
  • Example applications
  • Introduction of different agent concepts
    • Agents
    • Tools
    • Human in the Loop
    • Orchestrating Multiple Agents
    • The agent harness: knowledge and compaction
    • Advanced agentic design patterns
  • Code style and linting
  • Contributors Wall
  • License

AG2 Classic (the autogen.* namespace)

AG2 Classic is the original AutoGen-derived framework: the autogen.* import namespace and its agent classes — ConversableAgent, AssistantAgent, UserProxyAgent, GroupChat / GroupChatManager, swarms, register_function, LLMConfig / OAI_CONFIG_LIST, and the nested- and sequential-chat patterns.

It now lives in its own repository and has its own documentation site:

Are you using AG2 Classic?

If any of the following appear in your code, you are on Classic — stay on it, and use classic.docs.ag2.ai:

import autogen  # the autogen.* namespace
from autogen import ConversableAgent, GroupChat  # classic agent classes
from autogen import AssistantAgent, UserProxyAgent

Classic remains maintained and installable. Your existing code keeps working — pin the classic distribution instead of ag2>=1.0:

pip install ag2-classic

The rest of this README covers AG2 v1.0 (import ag2).

Getting started

For a step-by-step walk through of AG2 concepts and code, see the Quick Start in our documentation.

Installation

AG2 requires Python version >= 3.11. AG2 is available as ag2 on PyPI.

Windows/Linux:

pip install ag2[openai]

Mac:

pip install 'ag2[openai]'

Minimal dependencies are installed by default. Install the extra that matches your model provider — ag2[openai], ag2[anthropic], ag2[gemini], ag2[ollama], and so on.

Setup your API keys

Each provider config reads its standard environment variable, so keys never need to be hardcoded or checked in:

export OPENAI_API_KEY="<your-api-key>"     # or ANTHROPIC_API_KEY, GEMINI_API_KEY, ...

You can also pass a key explicitly with OpenAICompletionsConfig(model="gpt-4o-mini", api_key=...) — useful when each request brings its own key.

Run your first agent

AG2 is async throughout. Agent.ask(...) starts a turn and returns an AgentReply; the text is in reply.body.

import asyncio

from ag2 import Agent
from ag2.config import OpenAICompletionsConfig

agent = Agent(
    "assistant",
    prompt="You are a helpful assistant.",
    config=OpenAICompletionsConfig(model="gpt-4o-mini"),
)


async def main() -> None:
    reply = await agent.ask("Summarize the main differences between Python lists and tuples.")
    print(reply.body)


asyncio.run(main())

Example applications

We maintain both a live playground and a dedicated repository with a wide range of applications to help you get started with various use cases, and a set of runnable code examples in the documentation.

• AG2 Playground
• Build with AG2
• Code Examples

Introduction of different agent concepts

We have several agent concepts in AG2 to help you build your AI agents. We introduce the most common ones here.

• Agents: Agent is the core building block — it talks to a model provider, calls tools, and returns a reply.
• Tools: Plain Python functions, decorated with @tool, that the agent can invoke.
• Human in the loop: Pause a run to collect confirmation or missing information from a person.
• Orchestrating multiple agents: Coordinate several agents over a hub and typed channels using the Network.
• The agent harness: Opt-in primitives layered onto an agent — persistent knowledge, context assembly, and history compaction.
• Advanced Concepts: Structured outputs, middleware, observers, telemetry, evaluation, and more.

Agents

The Agent is the fundamental building block of AG2. ask() runs a turn; calling ask() on the returned reply continues the same conversation, preserving its history.

import asyncio

from ag2 import Agent
from ag2.config import OpenAICompletionsConfig

reviewer = Agent(
    "reviewer",
    prompt=(
        "You are a code reviewer. Analyze the provided code and suggest improvements. "
        "Do not generate code, only suggest improvements."
    ),
    config=OpenAICompletionsConfig(model="gpt-4o-mini"),
)


async def main() -> None:
    reply = await reviewer.ask("def fib(n): return n if n < 2 else fib(n-1) + fib(n-2)")
    print(reply.body)

    # Continue the same conversation — prior turns stay in scope.
    follow_up = await reply.ask("Which of those matters most for large n?")
    print(follow_up.body)


asyncio.run(main())

Tools

Agents gain significant utility through tools, which extend their capabilities with external data, APIs, or functions. Decorate a Python function with @tool and pass it to the agent — AG2 runs the full tool-calling loop: the model decides when to call it, AG2 executes it, and the result is fed back.

import asyncio
from datetime import datetime

from ag2 import Agent, tool
from ag2.config import OpenAICompletionsConfig


@tool
async def get_weekday(date_string: str) -> str:
    """Get the day of the week for a given date, formatted as YYYY-MM-DD."""
    return datetime.strptime(date_string, "%Y-%m-%d").strftime("%A")


date_agent = Agent(
    "date_agent",
    prompt="You find the day of the week for a given date.",
    config=OpenAICompletionsConfig(model="gpt-4o-mini"),
    tools=[get_weekday],
)


async def main() -> None:
    reply = await date_agent.ask("I was born on 1995-03-25, what day was it?")
    print(reply.body)


asyncio.run(main())

Human in the Loop

Human oversight is often essential for validating or guiding AI outputs. Call context.input(...) inside a tool to pause the run and ask a person — your hitl_hook decides how that question is answered (CLI prompt, web UI, queue, …).

import asyncio

from ag2 import Agent, Context, tool
from ag2.config import OpenAICompletionsConfig
from ag2.events import HumanInputRequest, HumanMessage


@tool
async def publish_lesson_plan(context: Context, plan: str) -> str:
    """Publish a lesson plan, once a human educator has approved it."""
    answer = await context.input(f"Approve this lesson plan?\n\n{plan}")
    if answer.strip().lower().startswith("y"):
        return "Published."
    return f"Rejected by the educator: {answer}"


def hitl_hook(event: HumanInputRequest) -> HumanMessage:
    # Block here for real input — a CLI prompt, a web UI, a queue.
    return HumanMessage(content=input(f"{event.content}\n> "))


teacher = Agent(
    "teacher",
    prompt=(
        "Draft a short lesson plan, then call the publish_lesson_plan tool to have it published. "
        "Approval is collected by the tool — never ask for approval in plain text."
    ),
    config=OpenAICompletionsConfig(model="gpt-4o-mini"),
    tools=[publish_lesson_plan],
    hitl_hook=hitl_hook,
)


async def main() -> None:
    reply = await teacher.ask("Let's introduce our kids to the solar system.")
    print(reply.body)


asyncio.run(main())

Orchestrating Multiple Agents

When two or more agents need to work together, AG2 uses the Network: a Hub that owns the registry, the write-ahead log, and the audit trail, with agents talking over typed channels. This replaces the classic GroupChat / swarm / nested-chat patterns.

Here a conversation channel — a free-form two-party session where either side may speak at any time — connects a planner and a reviewer:

import asyncio

from ag2 import Agent
from ag2.config import OpenAICompletionsConfig
from ag2.knowledge import MemoryKnowledgeStore
from ag2.network import EV_TEXT, Hub

MAX_MESSAGES = 4


async def wait_for_messages(hub: Hub, channel_id: str, expected: int, timeout: float = 120.0) -> None:
    """Poll the hub's write-ahead log until `expected` messages have been exchanged."""
    deadline = asyncio.get_event_loop().time() + timeout
    while asyncio.get_event_loop().time() < deadline:
        wal = await hub.read_wal(channel_id)
        if sum(1 for e in wal if e.event_type == EV_TEXT) >= expected:
            return
        await asyncio.sleep(0.05)
    raise TimeoutError(f"only reached {expected} messages before timing out")


async def main() -> None:
    config = OpenAICompletionsConfig(model="gpt-4o-mini")
    hub = await Hub.open(MemoryKnowledgeStore(), ttl_sweep_interval=0)

    planner = await hub.register(
        Agent("planner", prompt="You plan school lessons. Reply in one short sentence.", config=config),
    )
    reviewer = await hub.register(
        Agent("reviewer", prompt="You critique lesson plans. Reply in one short sentence.", config=config),
    )

    # Free-form 2-party channel: either side may speak at any time.
    channel = await planner.open(type="conversation", target="reviewer")
    await channel.send("What should a fourth-grade solar system lesson lead with?", audience=[reviewer.agent_id])

    # Both default handlers reply to every inbound message, so the conversation
    # auto-drives. `conversation` never auto-closes — we bound it and close it.
    await wait_for_messages(hub, channel.channel_id, expected=MAX_MESSAGES)
    await channel.close()

    # Replay the exchange from the hub's write-ahead log.
    names = {planner.agent_id: "planner", reviewer.agent_id: "reviewer"}
    for envelope in await hub.read_wal(channel.channel_id):
        if envelope.event_type == EV_TEXT:
            print(f"{names[envelope.sender_id]}: {envelope.event_data['text']}")

    await hub.close()


asyncio.run(main())

Channels come in several shapes — conversation (free-form, two parties), consulting (strict one-question-one-reply, auto-closing), discussion (round-robin across N agents), and workflow (a declarative TransitionGraph for conditional handoffs, which is the closest analogue to a classic GroupChat). See the Network guide.

The agent harness: knowledge and compaction

A bare Agent is just a model loop. The harness is the set of opt-in primitives you compose onto it. Two of the most useful:

• KnowledgePlugin — a KnowledgeStore the agent can read and write, so it remembers across runs.
• compact= — a strategy that caps history growth. SummarizeCompact folds the dropped turns into a summary rather than discarding them outright.

Pair the store with a WorkingMemoryPolicy through AssemblerMiddleware and the agent’s memory is injected into the system prompt on every turn — recall no longer depends on the model choosing to look it up.

import asyncio
from pathlib import Path

from ag2 import Agent, MemoryStream
from ag2.assembly import AssemblerMiddleware
from ag2.compact import CompactTrigger, SummarizeCompact
from ag2.config import OpenAICompletionsConfig
from ag2.events import CompactionCompleted, CompactionFailed
from ag2.knowledge import KnowledgePlugin, DiskKnowledgeStore
from ag2.middleware import Middleware
from ag2.policies import WorkingMemoryPolicy

config = OpenAICompletionsConfig(model="gpt-4o-mini")

# Disk-backed, so anything the agent remembers survives the process exiting.
STORE_DIR = Path("./knowledge_demo")
store = DiskKnowledgeStore(STORE_DIR)

agent = Agent(
    "tutor",
    prompt=(
        "You are a science tutor for a fourth-grade teacher. "
        "Whenever you learn a durable fact about the teacher or their class, use the knowledge "
        "tool to `read` `memory/working.md`, then `write` it back with the new fact appended as "
        "a bullet. Never drop a fact that is already there. "
        "Keep every reply to one or two sentences."
    ),
    config=config,
    plugins=[
        KnowledgePlugin(
            store=store,
            # Summarize the dropped history instead of forgetting it outright.
            compact=SummarizeCompact(target=4, config=config),
            compact_trigger=CompactTrigger(max_events=8),
        )
    ],
    # Injects memory/working.md into the system prompt on every turn, so recall
    # does not depend on the model choosing to call the knowledge tool.
    middleware=[Middleware(AssemblerMiddleware, policies=[WorkingMemoryPolicy()])],
)

stream = MemoryStream()


# Subscribe to both outcomes — watching only Completed would hide a failing strategy.
@stream.where(CompactionCompleted).subscribe()
async def on_compacted(event: CompactionCompleted) -> None:
    print(f"  [compacted: {event.events_before} -> {event.events_after} events via {event.strategy}]")


@stream.where(CompactionFailed).subscribe()
async def on_compaction_failed(event: CompactionFailed) -> None:
    print(f"  [compaction FAILED: {event.strategy}]")


async def main() -> None:
    # A returning session: no conversation history at all, so anything the agent
    # recalls here came off disk, via the knowledge store.
    if STORE_DIR.exists():
        reply = await agent.ask("What do you remember about me and my class?", stream=stream)
        print(f"tutor: {reply.body}")
        return

    reply = await agent.ask("I'm Dana. I teach 4th grade at Rosewood Elementary, 26 students.", stream=stream)
    print(f"tutor: {reply.body}")

    for turn in ["My class struggles most with why we have seasons.", "Suggest one hands-on demo for that."]:
        reply = await reply.ask(turn)
        print(f"tutor: {reply.body}")


asyncio.run(main())

Run it twice. The first run fills memory/working.md and trips compaction; the second starts with an empty history and still knows who Dana is:

  [compacted: 18 -> 3 events via SummarizeCompact]
tutor: I remember that you, Dana, teach 4th grade at Rosewood Elementary with 26 students,
       and your class struggles the most with understanding why we have seasons.

See the Agent Harness guide for context policies, delegation, aggregation, and the full turn lifecycle.

Advanced agentic design patterns

AG2 supports more advanced concepts to help you build your AI agent workflows. You can find more information in the documentation.

• Structured Output
• Multi-Agent Network
• Knowledge & Memory
• Middleware
• Telemetry
• Evaluation
• Testing

Code style and linting

This project uses prek hooks to maintain code quality. Before contributing:

1. Install prek:

pip install prek
prek install

2. The hooks will run automatically on commit, or you can run them manually:

prek run --all-files

Contributors Wall

License

This project is licensed under the Apache License, Version 2.0 (Apache-2.0).

• Modifications and additions made in this fork are licensed under the Apache License, Version 2.0. See the LICENSE file for the full license text.

We have documented these changes for clarity and to ensure transparency with our user and contributor community. For more details, please see the NOTICE file.