AI代理设计指南
本指南将代理设计分解为五个实际难度级别,每个级别均提供可运行的代码示例。
无论开发者是初学者还是处理现实世界的复杂任务,本指南都能帮助避免常见陷阱,构建真正有效的代理。
这些级别包括:
•级别1:带工具和指令的代理•级别2:带知识和记忆的代理•级别3:带长期记忆和推理的代理•级别4:多代理团队•级别5:代理系统
以下逐一介绍各级别。

级别1:带工具和指令的代理
此级别为基础设置,涉及一个遵循指令并在循环中调用工具的大语言模型(LLM)。当提到“代理是LLM加上工具使用”时,通常指这一级别,反映了基础但功能有限的实现。

指令明确代理的任务,工具赋予其行动能力,例如获取数据、调用API或触发工作流程。尽管简单,此设置已足以自动化某些任务。
from agno.agent importAgent
from agno.models.openai importOpenAIChat
from agno.tools.duckduckgo importDuckDuckGoTools
agno_assist =Agent(
name="Agno AGI",
model=OpenAIChat(id="gpt-4.1"),
description=dedent("""\
Agno AGI是一个利用Agno框架构建代理的自主AI代理。其目标是通过提供解释、可运行的代码示例以及可选的视觉和音频解释,帮助开发者理解和使用Agno的关键概念。"""),
instructions="搜索网络以获取关于Agno的信息。",
tools=[DuckDuckGoTools()],
add_datetime_to_instructions=True,
markdown=True,
)
agno_assist.print_response("Agno是什么?", stream=True)
级别2:带知识和记忆的代理
许多任务需要模型不具备的外部信息。由于上下文容量有限,代理需在运行时获取知识,这通过代理式RAG或动态少样本提示实现。

搜索采用混合模式(全文+语义),并需重新排序。混合搜索结合重新排序是代理式检索的最佳即插即用方案。
存储功能为代理提供记忆。LLM默认无状态,存储过去的行动、消息和观察结果使代理具备状态,能够参考历史信息并优化决策。
... imports
# 可参考 https://docs.agno.com/llms-full.txt 获取完整文档
knowledge_base =UrlKnowledge(
urls=["https://docs.agno.com/introduction.md"],
vector_db=LanceDb(
uri="tmp/lancedb",
table_name="agno_docs",
search_type=SearchType.hybrid,
embedder=OpenAIEmbedder(id="text-embedding-3-small"),
reranker=CohereReranker(model="rerank-multilingual-v3.0"),
),
)
storage =SqliteStorage(table_name="agent_sessions", db_file="tmp/agent.db")
agno_assist =Agent(
name="Agno AGI",
model=OpenAIChat(id="gpt-4.1"),
description=...,
instructions=...,
tools=[PythonTools(),DuckDuckGoTools()],
add_datetime_to_instructions=True,
# 当提供“knowledge”时,默认启用代理式RAG
knowledge=knowledge_base,
# 将代理会话存储在sqlite数据库中
storage=storage,
# 将聊天历史添加到消息中
add_history_to_messages=True,
# 历史运行次数
num_history_runs=3,
markdown=True,
)
if __name__ =="__main__":
# 加载知识库,首次运行后可注释
# agno_assist.knowledge.load(recreate=True)
agno_assist.print_response("Agno是什么?", stream=True)
级别3:带长期记忆和推理的代理
长期记忆使代理能够跨会话回忆细节,例如用户偏好、过去行为或失败尝试,并随时间适应,从而实现个性化和连续性。自我学习——基于过去经验优化行为——是此级别的重要潜力。
推理能力进一步提升代理表现,帮助分解问题、优化决策并更可靠地执行多步骤指令。推理不仅关乎理解,还能提高每一步的成功率,是严肃代理开发者必须掌握的核心技能。
... imports
knowledge_base =...
memory =Memory(
# 使用任意模型创建记忆
model=OpenAIChat(id="gpt-4.1"),
db=SqliteMemoryDb(table_name="user_memories", db_file="tmp/agent.db"),
delete_memories=True,
clear_memories=True,
)
storage =...
agno_assist =Agent(
name="Agno AGI",
model=Claude(id="claude-3-7-sonnet-latest"),
# 用于记忆的用户ID
user_id="ava",
description=...,
instructions=...,
# 赋予代理推理能力
tools=[PythonTools(),DuckDuckGoTools(),
ReasoningTools(add_instructions=True)],
...
# 将记忆存储在sqlite数据库中
memory=memory,
# 让代理管理其记忆
enable_agentic_memory=True,
)
if __name__ =="__main__":
# 首次运行后可注释,代理会记住
agno_assist.print_response("总是以‘hi ava’开始你的消息", stream=True)
agno_assist.print_response("Agno是什么?", stream=True)
级别4:多代理
代理在专注于单一领域并配备精简工具集(理想少于10个)时表现最佳。为应对复杂或广泛任务,可将多个代理组成团队,每个代理处理问题的一部分,共同覆盖更广领域。

