ag2-quickstart

快速入门：构建你的第一个 AG2 Agent

适用场景

• 用户从空白文件开始，希望构建一个可运行的 AG2 Agent。
• 用户不确定该使用哪种提供商配置。
• 用户希望接续后续轮次，同时保留对话上下文。
• 较大的任务需要以基本 Agent 设置为骨架——从这里开始，然后叠加相关功能技能。

前置条件

必需步骤：完成前安装依赖。 编写 AG2 代码后，安装对应的提供商扩展（以及任务所需的任何功能扩展，例如 ag-ui、tracing）。运行安装命令：

pip install "ag2[openai]"   # 替换为你使用的提供商/扩展

如果无法运行命令，请写明确切的 pip install 命令。这是完成任务的一部分，并非可选备注。

对于多文件项目（而非一次性脚本），还应添加一个 requirements.txt，锁定使用的扩展对应的 ag2 版本（例如 ag2[openai]>=0.14.0），以确保环境可复现。

安装正确的提供商扩展，并准备好对应的密钥。每个 *Config 都需要其提供商 SDK——如果没有安装匹配的扩展，就会看到 ImportError: ... requires optional dependencies. Install with 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 密钥）	pip install "ag2[gemini]"	GEMINI_API_KEY（或 GOOGLE_API_KEY）	GeminiConfig
Vertex AI（Gemini）	pip install "ag2[gemini]"	服务账号 / 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 等），请使用设置了 base_url= 的 OpenAIConfig：

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() 会保留此前轮次的上下文，让大模型记住相关约束。再次调用 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 密钥时，这很有用：

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

每次 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 密钥硬编码——优先使用环境变量回退（OPENAI_API_KEY 等），以便安全地提交配置。
• 未设置 streaming=True——AG2 以流式处理为先；在支持流式处理的提供商中，不启用该选项会降低用户体验。
• 每次调用 ask 时设置的 config= 会完全覆盖配置，而不是进行部分合并——请谨慎选择要设置的选项。