Python Agent 开发实战：从工具到系统的 5 层架构避坑指南

很多团队在开发智能体（Agent）时，往往一开始就把事情想得过于复杂。他们直接着手构建多智能体协同、自主推理循环或极其复杂的底层架构，结果花费数周时间调试，却发现连最基本的任务都无法完成。

我一直遵循一个简单到“不好意思说”的原则：从极简开始，逐步叠加能力，每一步都验证行为。

今天，我们就来拆解智能体软件的 5 个层级架构，并亲手搭建一个轻量级的编码智能体，从最基础的一层开始，逐级向上添加能力。和往常一样，我会为每个层级附上可直接运行的代码片段。

以下是我们要探讨的五个层级：

• 带工具的智能体
• 带存储与知识库的智能体
• 带记忆与学习能力的智能体
• 多智能体团队
• 生产级系统

层级 1：带工具的智能体

没有工具的智能体，本质上只是一个大型语言模型（LLM）。它擅长推理，却无法对世界产生任何实际影响。工具，才是将 LLM 转变为真正可行动的 Agent 的关键。

对于一个编码智能体而言，最小可行的工具集通常包括：读取文件、写入文件以及执行 Shell 命令。

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.coding import CodingTools

WORKSPACE = Path(__file__).parent.joinpath("workspace")
WORKSPACE.mkdir(parents=True, exist_ok=True)

agent = Agent(
    name="Gcode",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions=(
        "You are a coding agent. Write clean, well-documented code. "
        "Always save your work to files and test by running them."
    ),
    tools=[CodingTools(base_dir=WORKSPACE, all=True)],
    markdown=True,
)

agent.print_response(
    "Write a Fibonacci function, save it to fib.py, and run it to verify",
    stream=True,
)

发生了什么？

智能体接收到任务，通过 CodingTools 来编写、编辑和运行代码。参数 all=True 会启用编码工具包中的所有能力，包括读、写、编辑、Shell、grep、find、ls 等。

缺少什么？

• 每次运行都从零开始：没有状态保持。
• 无法回忆上一次会话：智能体不知道之前与你聊过什么。
• 不遵守项目约定：除非你将规范明确写入提示词，否则它不会遵循。
• 没有额外知识：除了当前对话上下文，它无法获取任何领域知识。

层级 2：带存储与知识库的智能体

层级 1 的智能体是无状态的，所有信息都必须挤在有限的上下文窗口里。层级 2 通过引入 会话存储 和 领域知识 来解决这个问题。

存储

存储机制会将每一次智能体的会话和运行记录存入数据库，这带来了两个核心价值：

1. 把聊天历史作为上下文：智能体可以将最近的 N 条消息纳入上下文窗口，从而了解当前的对话进度。对于长会话，还可以使用压缩算法来总结早期内容，让模型更专注于当下的关键信息。
2. 行为记录可追溯：并非所有内容都需要发送到第三方追踪平台。将会话存储在自己的数据库中是最简单的方式，你可以清晰地知道智能体做了什么、何时做的、以及为什么这样做。数据完全归你所有，你可以随时查询、审计，甚至基于此构建数据看板。

知识

当前的编码智能体通常只能访问你代码库中的文件，但它看不到：

• 架构文档
• 团队的设计决策记录
• 内部会议纪要
• Slack 中关于“为什么选择 Postgres 而非 DynamoDB”的讨论

这就是 知识库 要解决的问题。它为智能体提供了一个 可检索的仓库，用于存放所有对项目重要，但又不必时刻塞在上下文窗口里的信息：编码规范、需求文档、运行手册、架构决策记录、会议纪要、团队对话片段等。

核心认知在于：许多有价值的上下文信息，其实都在代码库之外。

from agno.db.sqlite import SqliteDb
from agno.knowledge import Knowledge
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.vectordb.chroma import ChromaDb, SearchType

db = SqliteDb(db_file=str(WORKSPACE / "agents.db"))

