AG2 Comprehensive Guide
AG2 1.x reference: Agent, model configs, tools, dependency injection, code execution, structured output, multimodal input, human-in-the-loop, events, middleware, knowledge and compaction, the multi-agent Network, MCP, A2A, agent specs and testing.
Verified against
ag21.3.2 (checked 2026-11-19). Every 1.x example on this page was executed offline against the installed package usingag2.testing.TestConfigin place of a real model. For the Classicimport autogenAPI, see AG2 Classic.
Overview
Section titled “Overview”AG2 began in November 2024 as the community fork of AutoGen 0.2, led by AutoGen’s original creators. Until mid-2026 it kept the AutoGen-style API (ConversableAgent, GroupChat, initiate_chat). AG2 1.0 replaced that with a new framework, previewed earlier as autogen.beta:
- Async throughout —
await agent.ask(...)returns anAgentReply. - Plain functions as tools — decorate with
@tool; dependency injection viaContext. - Typed events — every model call, tool call and human-input request is an event you can subscribe to on a
MemoryStream. - Network — a
Hubplus typed channels (conversation,consulting,discussion,workflow) replacesGroupChat, swarms and nested chats. - Interop — MCP servers as toolkits, agents served or consumed over A2A, AG-UI and ACP adapters.
What changed in 1.0
Section titled “What changed in 1.0”AG2 Classic (ag2 ≤ 0.14, autogen) | AG2 1.x (ag2 ≥ 1.0) | |
|---|---|---|
| Import | import autogen | import ag2 |
| Core agent | ConversableAgent, AssistantAgent, UserProxyAgent | Agent |
| Model config | LLMConfig / OAI_CONFIG_LIST dicts | Provider classes: OpenAIConfig, AnthropicConfig, GeminiConfig, … |
| Running | initiate_chat, generate_reply (sync) | await agent.ask(...), await reply.ask(...) |
| Tools | register_function(f, caller=..., executor=...) | @tool + Agent(tools=[...]) |
| Multi-agent | GroupChat / GroupChatManager, swarms, nested chats | ag2.network.Hub + channels, TransitionGraph |
| Human input | human_input_mode="ALWAYS" | await context.input(...) inside a tool + hitl_hook= |
| Testing | — | ag2.testing.TestConfig scripted model |
There is no compatibility shim: ag2>=1.0 does not ship the autogen package at all.
Installation and model configuration
Section titled “Installation and model configuration”pip install "ag2[openai]" # or ag2[anthropic], ag2[gemini], ag2[bedrock], ag2[ollama], ...pip install "ag2[openai]==1.3.2" # pinnedThe base install is deliberately small (pydantic, httpx, anyio, PyYAML and FastDepends); each provider and integration is an extra: openai, anthropic, gemini, bedrock, ollama, mistral, xai, zai, dashscope, typesafe, elevenlabs, plus mcp, mcp-ui, a2a, a2ui, ag-ui, acp, redis, tavily, ddgs, perplexity, tracing, metrics. Importing something whose extra is missing raises an ImportError that names the extra to install.
Each provider has its own config class in ag2.config, which reads the provider’s standard environment variable when api_key is omitted:
| Provider | Config class | Key variable |
|---|---|---|
OpenAI Chat Completions (and compatible endpoints via base_url) | OpenAIConfig | OPENAI_API_KEY |
| OpenAI Responses API | OpenAIResponsesConfig | OPENAI_API_KEY |
| Anthropic | AnthropicConfig | ANTHROPIC_API_KEY |
| Gemini API / Vertex AI | GeminiConfig / VertexAIConfig | GEMINI_API_KEY / ADC |
| Amazon Bedrock | BedrockConfig | AWS credentials |
| Ollama, Mistral, xAI, Z.AI, DashScope, TypeSafe | OllamaConfig, MistralConfig, XAIConfig, ZAIConfig, DashScopeConfig, TypeSafeConfig | provider-specific |
from ag2.config import AnthropicConfig, GeminiConfig, OpenAIConfig
openai_cfg = OpenAIConfig(model="gpt-6-luna", temperature=0.2, streaming=True)local_cfg = OpenAIConfig(model="llama3.1", base_url="http://localhost:11434/v1", api_key="unused")claude_cfg = AnthropicConfig(model="claude-sonnet-5-5")gemini_cfg = GeminiConfig(model="gemini-3.8-flash", thinking_budget=1024)A config can be set on the agent and overridden per call (agent.ask(..., config=...)).
Your first agent
Section titled “Your first agent”import asyncio
from ag2 import Agentfrom ag2.config import OpenAIConfig
agent = Agent( "assistant", # name (positional) prompt="You are a helpful assistant.", config=OpenAIConfig(model="gpt-6-luna"),)
async def main() -> None: reply = await agent.ask("Summarise the difference between lists and tuples.") print(reply.body) # text of the final message
follow_up = await reply.ask("Which is hashable?") # same conversation, history kept print(follow_up.body)
asyncio.run(main())Agent.ask(...)starts a new conversation;AgentReply.ask(...)continues it.prompt=accepts a string, a callable returning a string (sync or async), or a list of either — useful for prompts built from runtime state.Agent.run(...)is the observable counterpart ofask: it returns anAgentRun, an async context manager you drive (run.start()orawait run.result()), watch (run.stream), and feed (run.enqueue(...)). See Streaming and observing a turn.agent.as_tool(description=...)turns an agent into a tool another agent can call (registered astask_<name>) — the simplest sub-agent pattern.
from datetime import datetime
from ag2 import Agent, toolfrom ag2.config import OpenAIConfig
@toolasync def get_weekday(date_string: str) -> str: """Get the day of the week for a date formatted as YYYY-MM-DD.""" return datetime.strptime(date_string, "%Y-%m-%d").strftime("%A")
@tool(description="Add two integers and return the sum.")def add(a: int, b: int) -> int: return a + b
agent = Agent( "date_agent", prompt="Answer date and arithmetic questions using your tools.", config=OpenAIConfig(model="gpt-6-luna"), tools=[get_weekday, add],)- The docstring (or
description=) and type hints become the tool schema. Sync and async functions both work. - AG2 runs the whole loop: the model requests a call, AG2 executes it and feeds the result back until the model produces a final answer.
- A parameter typed
Contextis injected rather than exposed to the model; it gives tools access tocontext.input(...)(human input), variables and dependencies. - Built-in tools live in
ag2.tools. They include web search and fetch (WebSearchTool,WebFetchTool,TavilySearchTool,DuckDuckSearchTool), local code and shell execution (SandboxCodeTool,SandboxShellTool; see Code execution),FilesystemToolkit, skills (SkillsToolkit) and MCP (MCPToolkit). - Some tools are provider-hosted: the model provider runs them on its own side. Examples are
WebSearchTool,CodeExecutionTool(the provider’s code sandbox) andShellTool(OpenAI’s hosted container via the Responses API; not supported on Anthropic). They only work with providers that support them.
Dependency injection and variables
Section titled “Dependency injection and variables”Tool parameters can be filled by AG2 instead of the model. Annotate them and they disappear from the tool schema:
Annotated[T, Inject()]takes the value fromdependencies=(on theAgentor perask), looked up by parameter name or byInject("name"). Use it for database clients, HTTP sessions and settings.Annotated[T, Variable()]takes the value fromvariables=, the per-conversation state (tools can change it throughcontext.variables).Annotated[T, Depends(factory)]callsfactory()(FastDepends-style) and passes the result.
import asynciofrom dataclasses import dataclassfrom typing import Annotated
from ag2 import Agent, Depends, Inject, Variable, toolfrom ag2.config import OpenAIConfig
@dataclassclass Database: balances: dict[str, float]
def get_currency() -> str: return "EUR"
@tooldef account_balance( account_id: str, # the only parameter the model sees db: Annotated[Database, Inject()], user_id: Annotated[str, Variable()], currency: Annotated[str, Depends(get_currency)],) -> str: """Return the balance of one of the current user's accounts.""" return f"{user_id}/{account_id}: {db.balances[account_id]:.2f} {currency}"
agent = Agent( "bank", prompt="Answer balance questions with your tool.", config=OpenAIConfig(model="gpt-6-luna"), tools=[account_balance], dependencies={"db": Database({"current": 120.5})},)
async def main() -> None: reply = await agent.ask("What is in my current account?", variables={"user_id": "u-42"}) print(reply.body)
asyncio.run(main())A Context parameter gives the same access programmatically (context.dependencies, context.variables).
Variable scopes across delegation
Section titled “Variable scopes across delegation”When an agent delegates through as_tool(), the worker receives a copy of the parent’s variables by default, so its changes are not seen by the parent. Declare a variable with ScopedValue(value, scope) (Scope and ScopedValue are importable from ag2) to choose:
Scope.COPIED(the default): each delegate gets its own deep copy.Scope.SHARED: every agent in the delegation tree reads and writes the same binding. It can only be declared at the root agent, and there is no locking, so guard compound updates yourself.Scope.LOCAL: stays with the agent that declared it and is not passed on.
Redeclaring a variable with a different scope raises ScopeError.
import asyncio
from ag2 import Agent, Scope, ScopedValue, toolfrom ag2.annotations import Contextfrom ag2.events import ToolCallEventfrom ag2.testing import TestConfig
@tooldef spend(amount: int, context: Context) -> str: """Spend some of the budget.""" context.variables["spent"] += amount return "ok"
worker = Agent( "worker", config=TestConfig(ToolCallEvent(name="spend", arguments='{"amount": 5}'), "done"), tools=[spend],)lead = Agent( "lead", tools=[worker.as_tool(description="Do the work.")], variables={"spent": ScopedValue(0, Scope.SHARED)},)
reply = asyncio.run( lead.ask( "Go.", config=TestConfig(ToolCallEvent(name="task_worker", arguments='{"objective": "spend"}'), "Finished."), ))print(reply.context.variables["spent"]) # 5: the worker's change is visible to the parentCode execution
Section titled “Code execution”Two kinds of code tool exist, and they are not interchangeable:
| Tool | Where code runs | Works with |
|---|---|---|
SandboxCodeTool(environment), SandboxShellTool(environment) | Client-side, in the environment you pass: LocalEnvironment (a subprocess on your machine, no isolation), ag2.extensions.docker.DockerEnvironment (needs the docker package and a daemon), ag2.extensions.daytona.DaytonaEnvironment, ag2.extensions.e2b.E2BEnvironment (E2B cloud sandboxes) or ag2.extensions.boxd.BoxdEnvironment (the last two were added in 1.3.0; each needs its own SDK installed, and importing without it raises a missing-dependency error). I only checked that they import and are exported, not that they run against the services | Every provider |
CodeExecutionTool(), ShellTool() | Server-side, in the model provider’s sandbox | Only providers with native code execution or shell tools |
from ag2 import Agentfrom ag2.config import OpenAIConfigfrom ag2.tools import LocalEnvironment, SandboxCodeTool, SandboxShellTool
workspace = LocalEnvironment("./sandbox", timeout=30) # trusted code only; use DockerEnvironment otherwise
analyst = Agent( "analyst", prompt="Answer by running Python. Inspect files with the shell tool.", config=OpenAIConfig(model="gpt-6-luna"), tools=[ SandboxCodeTool(workspace, languages=("python",)), # exposes run_code(code, language) SandboxShellTool(workspace, allowed=["ls", "cat"], readonly=True), # exposes run_shell_command(command) ],)SandboxCodeTool has no default environment. It runs whatever the model writes, so you must choose the backend explicitly. SandboxShellTool takes its environment as an optional argument and also accepts allowed= / blocked= command lists and readonly=True. A command outside the allow-list is not run: the model receives a Command not allowed result instead. The tool names the model sees are run_code(code, language) and run_shell_command(command).
Structured output
Section titled “Structured output”from pydantic import BaseModel
from ag2 import Agentfrom ag2.config import OpenAIConfig
class TicketTriage(BaseModel): category: str # billing, bug, account_access urgency: str # low, medium, high
triage = Agent( "triage", prompt="You triage customer support messages. Be conservative with urgency.", config=OpenAIConfig(model="gpt-6-luna"), response_schema=TicketTriage,)
async def classify(text: str) -> TicketTriage: reply = await triage.ask(f"Classify this ticket:\n\n{text}") return await reply.content() # parsed and validated TicketTriagereply.body is always the raw text; await reply.content() parses it against the schema in force for that turn. response_schema accepts a plain type (int, a dataclass, a Pydantic model), a ResponseSchema(...) with an explicit name and description, a function decorated with @response_schema for custom parsing, or PromptedSchema(...) for models without native structured output.
Multimodal input
Section titled “Multimodal input”Pass inputs alongside the text in ask(...). ImageInput, DocumentInput, AudioInput and VideoInput accept a URL, path=, raw data= with a media_type=, or a provider file_id=:
from ag2 import Agent, DocumentInput, ImageInputfrom ag2.config import OpenAIConfig
agent = Agent("analyst", prompt="Describe what you are shown.", config=OpenAIConfig(model="gpt-6-luna"))
async def describe() -> None: reply = await agent.ask("What does this chart show?", ImageInput(path="chart.png")) print(reply.body) reply = await reply.ask("Does the report agree?", DocumentInput(url="https://example.com/q3-report.pdf")) print(reply.body)Support depends on the provider and model.
Human in the loop
Section titled “Human in the loop”from ag2 import Agent, Context, toolfrom ag2.config import OpenAIConfigfrom ag2.events import HumanInputRequest, HumanMessage
@toolasync def publish_plan(context: Context, plan: str) -> str: """Publish a lesson plan once a human has approved it.""" answer = await context.input(f"Approve this plan?\n\n{plan}") return "Published." if answer.strip().lower().startswith("y") else f"Rejected: {answer}"
def hitl_hook(event: HumanInputRequest) -> HumanMessage: # Replace with a web UI, queue or CLI prompt. return HumanMessage(content=input(f"{event.content}\n> "))
teacher = Agent( "teacher", prompt="Draft a short lesson plan, then call publish_plan. Never ask for approval in plain text.", config=OpenAIConfig(model="gpt-6-luna"), tools=[publish_plan], hitl_hook=hitl_hook,)The hook may be sync or async and may return a HumanMessage or a plain string. Tools that need approval before running can also be wrapped declaratively with the approval_required tool middleware from ag2.middleware.
Streaming and observing a turn
Section titled “Streaming and observing a turn”Set streaming=True on the provider config and the model’s text arrives as ModelMessageChunk events while the turn runs. A MemoryStream you pass to ask() lets you subscribe to them. The final ModelResponse still carries the complete text, and reply.body is unchanged.
import asyncio
from ag2 import Agent, MemoryStreamfrom ag2.config import OpenAIConfigfrom ag2.events import ModelMessageChunk, ModelResponse
agent = Agent("writer", prompt="Write one sentence.", config=OpenAIConfig(model="gpt-6-luna", streaming=True))
async def main() -> None: # 1. Subscribe to chunks on a stream you own. stream = MemoryStream()
@stream.where(ModelMessageChunk).subscribe() async def show(chunk: ModelMessageChunk) -> None: print(chunk.content, end="", flush=True)
reply = await agent.ask("Describe tea.", stream=stream) print("\nfinal:", reply.body)
# 2. Or open the turn as a scope and drive it yourself. async with agent.run("Describe coffee.") as run: seen: list[str] = []
@run.stream.where(ModelResponse).subscribe() async def on_response(event: ModelResponse) -> None: seen.append(type(event).__name__)
result = await run.result() # drives the turn; run.start() would drive it in the background print(result.body, seen)
asyncio.run(main())AgentRun owns the turn’s task: leaving the async with block cancels a turn that is still running, so await run.result() (or run.start() and then the result) inside the block. Subscribe before driving, because callbacks fire inline as events are published.
Messages you pass to run.enqueue(...) while a turn is running are folded into its next model call. If the turn ends without another model call (a final tool result, or calls handed to a client tool), the message stays queued for the next turn on that stream rather than being lost (behaviour as of 1.3.2).
Observing a turn with MemoryStream
Section titled “Observing a turn with MemoryStream”from ag2 import MemoryStreamfrom ag2.events import BaseEvent, ToolCallEvent
stream = MemoryStream()
@stream.subscribe()async def log_everything(event: BaseEvent) -> None: print(type(event).__name__)
@stream.where(ToolCallEvent).subscribe()async def on_tool_call(event: ToolCallEvent) -> None: print("tool requested:", event.name)
# reply = await agent.ask("What day was 1995-03-25?", stream=stream)Events are typed (ModelResponse, ModelMessageChunk when streaming=True, ToolCallEvent, ToolResultEvent, HumanInputRequest, compaction events, …), so persistence, UIs and audit logs subscribe to exactly what they need. Longer-lived concerns — metrics, tracing, policies — are better expressed as observers= and middleware= on the agent.
Middleware and observers
Section titled “Middleware and observers”Middleware wraps the agent turn, each LLM call and each tool execution, and can change what passes through. Observers only watch events and raise alerts. Both are passed as lists on the Agent (or per ask), and the built-ins are in ag2.middleware and ag2.observers:
import logging
from ag2 import Agentfrom ag2.config import OpenAIConfigfrom ag2.middleware import HistoryLimiter, LoggingMiddleware, RetryMiddleware, approval_requiredfrom ag2.observers import LoopDetector, TokenMonitor
agent = Agent( "support", prompt="You answer support questions.", config=OpenAIConfig(model="gpt-6-luna"), middleware=[ RetryMiddleware(max_retries=2), # retry failed LLM calls HistoryLimiter(max_events=200), # or TokenLimiter(max_tokens=...) LoggingMiddleware(logging.getLogger("support")), ], observers=[ TokenMonitor(warn_threshold=50_000, alert_threshold=100_000), LoopDetector(repeat_threshold=3), # identical tool calls in a row ],)Other built-ins: TelemetryMiddleware (OpenTelemetry spans; see production) and MetricsMiddleware (extra metrics). approval_required() is tool middleware: @tool(middleware=[approval_required()]) asks a human (through hitl_hook) before the tool runs. Write your own turn-level middleware by subclassing BaseMiddleware, and your own observer by subclassing BaseObserver. ToolMiddleware is not a base class: it is the type of a tool-middleware callable, async def mw(call_next, event, context), which you pass to @tool(middleware=[...]) (the next section shows both). A Plugin(tools=..., middleware=..., observers=..., prompt=...) bundles all of these so you can attach them with plugins=[...].
Writing your own middleware and observers
Section titled “Writing your own middleware and observers”BaseMiddleware has four hooks, each receiving call_next so it can run code before and after the wrapped step: on_turn, on_llm_call, on_tool_execution and on_human_input. Register it with Middleware(Class, **options), which builds a fresh instance per turn. Observers publish an ObserverAlert on the stream, which you can subscribe to like any other event.
import asyncioimport time
from ag2 import Agent, MemoryStream, toolfrom ag2.config import OpenAIConfigfrom ag2.events import ModelResponse, ObserverAlertfrom ag2.middleware import BaseMiddleware, Middleware, approval_requiredfrom ag2.observers import LoopDetector
class Timing(BaseMiddleware): """Print how long each LLM call takes."""
def __init__(self, event, context, *, label: str) -> None: super().__init__(event, context) self.label = label
async def on_llm_call(self, call_next, events, context) -> ModelResponse: started = time.perf_counter() response = await call_next(events, context) print(f"[{self.label}] LLM call took {time.perf_counter() - started:.3f}s") return response
@tool(middleware=[approval_required()]) # asks the human before every calldef delete_account(user_id: str) -> str: """Delete a user account.""" return f"deleted {user_id}"
def human(event) -> str: # hitl_hook: answer "y", "n" or "always" return input(event.content)
agent = Agent( "ops", prompt="Operate customer accounts.", config=OpenAIConfig(model="gpt-6-luna"), tools=[delete_account], middleware=[Middleware(Timing, label="ops")], observers=[LoopDetector(repeat_threshold=3)], hitl_hook=human,)
async def main() -> None: stream = MemoryStream()
@stream.where(ObserverAlert).subscribe() async def on_alert(alert: ObserverAlert) -> None: print("alert:", alert.severity, alert.message)
reply = await agent.ask("Delete account u1.", stream=stream) print(reply.body)
asyncio.run(main())approval_required() accepts message=, denied_message=, timeout= and allow_always=. A denied call returns denied_message to the model as the tool result. Answering always skips the question for later calls of the same tool in that conversation. LoopDetector emits a warning alert after repeat_threshold consecutive identical tool calls; it does not stop the turn, so a policy that should stop it belongs in middleware or the tool. Built-in observers (LoopDetector, TokenMonitor) and any BaseObserver take timeout= (seconds, default None), a per-call limit on the observer’s process method.
Knowledge, memory and compaction
Section titled “Knowledge, memory and compaction”KnowledgePlugin(store=..., ...) in plugins=[...] attaches a KnowledgeStore to an agent. By default the agent gets a knowledge tool for reading and writing the store, and each conversation’s event log is persisted there. A compaction strategy keeps long histories inside the context window:
from ag2 import Agentfrom ag2.compact import CompactTrigger, SummarizeCompact, TailWindowCompactfrom ag2.config import OpenAIConfigfrom ag2.knowledge import KnowledgePlugin, SqliteKnowledgeStore
config = OpenAIConfig(model="gpt-6-luna")
agent = Agent( "assistant", prompt="You are a long-running assistant.", config=config, plugins=[ KnowledgePlugin( store=SqliteKnowledgeStore("agent-memory.db"), compact=TailWindowCompact(target=40), # free: keep the last 40 events # compact=SummarizeCompact(target=40, config=config), # one LLM call: summarise the rest compact_trigger=CompactTrigger(max_events=80), # or max_tokens=... ) ],)Agent(knowledge=KnowledgeConfig(...)) still works in 1.3.2 but is deprecated and goes in 1.4.0 (KnowledgeConfig itself stays; KnowledgePlugin takes the same options). An agent can have only one KnowledgePlugin per invocation: combining two, or one with knowledge=, raises ValueError. A delegated worker with its own plugin uses its own store rather than its parent’s.
- Stores:
MemoryKnowledgeStore(tests),SqliteKnowledgeStore,DiskKnowledgeStore(needswatchdog),RedisKnowledgeStore(extraredis). expose_tool=Falsehides the store from the model when only your own code should use it.aggregate=/aggregate_trigger=distil conversations into longer-term memory.AssemblyPolicyobjects, registered throughAssemblerMiddleware, decide what goes into each LLM request (for example working or episodic memory read from the store). See below.
Controlling what the model sees: assembly policies
Section titled “Controlling what the model sees: assembly policies”AssemblerMiddleware takes policies from ag2.policies. Each one receives the system prompts and the event list before every LLM call and returns changed copies; they run left to right, so each sees the previous one’s output. The stored history is not altered, only the request.
| Policy | Effect |
|---|---|
ConversationPolicy() | Keeps only conversation and tool events (and compaction summaries); everything else on the stream is hidden from the model. |
SlidingWindowPolicy(max_events, transparent=False) | Keeps the last N events. |
TokenBudgetPolicy(max_tokens, chars_per_token=4, transparent=False) | Keeps the most recent events that fit a budget, estimated from character counts. |
WorkingMemoryPolicy(), EpisodicMemoryPolicy(max_episodes=5) | Inject /memory/working.md and recent conversation summaries from the knowledge store into the prompt. |
AlertPolicy() | Injects observer alerts into the prompt; a FATAL alert emits a HaltEvent. |
Put injection policies (memory, alerts) before reduction policies (window, budget). Window and budget are targets: events orphaned by the cut (for example a tool result whose call was dropped) are removed too, and a cut that would leave nothing widens instead. With transparent=True the policy adds a note saying how many events are shown. HistoryLimiter and TokenLimiter in ag2.middleware do a similar trim as middleware.
from ag2 import Agentfrom ag2.assembly import AssemblerMiddlewarefrom ag2.config import OpenAIConfigfrom ag2.middleware import HaltCheckMiddleware, Middlewarefrom ag2.policies import ConversationPolicy, SlidingWindowPolicy, TokenBudgetPolicy
agent = Agent( "chat", prompt="Be brief.", config=OpenAIConfig(model="gpt-6-luna"), middleware=[ Middleware( AssemblerMiddleware, policies=[ ConversationPolicy(), SlidingWindowPolicy(max_events=40, transparent=True), TokenBudgetPolicy(max_tokens=8_000), ], ), Middleware(HaltCheckMiddleware), # lets a FATAL alert from AlertPolicy stop the model call ],)Since 1.3.0 Agent(assembly=[...]) is deprecated and removed in 1.4.0; pass the policies to AssemblerMiddleware as above. Register HaltCheckMiddleware straight after it when you use AlertPolicy: once a HaltEvent has been emitted in the turn, later model calls return a HALTED: <reason> message instead of reaching the provider.
Adding live status to each request
Section titled “Adding live status to each request”statusbar_middleware appends freshly computed input to every model request without writing it to the conversation history, which suits a clock, a budget counter or a queue depth. The callback can be sync or async, takes the same injected parameters as a tool (such as Context), and returns one Input, a sequence of them, or None. A plain str is rejected with TypeError; wrap it in TextInput. persist=True keeps each non-empty result in the history as an observation.
from ag2 import Agentfrom ag2.annotations import Contextfrom ag2.events import TextInputfrom ag2.middleware import statusbar_middlewarefrom ag2.testing import TestConfig
@statusbar_middlewaredef budget(context: Context): return TextInput("Budget left: 12 calls.")
agent = Agent("worker", config=TestConfig("Understood."), middleware=[budget])Register it before RetryMiddleware so one snapshot is reused across provider retries.
Write your own by implementing name and async def apply(self, prompts, events, context) -> (prompts, events).
Sub-tasks and evaluation
Section titled “Sub-tasks and evaluation”Deprecated in 1.3.0, removed in 1.4.0:
Agent(tasks=TaskConfig(...)), the injectedrun_subtask/run_subtaskstools andagent.task(). Build worker agents explicitly and expose them withas_tool()(below). For tracking a unit of work yourself, useTask(owner_id=..., spec=TaskSpec(...))fromag2.task. The description ofTaskConfigthat follows is kept for code you are migrating.
tasks=TaskConfig(...)gives an agentrun_subtask(task)andrun_subtasks(tasks, parallel=True)tools for delegating work to sub-agents. The sub-agents inherit its tools, narrowed withinclude_tools=/exclude_tools=, and cannot delegate further.TaskConfig(config=...)picks a cheaper model for them,extra_tools=adds tools only they have, andmax_concurrency=bounds how many run at once.agent.task(...)is the lifecycle handle for tracking a unit of work yourself.
import asyncio
from ag2 import Agent, TaskConfig, toolfrom ag2.config import OpenAIConfig
@tooldef word_count(text: str) -> int: """Count the words in a text.""" return len(text.split())
lead = Agent( "lead", prompt="Split big jobs into sub-tasks with run_subtasks, then combine the results.", config=OpenAIConfig(model="gpt-6-astra"), tools=[word_count], tasks=TaskConfig( config=OpenAIConfig(model="gpt-6-luna"), # cheaper model for the workers include_tools=["word_count"], # workers may only count words max_concurrency=2, ),)
print(asyncio.run(lead.ask("How many words are in each of these: 'a b c' and 'd e'?")).body)Agents as tools
Section titled “Agents as tools”agent.as_tool(description=..., name=None, stream=None) (or subagent_tool(agent, ...) from ag2.tools.subagents) exposes a whole agent as a tool for another one. Unlike TaskConfig, which it replaces, the delegate keeps its own prompt, tools, model and config. The tool takes an objective and an optional context string, runs the agent as a sub-task, and returns its answer; a failure comes back as a text message rather than an exception. The default name is task_<agent name>.
By default each delegation starts on a fresh MemoryStream. Pass stream=persistent_stream() so the delegate remembers its earlier delegations within one conversation (token cost grows with them), a Stream instance to share one stream you can subscribe to, or a factory (agent, context) -> Stream.
background_agent_tool(agent, description=...) is the fire-and-forget version. It returns a task id at once, runs the delegate in the background, and queues the result as a follow-up message to the parent, which does not finish its ask until the task has completed.
import asyncio
from ag2 import Agentfrom ag2.events import ToolCallEventfrom ag2.testing import TestConfigfrom ag2.tools.subagents import persistent_stream
researcher = Agent( "researcher", prompt="Find facts and report them briefly.", config=TestConfig("Paris has about 2.1 million residents."), # use a real config in practice)
lead = Agent( "lead", prompt="Delegate research, then answer.", tools=[ researcher.as_tool( description="Research a question and return a short answer.", stream=persistent_stream(), ) ],)
reply = asyncio.run( lead.ask( "How many people live in Paris?", config=TestConfig( ToolCallEvent(name="task_researcher", arguments='{"objective": "Population of Paris"}'), "About 2.1 million.", ), ))print(reply.body)When testing background_agent_tool with TestConfig, reply.body sometimes returned the first turn’s text (“Started.”) rather than the follow-up. Subscribe to a MemoryStream and read the last ModelMessage instead of relying on it.
Evaluating an agent
Section titled “Evaluating an agent”ag2.eval runs an agent over a Suite of tasks and grades each run with scorers. run_agent asks the agent each task’s inputs["input"], records the turn as a Trace (it needs OpenTelemetry, so install ag2[tracing]), and passes that trace to your scorers. Scorers are plain functions decorated with @scorer; the parameters they name (trace, inputs, outputs, reference_outputs, task) are injected. A bool or number becomes a score, a str becomes a category, and a scorer that raises is recorded as an unscored result rather than failing the run. With store_dir= the run is saved as <run_id>.json, which load_run reads back and which can be diffed against another run.
import asyncioimport jsonimport tempfilefrom pathlib import Path
from ag2 import Agent, toolfrom ag2.eval import Suite, load_run, run_agent, scorerfrom ag2.events import ToolCallEventfrom ag2.testing import TestConfig
@tooldef lookup(order_id: str) -> str: """Look up an order.""" return f"Order {order_id} has shipped."
agent = Agent( "support", config=TestConfig(ToolCallEvent(name="lookup", arguments='{"order_id": "42"}'), "It has shipped."), tools=[lookup],)
suite = Suite.from_list( [ {"inputs": {"input": "Where is order 42?"}, "reference_outputs": {"order_id": "42"}}, {"inputs": {"input": "Has order 42 gone out yet?"}, "reference_outputs": {"order_id": "42"}}, ], name="order-status",)
@scorerdef looked_up_right_order(trace, reference_outputs): calls = trace.events_of(ToolCallEvent, name="lookup") return bool(calls) and json.loads(calls[0].arguments)["order_id"] == reference_outputs["order_id"]
async def main(): with tempfile.TemporaryDirectory() as store: result = await run_agent(suite, agent=agent, scorers=[looked_up_right_order], store_dir=store) print(result.aggregates.pass_rate) # {'looked_up_right_order': 1.0} saved = load_run(next(Path(store).glob("*.json"))) print(len(saved.tasks)) # 2
asyncio.run(main())Notes from running it:
ToolCallEvent.argumentsis a JSON string, so decode it in a scorer.- A
TestConfigscript starts again from the beginning for each task, so a scripted agent gives every task the same turn. Use a real model, orrun_agent(..., model_config=...), when tasks need different behaviour. Suite.from_jsonl(path)loads the same task shape from a file.run_variantscompares several agent or model variants on one suite,run_pairwiseandevaluate_pairwisecompare two runs with a judge, andevaluate_tracesgrades traces you already hold.
Multi-agent: the Network
Section titled “Multi-agent: the Network”Multi-agent systems in 1.x run on ag2.network: a Hub owns the agent registry, a write-ahead log (WAL) and an audit trail; agents talk over channels:
| Channel type | Shape | Ends when |
|---|---|---|
conversation | Free-form, two parties | You close it |
consulting | One question, one reply | Automatically, after the reply |
discussion | Round-robin across N agents | You close it |
workflow | Turn order from a declarative TransitionGraph | The graph terminates or max_turns is reached |
A three-step pipeline (the 1.x equivalent of a sequential GroupChat):
import asyncio
from ag2 import Agentfrom ag2.config import OpenAIConfigfrom ag2.knowledge import MemoryKnowledgeStorefrom ag2.network import EV_CHANNEL_CLOSED, EV_PACKET, Hub, TransitionGraph
async def main() -> None: config = OpenAIConfig(model="gpt-6-luna") hub = await Hub.open(MemoryKnowledgeStore(), ttl_sweep_interval=0)
requester = await hub.register(Agent("requester", prompt="You commission short pieces.", config=config)) researcher = await hub.register(Agent("researcher", prompt="You gather facts.", config=config)) writer = await hub.register(Agent("writer", prompt="You turn facts into a short draft.", config=config)) editor = await hub.register(Agent("editor", prompt="You tighten drafts.", config=config))
graph = TransitionGraph.sequence([requester.agent_id, researcher.agent_id, writer.agent_id, editor.agent_id]) channel = await requester.open( type="workflow", target=[researcher.agent_id, writer.agent_id, editor.agent_id], knobs={"graph": graph.to_dict()}, ) await channel.send("Topic: how does HTTPS work?") # this message is the requester's turn
# Wait for the graph to finish, then replay the exchange from the WAL. while not any(e.event_type == EV_CHANNEL_CLOSED for e in await hub.read_wal(channel.channel_id)): await asyncio.sleep(0.1) for envelope in await hub.read_wal(channel.channel_id): if envelope.event_type == EV_PACKET: print(envelope.event_data["body"])
await hub.close()
asyncio.run(main())- The initiator’s
channel.send(...)is the initiator’s own turn. If the initiator is the first step of the graph, its model never runs, so give the first step to an agent whose job is just to hand over the brief (requesterabove), and put the agents you want to run after it. TransitionGraph.round_robin(participants=[...], max_turns=N)andTransitionGraph.sequence([...])cover the common cases; custom graphs useTransition(when=..., then=...)with conditions such asFromSpeaker(...)orToolCalled("escalate")and targets such asAgentTarget(...),StayTarget(),RevertToInitiatorTarget()andTerminateTarget(reason=...).- Graphs are plain data (
to_dict()), so a channel survivesHub.hydrate()after a restart. UseDiskKnowledgeStore,SqliteKnowledgeStoreorRedisKnowledgeStoreinstead ofMemoryKnowledgeStorefor durable hubs. - For a two-agent exchange,
type="conversation"withtarget="reviewer"is simpler; close it yourself withawait channel.close().
A consulting channel: one question, one answer
Section titled “A consulting channel: one question, one answer”consulting is the lightest channel. The initiator sends one message, the respondent replies once, and the hub closes the channel with the reason consulting_complete. Targets can be given by agent name or agent_id.
import asyncio
from ag2 import Agentfrom ag2.config import OpenAIConfigfrom ag2.knowledge import MemoryKnowledgeStorefrom ag2.network import EV_CHANNEL_CLOSED, EV_TEXT, Hub
async def main() -> None: config = OpenAIConfig(model="gpt-6-luna") hub = await Hub.open(MemoryKnowledgeStore(), ttl_sweep_interval=0) asker = await hub.register(Agent("asker", prompt="You ask questions.", config=config)) await hub.register(Agent("tax_expert", prompt="Answer tax questions in one sentence.", config=config))
channel = await asker.open(type="consulting", target="tax_expert") await channel.send("What is the standard UK VAT rate?")
while not any(e.event_type == EV_CHANNEL_CLOSED for e in await hub.read_wal(channel.channel_id)): await asyncio.sleep(0.05) answer = [e.event_data["text"] for e in await hub.read_wal(channel.channel_id) if e.event_type == EV_TEXT][-1] print(answer) await hub.close()
asyncio.run(main())Routing on a tool call
Section titled “Routing on a tool call”A transition can depend on what an agent did, not only on who spoke. ToolCalled("escalate") fires when the speaker’s turn included a call to a tool named escalate, and the graph’s default_target handles every other case. Below, the desk submits a ticket, triage answers it or escalates it, and a specialist only speaks when triage escalated:
import asyncio
from ag2 import Agent, toolfrom ag2.config import OpenAIConfigfrom ag2.knowledge import MemoryKnowledgeStorefrom ag2.network import ( EV_CHANNEL_CLOSED, EV_PACKET, AgentTarget, FromSpeaker, Hub, TerminateTarget, ToolCalled, Transition, TransitionGraph,)
@tooldef escalate(reason: str) -> str: """Hand the ticket to a human specialist.""" return "escalated"
async def main() -> None: config = OpenAIConfig(model="gpt-6-luna") hub = await Hub.open(MemoryKnowledgeStore(), ttl_sweep_interval=0) desk = await hub.register(Agent("desk", prompt="You submit tickets.", config=config)) triage = await hub.register(Agent("triage", prompt="Answer simple questions. Call escalate for refunds over 500 pounds.", config=config, tools=[escalate])) specialist = await hub.register(Agent("specialist", prompt="You handle escalated refund requests.", config=config))
graph = TransitionGraph( initial_speaker=desk.agent_id, transitions=[ Transition(when=FromSpeaker(desk.agent_id), then=AgentTarget(triage.agent_id)), Transition(when=ToolCalled("escalate"), then=AgentTarget(specialist.agent_id)), ], default_target=TerminateTarget(reason="resolved"), # anything else ends the channel max_turns=4, ) channel = await desk.open(type="workflow", target=[triage.agent_id, specialist.agent_id], knobs={"graph": graph.to_dict()}) await channel.send("Customer wants a 900 pound refund.")
while not any(e.event_type == EV_CHANNEL_CLOSED for e in await hub.read_wal(channel.channel_id)): await asyncio.sleep(0.1) for envelope in await hub.read_wal(channel.channel_id): if envelope.event_type == EV_PACKET: print(envelope.event_data["body"]) await hub.close()
asyncio.run(main())A tool can also choose the next speaker at run time by returning Handoff(target="specialist", reason=...) (the target is the agent’s registered name), or end the channel by returning Finish(summary=...); both are exported from ag2.network.
MCP servers
Section titled “MCP servers”from ag2 import Agentfrom ag2.config import OpenAIConfigfrom ag2.tools import MCPServerConfig, MCPStdioServerConfig, MCPToolkit
agent = Agent( "ops", prompt="Use the filesystem and ticketing tools to answer questions.", config=OpenAIConfig(model="gpt-6-luna"), tools=[ # local server launched as a subprocess over stdio MCPToolkit(MCPStdioServerConfig(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."])), # remote streamable-HTTP server MCPToolkit(MCPServerConfig(server_url="https://mcp.example.com/mcp", authorization_token="...")), ],)MCPToolkit connects from your process and exposes each MCP tool as an ordinary function tool, so it works with any provider. The stdio subprocess gets a minimal environment, so pass env=dict(os.environ) (or the variables it needs) to MCPStdioServerConfig if npx must reach a registry through a proxy. allowed_tools= / blocked_tools= / tool_name_prefix= on the server config narrow what the model sees. MCPServerTool instead forwards the server URL to providers that connect to MCP themselves (for example Anthropic). Requires ag2[mcp].
Serving an agent as an MCP server
Section titled “Serving an agent as an MCP server”ag2.mcp.MCPServer does the reverse: it exposes an Agent to other MCP clients as a single tool (named ask unless you set tool_name=) that takes a message. It speaks stdio through run_stdio(), and the server object is also an ASGI app that serves streamable HTTP at /mcp. Requires ag2[mcp].
import asyncio
from ag2 import Agentfrom ag2.config import OpenAIConfigfrom ag2.mcp import MCPServer
agent = Agent("tax_expert", prompt="Answer tax questions in one sentence.", config=OpenAIConfig(model="gpt-6-luna"))server = MCPServer(agent, name="tax-expert", tool_name="ask_tax_expert")
if __name__ == "__main__": asyncio.run(server.run_stdio()) # or: uvicorn tax_server:server (HTTP at /mcp)Another AG2 agent can then use it with MCPToolkit(MCPStdioServerConfig(command="python", args=["tax_server.py"])), or with MCPServerConfig(server_url="http://127.0.0.1:8000/mcp") for the HTTP form. Any other MCP client works too.
A2A protocol
Section titled “A2A protocol”Serve an agent over A2A, or call a remote A2A agent as if it were local (requires ag2[a2a]):
import uvicorn
from ag2 import Agent, toolfrom ag2.a2a import A2AConfig, A2AServer, build_cardfrom ag2.config import AnthropicConfig
@tool(description="Add two integers and return the sum as a string.")async def calc_add(a: int, b: int) -> str: return f"{a + b}"
async def serve() -> None: agent = Agent("calculator", config=AnthropicConfig(model="claude-sonnet-5-5"), tools=[calc_add]) card = build_card(agent, url="http://127.0.0.1:8000", description="Adds integers.") app = A2AServer(agent).build_jsonrpc(url="http://127.0.0.1:8000", card=card) await uvicorn.Server(uvicorn.Config(app, host="127.0.0.1", port=8000)).serve()
# Client side: the remote agent's card URL is the "model config".remote = Agent("remote", config=A2AConfig(card_url="http://127.0.0.1:8000"))# reply = await remote.ask("What is 2 + 40?")The card is served at /.well-known/agent-card.json. A2AServer can also build REST and gRPC transports sharing one task store, and supports push notifications via push_config_store=; pass push_url_validator= (added in 1.2.0) to guard against SSRF through client-supplied webhook URLs.
ACP: coding agents and editors
Section titled “ACP: coding agents and editors”The Agent Client Protocol (ACP) is how editors talk to coding agents. ag2.acp supports both roles (requires ag2[acp]).
Driving a CLI coding agent. An ACP config is a model config whose “model” is an external agent process. ClaudeCodeConfig, CodexConfig, OpenCodeConfig and KiloCodeConfig carry the launch command for each adapter (ACPConfig(["your-agent"]) takes any other); the adapter binary must be on PATH.
import asyncio
from acp import schema
from ag2 import Agentfrom ag2.acp import ClaudeCodeConfigfrom ag2.acp.testing import ACPTurn, fake_acp_config
# Real use: the config launches the adapter as a subprocess.real = ClaudeCodeConfig(cwd=".", permission_policy="ask", turn_timeout=300)
async def main() -> None: # Tests: a scripted in-process agent stands in for the subprocess. reply = schema.AgentMessageChunk( session_update="agent_message_chunk", content=schema.TextContentBlock(type="text", text="Done."), ) cfg = fake_acp_config(ACPTurn(updates=[reply]), permission_policy="auto") async with cfg: # leaving the scope closes every session the config started coder = Agent("coder", config=cfg) print((await coder.ask("Fix the failing tests")).body)
asyncio.run(main())Settings worth knowing:
permission_policyanswers the agent’s permission requests:"ask"(default) routes them to the agent’shitl_hookorcontext.input,"auto"allows,"deny"rejects.elicitation_policydoes the same for questions the agent puts to the user ("ask"or"decline").- The subprocess inherits only
HOME,LOGNAME,PATH,SHELL,TERMandUSER. Pass API keys inenv=; a shellexportdoes not reach it. A login stored under$HOMEworks without. cwdis the workspace the agent reads and writes, andfs_rootconfines file access (it defaults tocwd).allow_terminal=Falsewithholds the terminal capability.expose_tools=True(default) serves the agent’s own function tools to the CLI agent over a local HTTP MCP server, and passesMCPServerToolentries through. The set of MCP servers is fixed when the session is created on the first turn.turn_timeoutbounds a prompt turn; on expiry AG2 sendssession/canceland, aftercancel_timeoutseconds, tears the connection down.ACPRemoteConfig(url="wss://…", headers={…})reaches an agent that is already running. It needspip install "agent-client-protocol[http]". The workspace stays on the AG2 side, so a remote agent works on your local files.
Serving an AG2 agent to an editor. Wrap it in ACPAgent and run it over stdio, which is how ACP clients normally launch agents:
from ag2 import Agentfrom ag2.acp import ACPAgent, SessionConfig
served = ACPAgent( Agent("workie", prompt="You are a helpful coding assistant."), sessions=SessionConfig(max_sessions=8, ttl=600, max_concurrent_turns=4),)# await served.run_stdio()Each session/new gets an isolated history; prompts on one session queue (bounded by max_queued) and session/cancel stops that session’s running turn and everything queued behind it. History is dropped when the connection closes unless you set SessionConfig(retain_history=True) with a durable storage, which lets a later session/load resume it. auth= takes an AuthProvider such as StaticTokenAuth; it decides whether a client may connect, not who it is, so serve one tenant per instance. Reasoning is not sent to clients unless you pass stream_thoughts=True. A turn that calls context.input() fails unless you supply hitl_hook=.
Agent specs
Section titled “Agent specs”AgentSpec is a JSON-serialisable description of an agent’s declarative parts: name, prompt, tool_names and the response schema. Middleware, callbacks, dependencies and dynamic prompts are not captured, so you supply them again when rebuilding. Tools are stored by name and resolved against the available_tools you pass to to_agent; a missing name raises ToolResolutionError listing what was available. Unknown keys in a spec load with an UnknownSpecFieldWarning naming the closest valid field.
import asyncio
from ag2 import Agent, toolfrom ag2.spec import AgentSpecfrom ag2.testing import TestConfig
@tooldef lookup(order_id: str) -> str: """Look up an order.""" return "shipped"
spec = AgentSpec.from_agent(Agent("support", prompt="You help.", tools=[lookup]))text = spec.model_dump_json(indent=2) # store this in a file or database
agent = AgentSpec.model_validate_json(text).to_agent( available_tools=[lookup], config=TestConfig("hello"), # use a real config in practice)print(asyncio.run(agent.ask("hi")).body)Testing
Section titled “Testing”ag2.testing.TestConfig replays scripted model outputs (strings for answers, ToolCallEvent(...) for tool calls), so agents can be unit-tested without network access. The example uses pytest-asyncio (pip install pytest pytest-asyncio):
import pytest
from ag2 import Agent, toolfrom ag2.events import ToolCallEventfrom ag2.testing import TestConfig
@tooldef lookup(order_id: str) -> str: """Look up an order.""" return f"order {order_id}: shipped"
@pytest.mark.asyncioasync def test_lookup_flow() -> None: agent = Agent("support", tools=[lookup]) reply = await agent.ask( "Where is order 42?", config=TestConfig(ToolCallEvent(name="lookup", arguments='{"order_id": "42"}'), "It has shipped."), ) assert reply.body == "It has shipped."AG2 Classic and migrating from 0.x
Section titled “AG2 Classic and migrating from 0.x”The Classic import autogen API (ConversableAgent, GroupChat), which ag2 shipped up to 0.14.0, now lives in ag2ai/ag2-classic. It is published on PyPI as autogen and is in maintenance mode. It has its own section on this site: AG2 Classic. To port Classic code to 1.x (or AutoGen 0.2 code to Classic), follow the migration guide.