AI Coding Assistants

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

Why this matters#

AG2 (ag2) is an 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, an up-to-date docs reference, and project rules that keep it on the current AG2 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. 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 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 AG2 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) — now removed from the package. Give it current ground truth:

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

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

Step 3: Add project rules to your repo#

A rules file pins AG2 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** (`ag2`). Follow these rules.

## API surface
- Import only from `ag2` and its submodules (`ag2.config`,
  `ag2.tools`, ...). Do NOT use the legacy `autogen` / `pyautogen`
  API (`ConversableAgent`, `initiate_chat`) — it has been removed.
- 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`.
- AG2 docs: https://docs.ag2.ai/latest/docs/user-guide/agents/ (machine-readable index at /latest/llms.txt).
- When unsure of a signature, check the AG2 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.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 (ag2, ag2.tools, ag2.config) over reaching into internals.
• Always review generated code. Models still drift toward legacy autogen patterns; verify imports come from ag2 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.