// Map of AG2 beta capabilities and which sibling skill to reach for. Load first when the user mentions building with AG2 beta (autogen.beta) but the specific feature isn't yet clear — agents, tools, model config, delegation, memory, observers, structured output, HITL, AG-UI, telemetry, testing, or evaluation.
| name | ag2-overview |
| description | Map of AG2 beta capabilities and which sibling skill to reach for. Load first when the user mentions building with AG2 beta (autogen.beta) but the specific feature isn't yet clear — agents, tools, model config, delegation, memory, observers, structured output, HITL, AG-UI, telemetry, testing, or evaluation. |
| license | Apache-2.0 |
AG2 beta (autogen.beta) is an async, protocol-driven agent framework. The full reference docs live under website/docs/beta/. This skill is the index of sibling skills that cover the common build paths.
Read this file first when a request mentions "AG2 beta", "autogen.beta", or building agents in this repo and you don't yet know which feature is needed. Use the table below to pick the right specialised skill, then load that skill's SKILL.md for the recipe.
Anything you build with AG2 needs three things in place. Get these right once and the rest of the skills run cleanly:
pip install "ag2[openai]", ag2[anthropic], ag2[gemini], etc. The *Config class will raise ImportError: ... requires optional dependencies without it.OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY (or GOOGLE_API_KEY). Loading from a project-root .env via from dotenv import load_dotenv; load_dotenv() is the common pattern.python -c "import sys, autogen; print(sys.executable, autogen.__version__)". If you have multiple Python environments, this confirms which ag2 your script will actually import.Full per-provider table (install + env var + config class) lives in ag2-quickstart → "Prerequisites".
| User intent | Skill | What it covers |
|---|---|---|
Build an Agent from scratch, pick a model | ag2-quickstart | Agent, ModelConfig, ask() / reply.ask() chaining, providers, env vars |
| Give the Agent a custom Python tool | ag2-add-custom-tool | @tool, sync/async, ToolResult, Context, Inject, Variable, Depends |
| Use shipped tools (web search, code exec, MCP, etc.) | ag2-use-builtin-tools | WebSearchTool, WebFetchTool, CodeExecutionTool, MCPServerTool, ImageGenerationTool, MemoryTool, FilesystemToolkit, DuckDuckSearchTool, ExaToolkit, TavilySearchTool |
| Run shell commands from an agent | ag2-shell-tool | LocalShellTool (any provider), provider-side ShellTool, sandboxing (allowed/blocked/ignore/readonly) |
| Get typed Pydantic / dataclass output | ag2-structured-output | response_schema=, ResponseSchema, @response_schema, PromptedSchema, reply.content(), retries |
| Multi-agent: parallel subtasks or named delegates | ag2-subagent-delegation | tasks=TaskConfig(), run_subtasks(parallel=True), Agent.as_tool(), persistent_stream |
| Pause for human input or gate a tool with approval | ag2-hitl | context.input(), hitl_hook, approval_required() middleware |
| Logging, retry, history-trim, custom interception | ag2-middleware | BaseMiddleware, LoggingMiddleware, RetryMiddleware, HistoryLimiter, TokenLimiter, tool middleware |
| Test agents and tools | ag2-testing | TestConfig, mocking LLM responses, simulating ToolCallEvent |
| Evaluate / benchmark an agent offline, CI gate, scorers | ag2-evaluation | Suite, run_agent, final_answer_matches / tool_called / agent_judge, @scorer, RunResult, TestConfig, evaluate_traces, diff().regressions |
| Compare models / prompts — leaderboard or head-to-head | ag2-eval-comparison | run_variants (Variants.from_*), run_pairwise + pairwise_judge (win-rate, Wilson CI, flips, κ), human_pairwise |
| Persistent memory across runs, history compaction, assembly | ag2-knowledge-and-memory | KnowledgeStore, KnowledgeConfig, WorkingMemoryAggregate, AssemblyPolicy, SlidingWindowPolicy, TokenBudgetPolicy, TailWindowCompact, SummarizeCompact |
| Observability, alerts, halts | ag2-observers-and-alerts | BaseObserver, TokenMonitor, LoopDetector, EventWatch, CadenceWatch, AlertPolicy, HaltEvent |
| Send images / audio / video / PDFs in | ag2-multimodal-input | ImageInput, AudioInput, VideoInput, DocumentInput, FilesAPI |
| Web frontend via the AG-UI protocol | ag2-ag-ui | AGUIStream, FastAPI mount, CopilotKit |
| OpenTelemetry traces / metrics | ag2-telemetry | TelemetryMiddleware, GenAI semconv attributes, content capture |
Whenever two or more agents need to interact, load ag2-network-quickstart first — the network is the standard multi-agent pattern in AG2 beta. It covers the Hub setup and the two 2-party channel adapters (consulting for strict 1Q1R and conversation for free-form). After the quickstart, route to the right deep-dive:
| User intent | Skill | What it covers |
|---|---|---|
| N-party round-robin / fixed turn order | ag2-network-discussion | discussion adapter, ORDERING_ROUND_ROBIN knob, can_send probe pattern, view-window sizing |
Declarative orchestration / TransitionGraph / GroupChat migration | ag2-network-workflow | workflow adapter, TransitionGraph.sequence / .round_robin, Handoff, ToolCalled, ContextEquals, context_vars, 8 cookbook patterns, classic-GroupChat migration |
| Rate limits, access policy, expectations, audit, capability tracking | ag2-network-governance | Rule (AccessBlock / LimitsBlock / RateBlock / InboxBlock), Expectations, audit log + AUDIT_KIND_*, task observation, Resume.observed |
| Custom envelope handlers, view policies, peer discovery, the six LLM-facing network tools | ag2-network-tools-and-views | say / delegate / peers / channels / tasks / context tools, agent_client.on_envelope, ViewPolicy (FullTranscript / WindowedSummary), skill_md peer discovery, full Envelope / EV_* reference |
Not a network task: if the user has one agent recursively spawning its own sub-tasks (via run_subtask / run_subtasks(parallel=True)) or calling another agent as a lightweight tool, use ag2-subagent-delegation — no hub, no registry, no channels. The network is for distinct, registered agents collaborating through a shared hub.
Compare AG2 beta agents, models, or prompts to decide which is better. run_variants scores several named configurations on one suite and ranks them on a leaderboard (Variants.from_configs, from_prompts, from_tools, from_middleware, from_targets). run_pairwise with pairwise_judge does head-to-head LLM comparison using a dual-order position swap (a win counts only if it survives the swap, else a tie), reporting win-rate with a Wilson 95% CI, wins, losses, ties, flips, and agreement (Cohen's kappa). human_pairwise collects a person's blinded vote inline, or via an exported manifest with export_pairwise_cases and human_labels. Use when the user wants to A/B test prompts or models, run a leaderboard, pick a winner, judge head-to-head, measure win-rate, or collect human preference labels. For running and grading a single agent, see ag2-evaluation.
Evaluate, test, and track an AG2 beta Agent offline. Build a Suite of tasks, run the agent with run_agent, and grade answers with prebuilt scorers (final_answer_matches, tool_called, no_tool_errors, token_budget) or a custom @scorer — including the agent_judge LLM judge. Read the RunResult scorecard (pass_rate, score_stats, value_counts), gate it in CI with deterministic TestConfig cassettes, persist to store_dir and diff runs to catch regressions, and grade existing traces with evaluate_traces. Use when the user wants to evaluate, test, grade, or benchmark an agent, build a CI or regression gate, or score correctness, tool use, cost, or quality. To compare builds head-to-head or on a leaderboard, see ag2-eval-comparison.
Intercept the AG2 beta agent loop with `BaseMiddleware` — wrap full turns (`on_turn`), each LLM call (`on_llm_call`), each tool execution (`on_tool_execution`), or each human-input request (`on_human_input`). Use for retry, logging, history trimming, request mutation, tool auditing, guardrails, or rate limiting. Built-ins: `LoggingMiddleware`, `RetryMiddleware`, `HistoryLimiter`, `TokenLimiter`, `TelemetryMiddleware` (see `ag2-telemetry`). For per-tool hooks see also `ag2-add-custom-tool` tool-middleware section.
Open an AG2 network `discussion` channel — N-party (2+) round-robin where each participant speaks in fixed order, cycling until explicit close or TTL. Use when the user wants a brainstorm with a fixed cast, a panel discussion, or round-robin reviewers. Covers `agent_client.open(type="discussion", target=[...], knobs={"ordering": ORDERING_ROUND_ROBIN})`, the `expected_next_speaker` rotation, the `hc.can_send(...)` probe pattern (default handlers skip LLM calls when it isn't their turn), `DiscussionState`, the `turn_within` expectation defaults (`warn` at 120s / `hide` at 600s), view-window sizing for N participants, and the four close patterns that work with this adapter. Load this after `ag2-network-quickstart`. For conditional handoffs or declarative orchestration, see `ag2-network-workflow` instead.
Govern an AG2 multi-agent network — identity (`Passport`, `Resume`), per-agent `Rule` with `AccessBlock` / `LimitsBlock` / `RateBlock` / `InboxBlock`, the swappable `HubArbiter` / `RuleBasedArbiter` access-&-routing seam, `AuthAdapter` / `AuthRegistry` registration, channel-level `Expectation`s with `audit` / `warn` / `auto_close` violation handlers, the hub's append-only audit log and `AUDIT_KIND_*` constants, live `HubListener` / `BaseHubListener` observability plus `Hub` `on_*` hooks and `register_sweeper`, and task observation via `agent.task(...)` + `TaskMirror` (updates `Resume.observed` for peer ranking). Use when the user needs rate limits, access policy, SLAs, compliance trails, live metrics/alerting, capability-driven peer ranking, or to inspect what actually happened on the network. Load this after `ag2-network-quickstart`. For the agent-side surface (custom handlers, views, LLM tools, `HumanClient`) see `ag2-network-tools-and-views`.
Shape what an AG2 network agent perceives and which actions its LLM can take. Covers the six auto-injected LLM-facing tools that ship via `NetworkPlugin` (`say`, `delegate`, `peers`, `channels`, `tasks`, `context`); replacing the default handler with `agent_client.on_envelope(callback)` (gateways, headless workers); the `ViewPolicy` Protocol with the built-in `FullTranscript` and `WindowedSummary(recent_n=N)` views plus how to write a custom view; peer discovery via skill markdown (`skill_md=`, `parse_skill_frontmatter`, `hub.set_skill`); the `Envelope` wire format with the `EV_*` event taxonomy (`EV_TEXT`, `EV_PACKET`, `EV_CHANNEL_*`, `EV_EXPECTATION_VIOLATED`, `ag2.task.*`), `audience` and `visible_to` semantics, `Priority`, `causation_id`, and how to send raw envelopes with custom event types via `agent_client.send_envelope(...)`. Use when the user wants to customise the LLM's network surface, write a custom envelope handler, build a gateway / headless worker, or wire peer discovery.