构建会学习的 AI Agent：从架构到实现

大多数“如何构建 Agent”的文章都会直接进入代码环节。然而，我们见过的每一个取得突破的 Agent，早在第一次执行 pip install 之前就已经开始孕育了。它始于三个不动声色的习惯：

记住这些习惯，接下来的技术工作就不会显得那么令人生畏，反而会更有成就感。

文章涵盖了什么，又缺少什么

本文会逐一介绍我们在多个 Agent 相关用例中使用的代码块，其中包括共享的代码片段和搜索片段——你可以通过 Pieces 分享它们——用于展示一些具体功能。

这些代码块本身很有用，但不足以构建一个完全自主的 Agent 系统。

例如，你会注意到 Qdrant 代码片段引用了一个 ltm collection，但文章没有在任何地方定义它，也没有交代相关上下文。

缺少这些信息，你可能只能靠猜。

因此，尽管这些代码体现了文章提到的概念，但不应该把它们当成一套开箱即用的框架。

事实上，构建 Agent 并不是真的要照搬别人的结构。

正如我们的机器学习工程负责人所说：

“人们会用各种方式构建 Agent，并不存在唯一‘正确’的框架。不过，几乎每一种严肃的实现中都会出现三个共同组件：

Thought——LLM 判断下一步应该做什么。

Action——Agent 通过工具或 API 执行操作。

Observation——模型分析工具的输出，并决定接下来该做什么。”

对于想要初步尝试设计 Agent 的人来说，这是一份非常出色的资源。

为什么我们仍然分享这些代码块

即使本文没有提供构建生产级 Agent 的分步教程，我们仍然分享了这些代码块，希望它们能够启发思路、鼓励实验。

它们是建筑材料，而不是施工蓝图。

如果你把这些材料与三个基础习惯——捕获、提问和反思——结合起来，就能在构建 Agent 系统时占据更有利的位置：它不仅可以正常工作，还能真正发挥作用。

为 Agent 添加记忆层

没有记忆的模型，只是一只聪明的鹦鹉。

拥有记忆之后，模型才能成为你的伙伴。你的第一个架构决策是什么？vector store？graph？还是 Hybrid？

这个选择会为之后的每一次成功或失败埋下伏笔。

启动记忆存储

pip install qdrant-client openai

  -e NEO4J_AUTH=neo4j/password \
  -p7474:7474 -p7687:7687 neo4j:latest
pip install neo4j

同时运行两者：将 embeddings 存入 Qdrant，将 edges 存入 Neo4j。

当你浏览比较 Pinecone、Qdrant 和 Weaviate 的博客文章时，Pieces 会在后台自动收集代码片段、示意图和优缺点对照表。

一个月后，当你想知道“面对 100 万个 vectors 时，哪种存储速度最快？”你不必打开浏览器，而是会打开 Pieces。

设计最小化 schema

提示：所有数据都使用 UTC 存储，在 UI 中进行转换。

编写上下文检索器

def fetch_context(query: str, top_k: int = 5):
    embedding = openai.embeddings.create(
        model="text-embedding-3-small",
        input=query
    ).data[0].embedding
    matches = qdrant_client.search(
        collection_name="ltm",
        query_vector=embedding,
        limit=top_k,
        with_payload=True
    )
    return [m.payload for m in matches]

我已经像上面这样把 embeddings 存入 Qdrant。应该如何批量插入文档，并确保 cosine similarity 配置正确？

继续深挖，直到你无需查看笔记也能把它解释清楚。

锻炼自己的好奇心，是在为那些尚未遇到的 bug 做准备。

Pieces 会成为你在架构决策上的良知，适时呈现你曾写给未来自己的笔记。

构建推理引擎

如果 Agent 无法利用记忆进行思考，那么记忆毫无用处。推理层负责把原始上下文转化为有帮助的行动。

SYSTEM_PROMPT = """
You are a step-by-step reasoning agent. 
Use the provided context first; only fall back to general knowledge if needed.
"""
USER_TEMPLATE = """
Question: {question}

Context:
{context}

Answer in JSON with keys: "answer", "thought_process".
"""

from langchain.chains import LLMChain
prompt = PromptTemplate(
    input_variables=["question", "context"],
    template=SYSTEM_PROMPT + USER_TEMPLATE
)
chain = LLMChain(llm=model, prompt=prompt)

import json, re
def safe_call(q, ctx):
    raw = chain.run(question=q, context=ctx)
    try:
        data = json.loads(raw)
        assert "answer" in data
        return data["answer"]
    except Exception:
        return "Sorry, I’m unsure. Can you clarify?"

遇到困难时询问 ChatGPT

Prompt：为什么我的 LangChain chain 有时会在 JSON 周围返回多余的 Markdown？