然而,若团队领导者缺乏强大推理能力,处理细微问题时易失败。当前,自主多代理系统的可靠性不足,成功率低于50%,尚无法满足实际需求。
某些架构可简化协调。例如,Agno支持协调、路由和协作三种执行模式,并提供内置的记忆和上下文管理。谨慎设计仍不可或缺,但这些功能使多代理工作更具可行性。
... imports
web_agent =Agent(
name="Web Search Agent",
role="处理网页搜索请求",
model=OpenAIChat(id="gpt-4o-mini"),
tools=[DuckDuckGoTools()],
instructions="始终包含来源",
)
finance_agent =Agent(
name="Finance Agent",
role="处理金融数据请求",
model=OpenAIChat(id="gpt-4o-mini"),
tools=[YFinanceTools()],
instructions=[
"你是一个金融数据专家。提供简洁准确的数据。",
"使用表格展示股票价格、基本面(市盈率、总市值)",
],
)
team_leader =Team(
name="Reasoning Finance Team Leader",
mode="coordinate",
model=Claude(id="claude-3-7-sonnet-latest"),
members=[web_agent, finance_agent],
tools=[ReasoningTools(add_instructions=True)],
instructions=[
"使用表格展示数据",
"仅输出最终答案,不包含其他文本。",
],
show_members_responses=True,
enable_agentic_context=True,
add_datetime_to_instructions=True,
success_criteria="团队已成功完成任务。",
)
if __name__ =="__main__":
team_leader.print_response(
"""\
分析近期美国关税对以下关键行业市场表现的影响:
-钢铁和铝业:(X, NUE, AA)
-技术硬件:(AAPL, DELL, HPQ)
对每个行业:
1.比较关税实施前后的股票表现
2.识别供应链中断和成本影响百分比
3.分析公司的战略应对(回岸生产、价格调整、供应商多元化)""",
stream=True,
stream_intermediate_steps=True,
show_full_reasoning=True,
)
级别5:代理系统
代理系统标志着代理从工具转变为基础设施。此级别涉及完整API,接受用户请求,启动异步工作流程,并流式返回生成的结果。

理论上流程清晰,实际操作极具挑战。需在请求时持久化状态,启动后台作业,跟踪进度,并流式输出结果。WebSocket可提供支持,但扩展和维护难度较大,后端复杂性常被低估。
这一级别是将代理转化为实际产品的关键,不仅是构建功能,而是打造完整系统。
从失败到成功:代理设计的关键经验教训
构建AI代理的核心在于夯实基础,而非追逐潮流或堆砌功能。从基本工具使用到完全异步的代理系统,每一级别需建立在稳固的架构之上,方能增强能力。
失败往往源于忽视基础原则:清晰的模块边界、扎实的推理、有效的记忆管理,以及适时引入人工干预。
通过从简单开始,逐步有针对性地增加复杂性,仅在解决实际问题时引入新功能,开发者能够构建出不仅有趣且真正可靠的代理系统。
(文:PyTorch研习社)