knowledge = Knowledge(
    vector_db=ChromaDb(
        collection="coding-standards",
        path=str(WORKSPACE / "chromadb"),
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

agent = Agent(
    name="Gcode",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions=(...),
    tools=[CodingTools(base_dir=WORKSPACE, all=True)],
    knowledge=knowledge,
    search_knowledge=True,
    db=db,
    add_history_to_context=True,
    num_history_runs=3,
    markdown=True,
)

有什么变化？

我们新增了两样东西：

• 基于 ChromaDb 的知识库（支持语义+关键词的混合检索）
• 用于会话存储的 SqliteDb

现在，智能体可以：

• 在编写代码前先检索知识库（例如，如果你的风格指南要求使用蛇形命名法，它会找到并遵守）。
• 记住对话上下文：在同一会话中询问后续问题时，它拥有完整的聊天历史。

注入知识

你可以将文本、PDF 或 URL 插入知识库。运行时，智能体会检索相关的知识片段并加入到上下文中，这就是基础的 Agentic RAG 流程。

# Load your coding standards
knowledge.insert(text_content="""
## Project Conventions
- Use type hints on all function signatures
- Write docstrings in Google style
- Prefer list comprehensions over map/filter
""")

什么时候用层级 2？

• 智能体需要遵守它未经训练过的特定规范时。
• 用户期望进行多轮对话，且需要上下文连贯性时。

对于大多数内部工具的开发来说，这是 最佳平衡点。如果你在为项目寻找更多关于架构设计的灵感，可以访问 云栈社区的技术文档 板块。

层级 3：带记忆与学习能力的智能体

从层级 2 到层级 3，是 最重要的一次跃迁。

• 层级 2：智能体遵守你设定的规则。
• 层级 3：智能体从经验中 自己学习规则。

理想情况下，第 1000 次交互的质量理应比第 1 次更高。

from agno.learn import LearnedKnowledgeConfig, LearningMachine, LearningMode
from agno.tools.reasoning import ReasoningTools

learned_knowledge = Knowledge(
    vector_db=ChromaDb(
        collection="coding-learnings",
        path="tmp/chromadb",
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

agent = Agent(
    name="Gcode",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions=(...),
    tools=[
        CodingTools(base_dir=WORKSPACE, all=True),
        ReasoningTools(),
    ],
    knowledge=docs_knowledge,
    search_knowledge=True,
    learning=LearningMachine(
        knowledge=learned_knowledge,
        learned_knowledge=LearnedKnowledgeConfig(
            mode=LearningMode.AGENTIC,
        ),
    ),
    enable_agentic_memory=True,
    db=db,
    markdown=True,
)

有什么变化？

1. 学习机器：智能体获得了 save_learning 和 search_learnings 工具，可以自主决定哪些经验值得记住：
   • 好用的编码模式
   • 需要避开的错误
   • 用户的特定偏好
     这些“学习成果”会被存储在一个独立的知识库中，并在未来的会话中被自动检索和调用。
2. 智能体记忆：智能体会逐渐为用户建立档案，记录其偏好的编码风格、常用框架、喜欢的解释方式等。

双会话测试

# 会话 1：用户告知偏好
agent.print_response(
    "I prefer functional programming style — no classes, "
    "use pure functions and immutable data. Write a data pipeline.",
    session_id="session_1",
)

# 会话 2：新任务 —— 智能体应自动应用偏好
agent.print_response(
    "Write a log parser that extracts error counts by category.",
    session_id="session_2",
)

在会话 2 中，智能体会检索之前的学习记录，找到“偏好函数式编程”这条信息，并据此写出对应风格的代码。

什么时候用层级 3？

• 智能体需要反复为同一批用户服务。
• 系统需要随时间推移不断自我优化、变得更好。
• 场景是个人编码助手或团队共享的学习型工具。
• 任何“按照我们习惯的方式来做”这一点非常重要的场合。

层级 4：多智能体团队

有些任务过于复杂，单个智能体难以胜任。层级 4 将职责拆分给 多个专业化的智能体，并由一个“团队负责人”智能体进行统一协调。

from agno.team.team import Team

coder = Agent(
    name="Coder",
    role="Write code based on requirements",
    tools=[CodingTools(base_dir=WORKSPACE, all=True)],
    ...
)

reviewer = Agent(
    name="Reviewer",
    role="Review code for quality, bugs, and best practices",
    tools=[CodingTools(base_dir=WORKSPACE, enable_write_file=False,
                       enable_edit_file=False, enable_run_shell=False)],
    ...
)

tester = Agent(
    name="Tester",
    role="Write and run tests for the code",
    tools=[CodingTools(base_dir=WORKSPACE, all=True)],
    ...
)

coding_team = Team(
    name="Coding Team",
    members=[coder, reviewer, tester],
    instructions=(...),
    show_members_responses=True,
    markdown=True,
)

分工明确：

• Coder：负责编写代码。
• Reviewer：权限为只读（不能写、不能编辑、不能执行 Shell），专司代码审查。
• Tester：负责编写并运行测试。
  团队负责人则负责协调工作流程并汇总最终结果。

坦诚提醒

多智能体团队的能力很强，但也 极其不可预测。团队负责人本身也是一个 LLM，它在进行任务分配决策，有时做得好，有时则不然。

对于重视稳定性的生产系统，应优先考虑使用明确、定义好的工作流，而非动态的多智能体团队。多智能体团队更适合 有人类监督 的场景，人类可以审核其最终输出，干预错误的协作路径。

什么时候用层级 4？

• 需要多个视角进行校验（例如严格的代码审查）。
• 任务天然可以拆分为不同的专家角色。
• 构建有人类监督的交互式工具。

层级 5：智能体系统（生产级 API）

层级 5 是将前面 1-4 级的能力，打包成一个 生产就绪的服务运行时。你需要从开发库升级到生产级组件，加入完善的追踪能力，并将所有功能通过 API 暴露出来。

from agno.db.postgres import PostgresDb
from agno.vectordb.pgvector import PgVector, SearchType
from agno.os import AgentOS

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
db = PostgresDb(db_url=db_url)

knowledge = Knowledge(
    vector_db=PgVector(
        db_url=db_url,
        table_name="coding_knowledge",
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

# ... create your Level 3 agent with production db ...

agent_os = AgentOS(
    id="Gcode OS",
    agents=[coding_agent],
    teams=[coding_team],
    config=config_path,
    tracing=True,
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="run:app", reload=True)

有什么变化？

• PostgreSQL + PgVector 替代了 SQLite + ChromaDb，带来了真正的连接池、备份和并发处理能力。
• AgentOS 将你的智能体封装成 FastAPI 应用，自带 Web UI、会话管理和追踪功能。
• Tracing 让你能够观测每一次工具调用、每一次知识检索和每一次任务分配决策，为线上问题排查提供了可能。

什么时候用层级 5？

• 智能体不再仅仅运行在你个人的开发机上。
• 需要支持多用户同时使用。
• 对系统的可用性和稳定性有明确要求。
• 需要具备线上问题排查与观测能力。

最重要的建议

务必从层级 1 开始。

先构建一个能解决核心问题的最简智能体，让它跑起来。仔细观察它在哪里卡住，遇到了什么困难，然后 精准地为其补上所缺的那一项能力。

我看到太多团队直接跳到了层级 4，因为多智能体架构在演示中看起来非常炫酷。结果他们花费了数月时间来调试智能体间的协作问题，而这些问题，一个指令撰写得当的单智能体本就可以轻松避免。

请将这 5 个层级视为一个 能力阶梯：每向上攀登一级，系统的复杂度和维护成本也会相应上升。在云栈社区的人工智能板块，你可以找到更多关于 Agent、RAG 等前沿技术的深度讨论和实战案例，帮助你在正确的层级上做出选择。明智的做法是，只在当前层级无法满足需求时，才考虑升级到下一层。