Skip to content
AgPy

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 ag2 1.3.2 (checked 2026-11-19). Every 1.x example on this page was executed offline against the installed package using ag2.testing.TestConfig in place of a real model. For the Classic import autogen API, see AG2 Classic.

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 an AgentReply.
  • Plain functions as tools — decorate with @tool; dependency injection via Context.
  • Typed events — every model call, tool call and human-input request is an event you can subscribe to on a MemoryStream.
  • Network — a Hub plus typed channels (conversation, consulting, discussion, workflow) replaces GroupChat, swarms and nested chats.
  • Interop — MCP servers as toolkits, agents served or consumed over A2A, AG-UI and ACP adapters.
AG2 Classic (ag2 ≤ 0.14, autogen)AG2 1.x (ag2 ≥ 1.0)
Importimport autogenimport ag2
Core agentConversableAgent, AssistantAgent, UserProxyAgentAgent
Model configLLMConfig / OAI_CONFIG_LIST dictsProvider classes: OpenAIConfig, AnthropicConfig, GeminiConfig, …
Runninginitiate_chat, generate_reply (sync)await agent.ask(...), await reply.ask(...)
Toolsregister_function(f, caller=..., executor=...)@tool + Agent(tools=[...])
Multi-agentGroupChat / GroupChatManager, swarms, nested chatsag2.network.Hub + channels, TransitionGraph
Human inputhuman_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.

Terminal window
pip install "ag2[openai]" # or ag2[anthropic], ag2[gemini], ag2[bedrock], ag2[ollama], ...
pip install "ag2[openai]==1.3.2" # pinned

The 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:

ProviderConfig classKey variable
OpenAI Chat Completions (and compatible endpoints via base_url)OpenAIConfigOPENAI_API_KEY
OpenAI Responses APIOpenAIResponsesConfigOPENAI_API_KEY
AnthropicAnthropicConfigANTHROPIC_API_KEY
Gemini API / Vertex AIGeminiConfig / VertexAIConfigGEMINI_API_KEY / ADC
Amazon BedrockBedrockConfigAWS credentials
Ollama, Mistral, xAI, Z.AI, DashScope, TypeSafeOllamaConfig, MistralConfig, XAIConfig, ZAIConfig, DashScopeConfig, TypeSafeConfigprovider-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=...)).

import asyncio
from ag2 import Agent
from 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 of ask: it returns an AgentRun, an async context manager you drive (run.start() or await 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 as task_<name>) — the simplest sub-agent pattern.
from datetime import datetime
from ag2 import Agent, tool
from ag2.config import OpenAIConfig
@tool
async 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 Context is injected rather than exposed to the model; it gives tools access to context.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) and ShellTool (OpenAI’s hosted container via the Responses API; not supported on Anthropic). They only work with providers that support them.

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 from dependencies= (on the Agent or per ask), looked up by parameter name or by Inject("name"). Use it for database clients, HTTP sessions and settings.
  • Annotated[T, Variable()] takes the value from variables=, the per-conversation state (tools can change it through context.variables).
  • Annotated[T, Depends(factory)] calls factory() (FastDepends-style) and passes the result.
import asyncio
from dataclasses import dataclass
from typing import Annotated
from ag2 import Agent, Depends, Inject, Variable, tool
from ag2.config import OpenAIConfig
@dataclass
class Database:
balances: dict[str, float]
def get_currency() -> str:
return "EUR"
@tool
def 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).

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, tool
from ag2.annotations import Context
from ag2.events import ToolCallEvent
from ag2.testing import TestConfig
@tool
def 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 parent

Two kinds of code tool exist, and they are not interchangeable:

ToolWhere code runsWorks 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 servicesEvery provider
CodeExecutionTool(), ShellTool()Server-side, in the model provider’s sandboxOnly providers with native code execution or shell tools
from ag2 import Agent
from ag2.config import OpenAIConfig
from 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).

from pydantic import BaseModel
from ag2 import Agent
from 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 TicketTriage

reply.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.

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, ImageInput
from 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.

from ag2 import Agent, Context, tool
from ag2.config import OpenAIConfig
from ag2.events import HumanInputRequest, HumanMessage
@tool
async 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.

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, MemoryStream
from ag2.config import OpenAIConfig
from 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).

from ag2 import MemoryStream
from 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 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 Agent
from ag2.config import OpenAIConfig
from ag2.middleware import HistoryLimiter, LoggingMiddleware, RetryMiddleware, approval_required
from 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=[...].

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 asyncio
import time
from ag2 import Agent, MemoryStream, tool
from ag2.config import OpenAIConfig
from ag2.events import ModelResponse, ObserverAlert
from ag2.middleware import BaseMiddleware, Middleware, approval_required
from 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 call
def 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.

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 Agent
from ag2.compact import CompactTrigger, SummarizeCompact, TailWindowCompact
from ag2.config import OpenAIConfig
from 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 (needs watchdog), RedisKnowledgeStore (extra redis).
  • expose_tool=False hides the store from the model when only your own code should use it. aggregate= / aggregate_trigger= distil conversations into longer-term memory.
  • AssemblyPolicy objects, registered through AssemblerMiddleware, 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.

