ag2-quickstart

用途

AG2 Quickstart 面向的是「从空白文件开始、想得到一个可运行的 AG2 Agent」的场景，也可作为更大任务的骨架：先按本文搭好基础 Agent，再叠加所需的功能技能。典型情况包括：用户不确定该选哪个提供商配置；用户希望串联多轮追问而不丢失对话上下文。

前置条件

完成前必须安装依赖。写完 AG2 代码后，安装与所用提供商匹配的 extra（以及任务需要的其它功能 extra，例如 ag-ui、tracing）。安装命令：

pip install "ag2[openai]"   # swap in the provider/extra you used

如果无法运行命令，需要明确给出准确的 pip install 命令。这是完成任务的一部分，不是可选的说明。

对于多文件项目（非一次性脚本），还应提供 requirements.txt，锁定所用 extra 的 ag2 版本（例如 ag2[openai]>=0.14.0），以保证环境可复现。

每个 *Config 都需要对应的提供商 SDK——缺少匹配的 extra 会出现 ImportError: ... requires optional dependencies。用 pip install "ag2[<provider>]" 安装。

提供商对照：

OpenAI：pip install "ag2[openai]"，环境变量 OPENAI_API_KEY，配置类 OpenAIConfig、OpenAIResponsesConfig
Anthropic：pip install "ag2[anthropic]"，ANTHROPIC_API_KEY，AnthropicConfig
Gemini（API key）：pip install "ag2[gemini]"，GEMINI_API_KEY（或 GOOGLE_API_KEY），GeminiConfig
Vertex AI（Gemini）：pip install "ag2[gemini]"，service-account / ADC，VertexAIConfig
Ollama（本地）：pip install "ag2[ollama]"，无环境变量，OllamaConfig
DashScope（Qwen）：pip install "ag2[dashscope]"，DASHSCOPE_API_KEY，DashScopeConfig

可使用 python-dotenv 从项目根目录的 .env 加载环境变量，让脚本无需在 shell 中导出密钥：

from dotenv import load_dotenv
load_dotenv()  # reads .env at project root

排查诡异的导入错误前，可先做一次快速自检，确认运行的是预期的 ag2：

python -c "import sys, ag2; from importlib.metadata import version; print(sys.executable); print('ag2', version('ag2'))"

60 秒示例

import asyncio
from ag2 import Agent
from ag2.config import OpenAIConfig

async def main() -> None:
    agent = Agent(
        "assistant",
        prompt="You are a helpful assistant. Reply in one sentence.",
        config=OpenAIConfig(model="gpt-4o-mini"),
    )

    # First turn
    reply = await agent.ask("What is the capital of France?")
    print(reply.body)

    # Continue the same conversation — context is preserved
    reply = await reply.ask("And of Germany?")
    print(reply.body)

asyncio.run(main())

Agent.ask(...) 开始新一轮并返回 AgentReply；AgentReply.ask(...) 延续同一段对话，保留其上下文与历史。回复文本在 reply.body 中；结构化输出见 ag2-structured-output 技能（reply.content()）。

选择提供商

每个提供商在 ag2.config 中都有自己的配置类。它们都接受 model=、可选的 api_key=，并在支持时接受 streaming=True。推荐开启流式——AG2 以异步和流式为一等设计。

from ag2.config import OpenAIConfig          # gpt-4o, gpt-5-*, o-series, etc.
from ag2.config import OpenAIResponsesConfig # OpenAI Responses API (image gen, file_id support)
from ag2.config import AnthropicConfig       # claude-sonnet-4-6, claude-opus-4-7, etc.
from ag2.config import GeminiConfig          # Gemini Developer API (api_key)
from ag2.config import VertexAIConfig        # Gemini on Google Vertex AI (project + location)
from ag2.config import OllamaConfig          # local Ollama
from ag2.config import DashScopeConfig       # Alibaba Qwen

config = AnthropicConfig(model="claude-sonnet-4-6", streaming=True)

若省略 api_key=，配置会读取标准环境变量——OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY（或 GOOGLE_API_KEY）等。

对于 OpenAI 兼容端点（vLLM、LM Studio、Together、NVIDIA NIM 等），使用 OpenAIConfig 并设置 base_url=：

config = OpenAIConfig(
    model="qwen-3",
    base_url="http://localhost:8000/v1",
    api_key="NotRequired",  # pragma: allowlist secret
)

多轮对话——链式调用 reply.ask()

agent = Agent("planner", prompt="...", config=config)
reply = await agent.ask("Plan a 5-day Japan trip in late April.")
reply = await reply.ask("Budget is $2500 per person, two travellers.")
reply = await reply.ask("Prefer trains. Day-by-day itinerary.")
print(reply.body)

reply.ask() 会保留之前的轮次，让 LLM 记住约束条件。再次调用 agent.ask(...) 则会开启一段全新对话。完整的旅行规划示例见 assets/multi_turn.py。

复用模型配置

配置是不可变的。使用 .copy(...) 派生出带覆盖项的副本：

base = OpenAIConfig(model="gpt-5")
hot = base.copy(temperature=0.8)
cheap = base.copy(model="gpt-5-mini")

也可以在每次 ask 时覆盖模型——适合用户按请求自带 API key 的情况：

agent = Agent("assistant", prompt="Help.")
reply = await agent.ask("Hello!", config=OpenAIConfig(model="gpt-5", api_key="sk-..."))  # pragma: allowlist secret

per-ask 配置会完全替换该轮对话中的 agent 配置。

深入了解

可运行入门（单轮）：assets/hello_agent.py（对应 code_examples/01）。
多轮入门：assets/multi_turn.py（对应 code_examples/03）。
完整提供商参考，包括 VertexAIConfig 认证、extra_body、自定义 httpx 客户端、环境变量回退表：website/docs/user-guide/model_configuration.mdx。
Agent 通信 API 面（事件、观测、HITL）：website/docs/user-guide/agents.mdx。
静态、动态、按轮提示词：website/docs/user-guide/system_prompts.mdx。

常见坑点

忘记 await——Agent / AgentReply 上的每个方法都是异步的。脚本中需用 asyncio.run(main()) 包裹。
两次调用 agent.ask() 却期望上下文延续——不会延续；应改用 reply.ask()。
硬编码 API key——优先使用环境变量回退（OPENAI_API_KEY 等），让配置能干净地提交。
跳过 streaming=True——AG2 以流式为一等设计；在支持的提供商上不开启会得到更差的用户体验。
per-ask 的 config= 是完全覆盖而非部分合并——需谨慎决定要设置哪些参数。