从0搭一个AI Agent（一）：为什么你需要的不是“调一次API”

很多人以为接入大模型，就是把接口 curl 一下，拿到文本往页面上一贴，完事。

我独立做了一年AI应用（玄镜，一套已上线的占卜/疗愈Web产品），可以很肯定地说：单次API调用，连一个能上线的功能都撑不起来，更别说产品。

这篇文章是系列开篇。先不碰框架，把这个认知掰清楚------后面几篇我们直接上手 LangGraph。

一、直接调 API，到底差在哪

假设你要做一个"今日运势"功能。用户问一句"我今天运势怎么样"，一个能用的系统需要完成五步：

理解意图：用户问的是整体运势，还是感情、事业？
检索知识：从知识库里拉取对应的解读素材（RAG）。
确定性计算 ：根据生辰算出排盘结果。这一步必须100%准确，不能让模型"推理"出一个答案。
生成解读：把结构化数据组装成用户能看懂的文字。
流式返回：边生成边展示，而不是转圈等5秒。

这五步里，单次 API 调用只覆盖第4步。理解、检索、计算、流式------全得你自己用代码串起来。

大模型是能力引擎，不是完整产品。 Agent 干的事，是把引擎装进一个会自己决定下一步该干什么的程序里。

二、Agent 的本质，是一个循环

Agent 不是"更高级的聊天框"。它的核心结构极其简单：

复制代码

感知（输入/上下文）
   → 思考（LLM 决定下一步）
   → 行动（调工具：查库/算数/调接口）
   → 观察（拿到结果）
   → 再思考 ...... 直到收尾

关键区别在于：下一步做什么，由模型在运行时决定，而不是你在代码里写死的 if-else。 这是"智能体"和"普通脚本"的分水岭。

不用任何框架，十行 Python 就能表达这个本质：

python 复制代码

def run_agent(user_input, tools):
    messages = [{"role": "user", "content": user_input}]
    while True:
        decision = llm.decide(messages, tools)  # 模型决定：直接回答，还是调工具
        if decision.is_final:
            return decision.reply
        result = tools[decision.tool](decision.args)  # 执行工具
        messages.append({"role": "tool", "content": result})  # 结果回灌，继续循环

这三步------决策 → 执行 → 回灌------就是所有 Agent 框架（包括 LangGraph）最终在底层干的事。

但请注意：这段代码如果直接上线，大概率会烧光你的 API 额度。 因为它没有限制循环次数，没有校验工具返回的格式，也没有处理"工具挂了"的情况。真实产品里复杂的地方从来不在骨架，而在骨架外面那一圈护栏。这是后面第四篇要展开的。

三、为什么说"会调 API"和"能做 Agent 产品"是两件事

掘金上已经有很多文章在讲怎么用 LangChain 或 LangGraph "跑通一个 Agent"。跑通确实不难。难的是跑通之后------模型在真实用户面前抽风的时候，你的系统能不能兜住。 -14

我踩过的坑包括但不限于：

排盘数据模型自己"编" ：用户给了完整生辰，模型有时仍然不调用工具，直接回一句"无法获取信息"。后来我把"该不该排盘"从"赌模型决策"改成了服务端的确定性判断。
全量 JSON 直接灌上下文：排盘结果上万字符，不做压缩直接喂给模型，上下文挤爆，成本翻倍，生成质量反而下降。
没有循环上限的 while True：一个格式错误的工具返回，足够让 Agent 在同一个坑里反复调用，直到预算耗尽。

"调一次 API"解决的是"模型能说话"的问题。Agent 工程要解决的是"模型说了不该说的话、或者不说话的时候，产品怎么继续运转"的问题。

四、这个系列后面讲什么

（二）用 LangGraph 把循环显式化：把"思考→调用→回复"画成图，而不是埋在一堆 if 里。
（三）SSE 流式输出：让首字延迟从"转圈5秒"变成"立刻出字"。
（四）生产级运行时：超时、重试、格式约束、输出校验------那圈"护栏"具体怎么搭。
（五）多智能体编排：什么时候该拆，什么时候一个 Agent 撑着反而更好。

写在最后

如果你也在做 AI 应用，或者团队在招 前端 + AI 应用 / 全栈 AI 方向的人------可以看看我的项目。

玄镜（OracleMind） 是我独立从 0 到 1 交付的生产级 AI 平台，LangGraph + RAG + SSE 流式，前端 Next.js、后端 FastAPI、AI 服务三端解耦。我关注的不只是"把模型接进来"，而是把不稳定的 LLM 输出做成稳定的产品能力。

项目和技术文档在这里：https://gitee.com/wufan870312/oraclemind

下一篇，我们直接用 LangGraph 把一个能调工具的 Agent 跑起来。