AssistantAgent 类详解

概述

AssistantAgent 是一个具备工具调用能力的智能助手代理类，继承自 BaseChatAgent 和 Component[AssistantAgentConfig]。它能够根据用户输入，调用模型和工具，自动完成任务，并支持流式输出、工具反射、上下文记忆、交接（handoff）等高级功能。

主要功能

• 支持模型推理与流式输出
• 支持工具调用与工具结果反射
• 支持多种上下文管理（如消息窗口、token 限制等）
• 支持记忆模块与上下文联动
• 支持任务交接（handoff）到其他代理
• 支持结构化输出（如 Pydantic 模型）

构造函数参数

• name (str): 代理名称。
• model_client (ChatCompletionClient): 用于推理的模型客户端。
• tools (可选, List[BaseTool/函数]): 可注册的工具列表。
• workbench (可选, Workbench): 工具工作台，和 tools 互斥。
• handoffs (可选, List[HandoffBase/str]): 任务交接配置。
• model_context (可选, ChatCompletionContext): 上下文管理器。
• description (str): 代理描述。
• system_message (可选, str): 系统消息，推理时会加在消息前。
• model_client_stream (bool): 是否启用流式输出。
• reflect_on_tool_use (bool): 工具调用后是否再次推理生成最终回复。
• tool_call_summary_format (str): 工具调用结果摘要格式。
• output_content_type (可选, type[BaseModel]): 结构化输出类型。
• output_content_type_format (可选, str): 结构化输出内容格式字符串。
• memory (可选, Sequence[Memory]): 记忆模块。
• metadata (可选, Dict[str, str]): 元数据。

主要行为说明

• on_messages / on_messages_stream：处理用户消息，返回最终回复或流式事件。
• run / run_stream：运行任务，返回 TaskResult 或流式消息。
• 工具调用：模型返回工具调用时，自动执行工具，支持并发。
• 工具反射：可配置是否在工具调用后再次推理生成最终回复。
• 交接（handoff）：支持将任务交接给其他代理。
• 上下文管理：支持消息窗口、token 限制、记忆模块等多种上下文管理方式。
• 结构化输出：可通过 output_content_type 返回结构化数据。

注意事项

• 仅需传入新消息，代理会自动维护历史状态。
• 该类非线程安全/协程安全，不可多任务/多协程共享。
• 工具名、交接名需唯一，且不能互相重名。
• 工具与 workbench 互斥。
• 某些模型（如 o1-mini）不支持 system_message 和 function calling。
• Claude 模型在工具反射时需注意工具定义完整性。

示例

基本用法

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

model_client = OpenAIChatCompletionClient(model="gpt-4o")
agent = AssistantAgent(name="assistant", model_client=model_client)
result = await agent.run(task="说出两个北美城市")
print(result)

工具调用

from autogen_core.tools import FunctionTool

def get_time() -> str:
    """返回当前时间"""
    return "12:00 PM"

tool = FunctionTool(get_time, description="获取当前时间")
agent = AssistantAgent(name="assistant", model_client=model_client, tools=[tool])

结构化输出

from pydantic import BaseModel
class Output(BaseModel):
    answer: str
agent = AssistantAgent(name="assistant", model_client=model_client, output_content_type=Output)

记忆模块

from autogen_core.memory import ListMemory, MemoryContent
memory = ListMemory()
await memory.add(MemoryContent(content="用户喜欢披萨。", mime_type="text/plain"))
agent = AssistantAgent(name="assistant", model_client=model_client, memory=[memory])

交接（handoff）

from autogen_agentchat.base import Handoff
handoff = Handoff(target="other_agent")
agent = AssistantAgent(name="assistant", model_client=model_client, handoffs=[handoff])

参考

• 支持的模型、工具、上下文、记忆等详细用法请参考官方文档。