追问：给我一个 regex，用于安全地移除三重反引号代码块。

不断追问，直到答案变得稀松平常；然后动手实现。

建立学习闭环

静态 Agent 的过时速度就像牛奶变质一样快。学习闭环能让它们保持新鲜。

feedback_db.insert({
    "query": query,
    "response": answer,
    "grade": "good" if user_upvote else "bad",
    "timestamp": datetime.utcnow()
})

做出选择：Fine-Tune 还是更新 RAG

延迟：在 LLM call 前后使用 time.perf_counter()。

准确率：将 model answer 与 gold JSON 进行 Diff。

Token 成本：usage.total_tokens。

将 dashboards 放在 Grafana 中。六个月后某项 metric 突然飙升时，Pieces 仍然会记得你调整过哪个 panel。

把 ChatGPT 当作导师

Prompt：推荐三个能够自动检测 RAG pipeline 中 model drift 的指标，并解释各自的优缺点。

将这段对话保存在 Pieces 中；未来的你会在事故复盘时重新读到它。

提供人机交互界面

即使是最聪明的 Agent，如果用户无法使用，也会在无人知晓的角落里消亡。

使用 FastAPI 提供 REST API

from fastapi import FastAPI
app = FastAPI()

@app.post("/ask")
async def ask(q: Query):
    ctx = fetch_context(q.text)
    ans = safe_call(q.text, ctx)
    return {"answer": ans}

@app.command("/askagent")
def handle(ack, body, respond):
    ack()
    q = body["text"]
    ctx = fetch_context(q)
    ans = safe_call(q, ctx)
    respond(ans)

复用 REST endpoint。payload 只使用 JSON。

Pieces 提醒：它会保存你定义的每一份 API contract、auth header 和 error pattern，因此 V2 移动应用可以自动继承这些经验。

AI monitoring 不只是观察 CPU 图表，还要衡量它对人的实际影响。

将 incident playbooks 保存在 Pieces 中，这样值班工程师醒来时面对的是完整上下文，而不是一片混乱。

与问题、记忆和反思相伴的一天

上午

你开始编写代码。Autocomplete 因为一个少见的 npm error 而失败。询问 ChatGPT：“macOS M1 上出现 MODULE_NOT_FOUND / bcrypt 的常见原因是什么？”继续追问：“哪个 env flag 可以修复它？”把修复方案复制到 VS Code 中。Pieces 会捕获问答记录和解决方案。

你开始编写代码。Autocomplete 因为一个少见的 npm error 而失败。

询问 ChatGPT：“macOS M1 上出现 MODULE_NOT_FOUND / bcrypt 的常见原因是什么？”

继续追问：“哪个 env flag 可以修复它？”

把修复方案复制到 VS Code 中。Pieces 会捕获问答记录和解决方案。

下午

你正在设计一个 vector schema。你在 Google 上搜索了十几篇教程。Pieces 会自动收集它们。感到困惑？询问 ChatGPT：“Vector 与 HNSW 有什么区别，为什么应该选择其中一个？”把最好的回答标记为有启发性。

你正在设计一个 vector schema。你在 Google 上搜索了十几篇教程。

Pieces 会自动收集它们。

感到困惑？询问 ChatGPT：“Vector 与 HNSW 有什么区别，为什么应该选择其中一个？”

把最好的回答标记为有启发性。

晚上

你的 Agent 错误地对一条用户 query 进行了分类。回想一下：Pieces 会呈现你上个月写下的“regex guardrail”笔记。实现修复。Commit。Push。

你的 Agent 错误地对一条用户 query 进行了分类。

回想一下：Pieces 会呈现你上个月写下的“regex guardrail”笔记。

实现修复。Commit。Push。

记忆、问题和反思形成了一个良性循环。没有炒作，只有稳定的进步。

经常遇到的“卡住”时刻

伙伴关系范式

构建一个 Agent 是一场短跑。构建一份围绕 Agent 的长期事业，则是一场依靠认知复利完成的马拉松。

Pieces 是一本你永远不会弄丢的笔记本。ChatGPT 是一位永远不会厌倦回答问题的同事。

它们共同创造了一个循环：

好奇心引发问题。

ChatGPT 给出回答，你负责实验。

Pieces 捕获结果和上下文。

下一个项目从更高的起点开始。

这个循环能够胜过任何单一的“天才技术栈”，因为它真正实现规模化提升的是你——你的直觉、品味和记忆。

启动记忆存储。

下次遇到困难时，打开 ChatGPT，不断追问“为什么？”，直到答案变得显而易见。然后让 Pieces 把这次突破归档到未来的你能够立即找到的位置。

这就是构建 Agent 和积累专业能力的方法：让它们与你一起思考、共同成长。