AI Coding Assistants

Set up your AI coding assistant (Claude Code, Cursor, Copilot, Codex, Windsurf, or any agent) so it can build AG2 Beta apps with you using current, accurate APIs and examples.

Why this matters#

AG2 Beta (autogen.beta) is a new, async, protocol-driven API. Models were largely trained on the older autogen / pyautogen surface, so out of the box an assistant will reach for stale patterns such as synchronous ConversableAgent, initiate_chat, and the like. The setup on this page gives your assistant three things it otherwise lacks: AG2-specific skills, a Beta-only docs reference, and project rules that keep it on the Beta API.

Step 1: Install the AG2 Skills#

The most critical and dev-accelerating step.

ag2-skills is a catalog of Agent Skills, on-demand instruction packs that teach an assistant how to build with AG2 Beta. Each skill loads only its name and description until it's relevant, then pulls in the full recipe. Skills cover quickstart, custom tools, the multi-agent network, middleware, memory, structured output, evaluation, and more.

The fastest path uses the skills CLI:

# Install the full AG2 Beta skill catalog
npx skills add ag2ai/ag2-skills

# Install just the quickstart (good first taste)
npx skills add ag2ai/ag2-skills@ag2-quickstart

# Clone and copy individual skills into your user skills directory
git clone https://github.com/ag2ai/ag2-skills.git
cp -r ag2-skills/skills/ag2-overview   ~/.claude/skills/
cp -r ag2-skills/skills/ag2-quickstart ~/.claude/skills/

Step 2: Point your assistant at the Beta docs#

Skills teach patterns; the docs keep your assistant honest about the exact current signatures. The biggest risk is your assistant falling back on the classic autogen API it was trained on (ConversableAgent, initiate_chat, GroupChat) — all retiring at v1.0. Give it Beta-only ground truth:

• Live Beta docs: https://docs.ag2.ai/latest/docs/beta/agents/ — point your agent at this section (most assistants can fetch a URL).
• Beta docs source (Markdown): ag2ai/ag2/website/docs/beta — the raw .mdx your agent can read directly from GitHub.
• Beta llms.txt: https://docs.ag2.ai/latest/llms.txt — a machine-readable index of the Beta docs following the llms.txt standard, plus llms-full.txt for the entire Beta docs in one file. Both are Beta-scoped, so they never point your agent at the classic API.

Then anchor your prompt: "Build with autogen.beta only. If a signature is unfamiliar, check the Beta docs before writing code — do not use the classic autogen API."

Step 3: Add project rules to your repo#

A rules file pins AG2 Beta conventions for every session in your project. The open AGENTS.md standard is read by Cursor, Copilot, Codex, Gemini CLI, Windsurf, and others; Claude Code reads CLAUDE.md. Drop one (or both, a symlink works) at your repo root:

# AGENTS.md

This project is built on **AG2 Beta** (`autogen.beta`). Follow these rules.

## API surface
- Import only from `autogen.beta` and its submodules (`autogen.beta.config`,
  `autogen.beta.tools`, ...). Do NOT use the legacy `autogen` / `pyautogen`
  API (`ConversableAgent`, `initiate_chat`) — it is retired at v1.0.
- Agents are async. Use `await agent.ask(...)` and `await reply.ask(...)`.

## Conventions
- Do not use `from __future__ import annotations`.
- Public signatures accept `str | os.PathLike[str]`; use `pathlib.Path` internally.
- Prefer top-level imports; no imports inside functions.

## Docs & skills
- Install and use the AG2 skills: `npx skills add ag2ai/ag2-skills`.
- Beta docs: https://docs.ag2.ai/latest/docs/beta/agents/ (machine-readable index at /latest/llms.txt).
- When unsure of a signature, check the Beta docs before writing code.
- Do NOT trust generic docs indexers — they surface the retired classic API.

# Claude Code reads CLAUDE.md — symlink it to a single source of truth
ln -s AGENTS.md CLAUDE.md

# Cursor reads AGENTS.md, or project rules under .cursor/rules/
mkdir -p .cursor/rules
cp AGENTS.md .cursor/rules/ag2-beta.md

# GitHub Copilot reads .github/copilot-instructions.md
mkdir -p .github
cp AGENTS.md .github/copilot-instructions.md

Per-tool summary#

Tips & caveats#

• Start from the quickstart. Have your assistant scaffold from ag2-quickstart rather than inventing structure — see Agent Communication and Model Configuration.
• Prefer the documented high-level API (autogen.beta, autogen.beta.tools, autogen.beta.config) over reaching into internals.
• Always review generated code. Models still drift toward legacy autogen patterns; verify imports come from autogen.beta and that calls are awaited.
• Run the tests. AG2 is async throughout — encourage your assistant to write and run tests with TestConfig instead of hitting a live model.