AutoGen(三)智能体开发实战：让AI不仅会聊天，还能用工具和结构化输出！

AutoGen智能体开发实战摘要AutoGen框架将大语言模型封装为"智能体"(Agent)，赋予AI使用工具和结构化输出的能力。核心功能包括：工具调用：通过tools参数传入Python函数，AI能自动调用外部API、数据库等结构化输出：使用output_content_type指定Pydantic模型，使AI输出JSON等格式开发只需定义函数和输出模型，Agent就能实现复杂功能，显著提升AI

qq_27492797

872人浏览 · 2025-06-26 11:15:57

qq_27492797 · 2025-06-26 11:15:57 发布

AutoGen智能体开发实战：让AI不仅会聊天，还能用工具和结构化输出！

前言

大语言模型（LLM）如GPT-4、Qwen等，已经能实现非常强大的自然语言对话能力。但你是否发现，直接用AI模型只能做简单的问答和闲聊，一旦涉及到调用外部API、数据处理、自动化操作等复杂任务，模型就"无能为力"了？

AutoGen AgentChat 框架为我们提供了"智能体壳子"——Agent，让AI不仅能对话，还能像人一样"用工具"，甚至能输出结构化数据，极大拓展了AI的应用边界。本文将带你深入理解AutoGen智能体的核心机制，并手把手教你如何让AI输出你想要的格式！

1. 为什么要给AI套上"Agent壳子"？

直接用大模型（如OpenAI、Qwen等）只能做"纯文本对话"，无法主动调用外部工具、API、数据库等。

Agent壳子的作用：

让AI具备"用工具"的能力（如自动查资料、发HTTP请求、调用自定义函数等）
支持多智能体协作（如专家团队讨论、流程自动化）
支持结构化输出（如JSON、Pydantic模型等）

举例：

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.ollama import OllamaChatCompletionClient

model_client = OllamaChatCompletionClient(model="qwen2.5-coder:latest")
agent = AssistantAgent(
    name="assistant",
    model_client=model_client,
    tools=[web_search],  # 这里传入了一个Python函数
    system_message="Use tools to solve tasks.",
)

此时，assistant 不再只是"会聊天的AI"，而是一个能用工具的智能体！

2. AssistantAgent类参数详解与实用技巧

要让AI真正"聪明"起来，理解和灵活运用 AssistantAgent的各个参数非常关键。下面我们详细讲解常用参数的含义、作用及实战用法。

2.1 tools —— 工具参数

作用：让AI能够主动调用你自定义的Python函数，实现查资料、发请求、数据处理等能力。

本质：你传入的每个Python函数，都会被自动包装成"工具"，AI会根据函数签名和文档字符串自动学会怎么用。

如何创建工具？

定义函数（支持同步和异步）：

def web_search(query: str) -> str:
    """在网络上查找信息"""
    return "AutoGen是一个多智能体开发框架"

传递给tools参数：

agent = AssistantAgent(
    name="assistant",
    model_client=model_client,
    tools=[web_search],
    system_message="Use tools to solve tasks.",
)

实用场景：

自动查找资料、天气、股票等
数据库/接口查询
代码自动生成与执行

进阶技巧：

支持多个工具，直接传入函数列表
支持异步函数（async def …）
工具函数可以返回结构化数据（如Pydantic模型）

2.2 model_client —— 模型客户端

作用：指定底层大语言模型（如OpenAI、Qwen、Ollama等），决定AI的"智力水平"。

用法示例：

from autogen_ext.models.ollama import OllamaChatCompletionClient
model_client = OllamaChatCompletionClient(model="qwen2.5-coder:latest")

实用场景：

需要指定不同模型能力、版本、API密钥等
支持本地模型、云端模型灵活切换

2.3 system_message —— 系统消息

作用：为AI设定"角色"和"行为准则"，影响其整体风格和输出内容。

用法示例：

agent = AssistantAgent(
    name="assistant",
    model_client=model_client,
    tools=[web_search],
    system_message="你是一个专业的知识助手，善于用工具解决问题。",
)

实用场景：

设定AI为"专家"、“客服”、"编程助手"等不同身份
明确要求输出格式、风格、语言等

2.4 output_content_type —— 结构化输出类型

作用：让AI输出你自定义的数据结构（如Pydantic模型、JSON等），方便后续自动化处理。

用法示例：

from typing import Literal
from pydantic import BaseModel

class AgentResponse(BaseModel):
    thoughts: str
    response: Literal["happy", "sad", "neutral"]

agent = AssistantAgent(
    name="assistant",
    model_client=model_client,
    tools=[web_search],
    system_message="请用JSON格式输出，包含thoughts和response字段。",
    output_content_type=AgentResponse,
)

实用场景：

需要AI输出结构化数据，便于前端/后端自动处理
复杂业务流程、表单、报表等自动生成

2.5 其他常用参数

name：智能体名称，团队协作时需唯一
reflect_on_tool_use：是否让AI对工具调用结果进行反思，提升输出质量，默认情况True
- 该参数控制Agent在调用工具后，是否会对工具的执行结果进行"反思"并生成更符合用户需求的最终回复。
- 典型场景：如AI调用web_search工具查到一段资料后，会自动总结、归纳或用更友好的方式输出给用户，而不是直接返回原始结果。
- 关闭时的影响：如果将其设为False，Agent会直接返回工具的原始输出，适合需要极致性能或只关心原始数据的场景。
- 举例：
```
agent = AssistantAgent(
    name="assistant",
    model_client=model_client,
    tools=[web_search],
    reflect_on_tool_use=False,  # 关闭反思，直接返回工具结果
)
```
workbench：用于集成MCP等高级工具协议
output_stats：是否输出统计信息，便于调试和优化