PolicyEffect
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 Agent
from ag2.assembly import AssemblerMiddleware
from ag2.config import OpenAIConfig
from ag2.middleware import HaltCheckMiddleware, Middleware
from 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.

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 Agent
from ag2.annotations import Context
from ag2.events import TextInput
from ag2.middleware import statusbar_middleware
from ag2.testing import TestConfig
@statusbar_middleware
def 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).

Deprecated in 1.3.0, removed in 1.4.0: Agent(tasks=TaskConfig(...)), the injected run_subtask / run_subtasks tools and agent.task(). Build worker agents explicitly and expose them with as_tool() (below). For tracking a unit of work yourself, use Task(owner_id=..., spec=TaskSpec(...)) from ag2.task. The description of TaskConfig that follows is kept for code you are migrating.

  • tasks=TaskConfig(...) gives an agent run_subtask(task) and run_subtasks(tasks, parallel=True) tools for delegating work to sub-agents. The sub-agents inherit its tools, narrowed with include_tools= / exclude_tools=, and cannot delegate further. TaskConfig(config=...) picks a cheaper model for them, extra_tools= adds tools only they have, and max_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, tool
from ag2.config import OpenAIConfig
@tool
def 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)

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 Agent
from ag2.events import ToolCallEvent
from ag2.testing import TestConfig
from 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.

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 asyncio
import json
import tempfile
from pathlib import Path
from ag2 import Agent, tool
from ag2.eval import Suite, load_run, run_agent, scorer
from ag2.events import ToolCallEvent
from ag2.testing import TestConfig
@tool
def 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",
)
@scorer
def 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.arguments is a JSON string, so decode it in a scorer.
  • A TestConfig script starts again from the beginning for each task, so a scripted agent gives every task the same turn. Use a real model, or run_agent(..., model_config=...), when tasks need different behaviour.
  • Suite.from_jsonl(path) loads the same task shape from a file. run_variants compares several agent or model variants on one suite, run_pairwise and evaluate_pairwise compare two runs with a judge, and evaluate_traces grades traces you already hold.

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 typeShapeEnds when
conversationFree-form, two partiesYou close it
consultingOne question, one replyAutomatically, after the reply
discussionRound-robin across N agentsYou close it
workflowTurn order from a declarative TransitionGraphThe graph terminates or max_turns is reached

A three-step pipeline (the 1.x equivalent of a sequential GroupChat):

import asyncio
from ag2 import Agent
from ag2.config import OpenAIConfig
from ag2.knowledge import MemoryKnowledgeStore
from 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 (requester above), and put the agents you want to run after it.
  • TransitionGraph.round_robin(participants=[...], max_turns=N) and TransitionGraph.sequence([...]) cover the common cases; custom graphs use Transition(when=..., then=...) with conditions such as FromSpeaker(...) or ToolCalled("escalate") and targets such as AgentTarget(...), StayTarget(), RevertToInitiatorTarget() and TerminateTarget(reason=...).
  • Graphs are plain data (to_dict()), so a channel survives Hub.hydrate() after a restart. Use DiskKnowledgeStore, SqliteKnowledgeStore or RedisKnowledgeStore instead of MemoryKnowledgeStore for durable hubs.
  • For a two-agent exchange, type="conversation" with target="reviewer" is simpler; close it yourself with await 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 Agent
from ag2.config import OpenAIConfig
from ag2.knowledge import MemoryKnowledgeStore
from 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())

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, tool
from ag2.config import OpenAIConfig
from ag2.knowledge import MemoryKnowledgeStore
from ag2.network import (
EV_CHANNEL_CLOSED, EV_PACKET, AgentTarget, FromSpeaker, Hub, TerminateTarget, ToolCalled, Transition, TransitionGraph,
)
@tool
def 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.

from ag2 import Agent
from ag2.config import OpenAIConfig
from 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].

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].

tax_server.py
import asyncio
from ag2 import Agent
from ag2.config import OpenAIConfig
from 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.

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, tool
from ag2.a2a import A2AConfig, A2AServer, build_card
from 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.

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 Agent
from ag2.acp import ClaudeCodeConfig
from 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_policy answers the agent’s permission requests: "ask" (default) routes them to the agent’s hitl_hook or context.input, "auto" allows, "deny" rejects. elicitation_policy does the same for questions the agent puts to the user ("ask" or "decline").
  • The subprocess inherits only HOME, LOGNAME, PATH, SHELL, TERM and USER. Pass API keys in env=; a shell export does not reach it. A login stored under $HOME works without.
  • cwd is the workspace the agent reads and writes, and fs_root confines file access (it defaults to cwd). allow_terminal=False withholds 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 passes MCPServerTool entries through. The set of MCP servers is fixed when the session is created on the first turn.
  • turn_timeout bounds a prompt turn; on expiry AG2 sends session/cancel and, after cancel_timeout seconds, tears the connection down.
  • ACPRemoteConfig(url="wss://…", headers={…}) reaches an agent that is already running. It needs pip 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 Agent
from 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=.

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, tool
from ag2.spec import AgentSpec
from ag2.testing import TestConfig
@tool
def 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)

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, tool
from ag2.events import ToolCallEvent
from ag2.testing import TestConfig
@tool
def lookup(order_id: str) -> str:
"""Look up an order."""
return f"order {order_id}: shipped"
@pytest.mark.asyncio
async 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."

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.