通过灵活配置这些参数，你可以让AI不仅"会聊天"，还能"用工具"、“懂业务”、“输出结构化数据”，真正成为你的智能助手！

3. AssistantAgent自动工具化机制

看到这里你是否会有一个疑问，Agent是怎么调用工具，它是怎么了解用什么方式使用工具的？接下来我就为你讲解

实际上，AssistantAgent的自动工具化机制非常智能：

函数签名：指的是函数的参数名、类型、返回值类型等。例如：

def web_search(query: str) -> str:
    """Find information on the web"""
    return "AutoGen is a programming framework for building multi-agent applications."

query: str 就是参数签名，告诉AI这个工具需要一个字符串类型的参数

文档字符串（docstring）：就是函数体下方的三引号注释，描述了函数的用途和用法。AI会用它来理解工具的功能。
- """Find information on the web""" 让AI知道这个工具是"查找网络信息"
函数签名解析：Agent会自动读取你传入函数的参数名、类型、返回值类型（即函数签名），并据此生成工具的参数协议。例如，def web_search(query: str) -> str 会被解析为"需要一个字符串类型的query参数"。
文档字符串(docstring)提取：Agent还会读取函数体下方的三引号注释（docstring），将其作为工具的用途和用法说明，帮助大模型理解工具的功能和使用场景。
协议转化：框架会将这些信息自动转化为标准的工具调用协议（如OpenAI Function Calling、JSON Schema等），并传递给底层大模型。
LLM自动推理：大模型在收到用户请求时，会自动判断是否需要调用工具，并根据协议自动生成调用指令（如函数名、参数、调用顺序等），无需开发者手动干预。
开发者优化建议：你可以通过完善函数的类型注解和docstring，让Agent更好地理解工具的能力和边界，从而提升工具调用的准确率和智能体的整体表现。

小结：只要你写好函数签名和注释，Agent就能自动学会怎么用你的工具，极大降低了AI与外部系统集成的门槛！

4. 结构化输出是什么？怎么让Agent输出自定义格式？

4.1 结构化输出的意义

传统AI回复都是"纯文本"，但在实际开发中，我们常常需要AI输出结构化数据，比如JSON、Pydantic模型等，方便后续程序处理。

AutoGen支持让Agent直接输出结构化内容，极大提升了AI的可控性和可用性。

4.2 如何让Agent输出自定义格式？

步骤一：定义结构化数据模型

推荐用Pydantic定义输出格式。例如：

from typing import Literal
from pydantic import BaseModel

class AgentResponse(BaseModel):
    thoughts: str
    response: Literal["happy", "sad", "neutral"]

步骤二：在AssistantAgent中指定输出类型

from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent

model_client = OpenAIChatCompletionClient(model="gpt-4o")
agent = AssistantAgent(
    "assistant",
    model_client=model_client,
    system_message="Categorize the input as happy, sad, or neutral following the JSON format.",
    output_content_type=AgentResponse,  # 关键：指定结构化输出类型
)

步骤三：运行并获取结构化结果

result = await agent.run(task="I am happy.")
assert isinstance(result.messages[-1].content, AgentResponse)
print("Thought: ", result.messages[-1].content.thoughts)
print("Response: ", result.messages[-1].content.response)

实际输出：

{
  "thoughts": "The user explicitly states they are happy.",
  "response": "happy"
}

4.3 让Agent输出你想要的格式的技巧

定义好Pydantic模型，字段名、类型要清晰
system_message里明确要求格式，如"请用JSON格式输出，字段包括…"
output_content_type参数一定要传，否则AI只会输出纯文本
可以用Literal/Enum限制字段取值，提升可控性
多轮对话时，建议每轮都要求结构化输出

5. run 和 run_stream 有什么区别？

在AutoGen中，所有Agent都支持两种运行方式：

run：一次性运行，返回最终结果（适合脚本/批处理）
run_stream：流式运行，每生成一条消息就返回一次（适合实时交互、控制台输出）

示例代码：

result = await agent.run(task="Find information on AutoGen")
print(result.messages)

run 方法会把整个任务的"思考过程"和最终回复都放在 result.messages 里，一次性返回。

如果你想边生成边显示，可以用 run_stream：

async def assistant_run_stream() -> None:
    await Console(
        agent.run_stream(task="Find information on AutoGen"),
        output_stats=True,
    )
await assistant_run_stream()

run_stream 方法会在每条消息生成时就 yield 出来，适合做实时展示、进度条等。

总结：

run 适合拿到最终结果后统一处理
run_stream 适合需要"边生成边看"的场景

6. 实战案例：让AI自动查资料并结构化输出

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.ollama import OllamaChatCompletionClient
from pydantic import BaseModel

# 定义结构化输出模型
class SearchResult(BaseModel):
    summary: str
    url: str

# 定义工具函数
async def web_search(query: str) -> SearchResult:
    # 实际开发中可调用API
    return SearchResult(summary="AutoGen是一个多智能体开发框架", url="https://github.com/microsoft/autogen")

model_client = OllamaChatCompletionClient(model="qwen2.5-coder:latest")
agent = AssistantAgent(
    name="assistant",
    model_client=model_client,
    tools=[web_search],
    system_message="请根据用户问题自动查找资料，并用JSON格式输出结果，包含summary和url字段。",
    output_content_type=SearchResult,
)

result = await agent.run(task="AutoGen是什么？")
print(result.messages[-1].content.summary)
print(result.messages[-1].content.url)