大家做 Agent 最常卡住的地方，不是框架选型，不是记忆设计，也不是工具调用链，而是连第一行大模型调用都没跑通。我最近重新整理自己的 Agent 项目，把之前踩过的坑翻出来复盘一遍，发现第一次跑通大模型调用的代码其实 10 行就能搞定，但如果没有经验，这个过程中足够让你踩出四五个跟头。
这篇文章就围绕“10 行代码跑通大模型调用”这条主线写，把环境准备、代码拆解、四个典型坑、以及从一次调用走向 Agent 的扩展思路全部串起来。已经跑过 API 的老手可以直接跳到第二部分看踩坑记录，刚上手的朋友建议从头读完，每一步我给的都是可直接复制运行的方案。
1. 内容整体设计与思路拆解
1.1 为什么从“调大模型”开始才是 Agent 的正确起跑线
很多人一上来就翻 Agent 框架的文档，什么规划、记忆、工具调用、多智能体协作看了一堆，结果自己动手写的时候，连“把一句话发给大模型再拿回结果”这一步都做得磕磕绊绊。其实 Agent 的上层玩法再花哨，底层都离不开一个最基础的能力：稳定、可控地调用大模型。就像盖楼先打地基，调用大模型就是 Agent 的地基。
我从零手撸 Agent 的第一步，就是先让一个真实的模型调用跑起来。这听起来简单，实际操作中却涉及到 API 密钥管理、请求参数设置、超时处理、返回结构解析、异常捕获等多个环节。标题里说的“10 行代码”，指的是核心逻辑控制在 10 行以内，但为了让它稳定跑通，前后需要补的环境准备和防护代码，才是真正决定成败的部分。
这里也给正准备入坑的朋友一个明确的建议：初期不要去折腾那些复杂的 Agent 框架，直接用大模型厂商提供的官方 SDK，自己写一个最简调用，感受一下“发请求、收响应、解析结果”这个最基本的闭环。这一步跑顺了，后面所有 Agent 的复杂功能才有附着点。
1.2 这 10 行代码解决的核心问题是什么
先说结论：这段代码解决的就是一个最基础的问题——把用户输入发送给大模型，拿到模型返回的文本结果。
听起来平平无奇，但这是后续一切 Agent 能力的底座。比如你想给 Agent 加“记忆”，本质是把历史消息一起拼到请求里再发送；你想给 Agent 加“工具调用”，本质是在请求里声明可用工具，然后解析模型返回的工具调用指令；你想给 Agent 加“多步推理”，本质是循环执行“发请求-拿结果-再发请求”这个动作。所以别看 10 行代码简单，它背后是 Agent 逻辑闭环的最小原型。
1.3 技术选型：为什么用官方 SDK 而不是 HTTP 直连
第一次做模型调用，很多人纠结用 requests 直接发 HTTP 请求，还是用官方 SDK。我的建议非常明确：用官方 SDK。原因有四个：
- 官方 SDK 封装好了鉴权、签名、请求重试这些繁琐细节，减少初期的出错面。
- SDK 内部对返回结构做了处理，拿结果比手动解析 JSON 更省事。
- 官方 SDK 会跟随模型版本升级同步更新字段，不容易出现“接口格式变了但代码没改”的问题。
- 社区和官方文档的示例代码基本都是基于 SDK 写的，遇到问题更容易搜到答案。
当然，如果你用的模型比较冷门，或者有特殊的网络环境限制，可能需要退回到 HTTP 直连。但那是少数情况，不在本文的讨论范围内。我这里用最常见的 OpenAI SDK 格式作为示例，其实国内很多大模型的 SDK 都是与之兼容的，代码几乎可以无缝切换。
2. 核心细节解析与实操要点
2.1 环境准备：把路铺平再出发
跑代码之前，有几个准备工作必须做。第一个是安装 SDK。我建议用一个独立的虚拟环境，避免跟系统其他项目依赖冲突。创建虚拟环境的命令很简单：
python -m venv agent_env source agent_env/bin/activate # Windows 下是 agent_env\Scripts\activate pip install openai python-dotenv这里同时装了 python-dotenv，是为了管理 API Key。强烈建议不要把密钥直接硬编码在代码里，一方面是有泄露风险，另一方面是后续不方便换 Key。在项目根目录创建一个.env文件，里面写上 API Key：
OPENAI_API_KEY=sk-你的密钥代码里用load_dotenv()加载，然后从环境变量读取。这一步虽然多花了十秒钟，但能帮你避开一个极大的隐患：代码误上传到公开仓库导致密钥泄露。我见过不止一个朋友因为硬编码 Key，最后 Key 被别人盗刷，损失惨重。
2.2 10 行核心代码逐行拆解
直接上代码，我这次用的模型调用格式是当前主流的 Chat Completions 风格，兼容 OpenAI SDK 的大模型厂商都可以用：
from openai import OpenAI from dotenv import load_dotenv import os load_dotenv() client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) response = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "你好，请用一句话介绍你自己"}], timeout=30 ) print(response.choices[0].message.content)八行代码，加上一个空行，满打满算 10 行。逐个拆解一下作用：
- 第 1-3 行：导入 SDK 和系统库。OpenAI 是客户端主类，dotenv 负责加载环境变量文件，os 用于读取环境变量。
- 第 5 行：加载
.env文件，把里面的 API Key 注入到环境变量，这行必不可少，少了她你会得到一个 None。 - 第 6 行：创建客户端实例。传入 API Key，这个 client 后面所有请求都复用，不需要每次重复创建。
- 第 8-12 行：核心请求。指定模型名，传入消息列表，设置超时时间。这个
messages参数是后续做 Agent 的抓手，它支持多轮对话和系统提示词。 - 第 13 行：从返回结构中提取文本内容。response 是一个复杂的嵌套对象，
choices[0]是第一个候选结果，.message.content才是模型回答的文本。
2.3 返回结构到底长什么样
第一次调用大模型，很多人会print整个response看看里面有什么，这完全正确，但你要做好心理准备——返回结构比你想象中复杂得多。以 Chat Completions 为例，核心结构大致是这样的：
{ "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1234567890, "model": "gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "你好！我是一个人工智能助手..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 13, "completion_tokens": 12, "total_tokens": 25 } }初次接触可能会被这个嵌套结构吓到，其实只需要关心三个地方：choices[0].message.content（模型回答的正文）、choices[0].finish_reason（结束原因，是正常结束还是因为长度截断）、usage（本次请求消耗的 token 数，做成本统计用）。这三个字段是后续 Agent 开发天天要打交道的核心字段，建议直接把这一小段 JSON 存成笔记，后面写代码时经常翻。
2.4 第一次运行前必做的两个小验证
代码写完之后，别急着直接跑正常请求。我建议先做两个小验证，把问题提前暴露出来。
第一个是验证 API Key 能不能用。可以在.env文件所在目录执行一个极简测试脚本，只打印 Key 的前几位：
import os from dotenv import load_dotenv load_dotenv() key = os.getenv("OPENAI_API_KEY") print("Key 前8位:", key[:8] if key else "未找到 Key") print("Key 长度:", len(key) if key else 0)如果这里查不到，那后面不管你代码写成什么样，请求都会报鉴权错误。第二个验证是网络连通性，直接运行一次最简单的请求，看能不能顺利拿到返回。如果网络有问题，报错信息通常会直接给出来，比如连接超时或 DNS 解析失败。
这两步验证加起来不到一分钟，但能把后面四个坑里的两个提前排掉，效率非常高。
3. 实操过程与核心环节实现
3.1 从零开始的完整操作流程
现在把完整流程走一遍，从建目录到看到第一行模型输出，整个过程大概五分钟，前提是 API Key 已经准备好且账户有余额。
第一步，建一个项目目录，专门放这次实践的文件：
mkdir my_first_agent cd my_first_agent第二步，创建虚拟环境并激活：
python -m venv venv source venv/bin/activate # Windows 下用 venv\Scripts\activate第三步，安装依赖：
pip install openai python-dotenv第四步，创建.env文件，写入 API Key。注意.env文件没有任何后缀名，就是一个小写的点加 env。第五步，在同一目录下创建main.py，把前面那段 10 行代码复制进去。第六步，运行程序：
python main.py如果一切顺利，你会看到终端里打印出一段中文文本，那是模型的自我介绍。如果报错了，大概率就是下面要讲的四个坑之一。
3.2 踩坑实录一：模型名称写错，认证通过了但请求失败
我第一次跑通模型调用的时候，以为自己已经非常小心了，结果第一个坑还是踩了——模型名称写错。
当时我把模型名写成了gpt-4o，实际上账户可用的模型并不是这个精确的字符串。报错信息也不是“检测不到模型”，而是给出了一个模型列表，提示我选择的模型不存在或没有权限。这个问题其实非常好排查，因为报错信息里通常会说明。
这里分享一个实用方法：官方 SDK 一般都有查模型列表的方法，可以精确看到你的账户到底能用哪些模型：
from openai import OpenAI from dotenv import load_dotenv import os load_dotenv() client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) models = client.models.list() for m in models: print(m.id)运行之后把模型列表和自己代码里的模型名对一下，多一个字符、少一个连字符、大小写不对，全都原形毕露。这个坑算不上高深，但它告诉我们一个道理：不要凭记忆写模型名，一定要以官方文档或列表接口返回为准。
3.3 踩坑实录二：超时设置缺失，程序假装死掉
第二个坑是超时问题。我第一次写代码的时候没有加timeout参数，想着让模型慢慢返回也没关系。结果有一次赶上服务波动，请求发出去之后整整一分多钟没有任何响应，程序一直挂在那里，看起来就像死掉了一样。
后来我在所有请求里都显式加上超时参数，并且会依据具体场景选择合适的值：
- 普通聊天/简单生成：建议
timeout=30，默认情况足够。 - 复杂推理/长文生成：可以放宽到
timeout=60或timeout=120。 - 对响应时间要求高的场景：建议
timeout=10，超时后走降级逻辑。
加超时还有一个额外好处：能帮你快速定位网络问题。如果请求总是超过 10 秒才响应，说明链路可能有问题，而不是参数写错了。如果请求秒回超时，那大概率是网络被掐断或者域名解析异常。
3.4 踩坑实录三：上下文过长被拒绝，请求还没到模型就失败了
第三个坑跟请求内容本身有关。有一次我在测试多轮对话，把前面十几轮的历史消息原封不动地拼在messages里发给模型，结果返回了一个上下文长度超限的错误。
大模型对输入长度有硬性上限，不同模型的上限不同，有的 8K token，有的 128K token。超出限制后，请求会直接被拒绝，而不是截断处理。解决思路有两个：一个是控制历史消息的数量，早期做 Agent 最简单的方式是只保留最近 N 轮对话；另一个是用支持更长上下文的模型。
这里给一个实用建议，在早期调通阶段，messages里只放当前这一轮的用户输入就好，等基础调用没问题了再去搞记忆和历史消息管理。先把地基打牢，再盖楼。
3.5 踩坑实录四：返回结果解析错误，把整个对象当文本打印
第四个坑是最“低级”但也最容易忽略的：拿到响应之后，直接print(response)看结果，发现打印出来一大长串看不懂的对象结构，以为自己调用失败了。
其实响应已经成功返回，只是没有取对字段。正确的做法是取response.choices[0].message.content，这才是模型输出的纯文本内容。如果你把整个 response 对象打印出来，看到的是一大堆元数据、usage 信息、嵌套结构，看起来非常唬人，但并不是模型回答本身。
我还见过另一种情况：有人用response["choices"]的方式取值，结果报类型错误。因为 SDK 返回的是对象而不是字典，需要用点号属性访问，而不是方括号键名访问。如果你非要用字典的方式，可以调.model_dump()把对象转成字典再取，但没必要，点号访问更直接。
3.6 关于四个坑的最省心排查序列
把这四个坑串起来，给你一个最省心的排查顺序，以后跑模型调用报错，按这个顺序查基本不会走弯路：
| 错误现象 | 优先排查 | 验证方法 |
|---|---|---|
| 401 鉴权失败 | API Key 是否正确、是否被正确加载 | 打印 Key 前几位和长度 |
| 404 或模型不存在 | 模型名是否正确 | 调用模型列表接口核对 |
| 超时/连接错误 | 网络状态、超时参数是否设置 | ping 供应商域名或换网络测试 |
| 上下文长度错误 | 请求体是否超长 | 统计 token 总量或减少历史消息 |
| 拿到对象不是文本 | 返回字段取值路径是否正确 | 用response.choices[0].message.content做最小提取 |
这个表格是我自己实践中浓缩出来的，对照着排查，大多数问题五分钟之内能定位。
4. 常见问题与排查技巧实录
4.1 不同模型调用的兼容性怎么处理
整个大模型生态目前还处于快速发展期，几乎每个月都有新模型冒出来。不同厂商提供的 SDK 风格不完全一样，但主流的 Chat Completions 格式兼容性做得不错。如果你今天用 A 厂商 SDK 跑通了，明天想换 B 厂商，代码改动量通常很小，主要改base_url和api_key，方法名和参数结构大同小异。
比如很多国内模型的 OpenAI 兼容模式，是这样配置的：
from openai import OpenAI client = OpenAI( api_key="你的密钥", base_url="https://api.某厂商.com/v1" )这行配置值得专门记住，因为不少模型厂商提供了兼容 Chat Completions 的接口，你只要把base_url指过去，代码就能复用。这意味着你之前学到的调用方式，可以平移到很多不同的模型上，不用重学一套 SDK。
4.2 多轮对话的正确实现姿势
从一次调用走向 Agent，最先遇到的扩展需求一定是多轮对话。很多人会把多轮对话理解成“多次调用”，其实不准确。模型本身是无状态的，它不会记得之前的请求。你必须把完整的对话历史在每次请求时都交给它，它才能基于上下文回答。
正确的多轮对话实现方式是维护一个消息数组：
messages = [ {"role": "system", "content": "你是一个乐于助人的助手"}, {"role": "user", "content": "你好"}, {"role": "assistant", "content": "你好！有什么可以帮你的？"}, {"role": "user", "content": "我叫小明"}, ]每次用户说一句话，就往这个数组里追加一条user消息，然后把整个数组发给模型。模型返回的结果再追加一条assistant消息，作为下一轮请求的一部分。
这个数组就是 Agent 的“记忆”雏形。你不需要任何高级框架，先把消息数组维护好，就已经实现了 Agent 的记忆基础能力。
4.3 流式输出为什么值得尽早掌握
第一次跑通模型调用时，用的是非流式请求，就是一次性把完整结果打印出来。这在体验上有一个明显问题：如果模型生成内容较长，你要等好几秒甚至十几秒才能看到第一个字。
流式输出可以解决这个问题。它让模型生成一个 token 就推送一个 token，用户侧的效果就是“打字机式”地看到内容逐渐出现，体验好很多，而且首字延迟大幅降低。
在 Chat Completions 格式下，流式输出的代码改动量非常小，只要加一个参数并把返回遍历方式改一下：
stream = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "写一篇短文"}], stream=True ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="")对于做 Agent 的人来说，流式输出是刚需，因为 Agent 内部可能有多步执行过程，如果每一步都非流式，整个交互过程会显得非常笨重。建议在基础调用跑通之后，第一时间研究流式输出。
4.4 请求异常统一包装的思路
代码跑通之后，接下来要面对的是“健壮性”问题。大模型调用不是一个百分之百稳定的操作，受网络、服务负载、参数合法性影响，随时可能抛异常。好的做法是把调用封装成一个统一的函数，统一处理超时、重试和异常：
def call_model(client, messages, retry=3): for i in range(retry): try: response = client.chat.completions.create( model="gpt-4o-mini", messages=messages, timeout=30 ) return response.choices[0].message.content except Exception as e: print(f"第{i+1}次调用失败: {e}") if i == retry - 1: raise return None这里注意几点：重试之间最好加一点退避延迟，直接加time.sleep(1)就够用；只有网络类异常才值得重试，参数类错误重试多少次都一样失败，所以实际项目中通常还会细分异常类型再决定是否重试。这一层封装是 Agent 项目的第一个基础设施。
4.5 成本控制：从调用量到 token 统计
跑通模型调用后，很快会关心成本问题。每次请求消耗多少 token，通过返回结构里的usage字段就能拿到。但做 Agent 时成本问题更复杂，因为一个 Agent 任务可能包含多个模型调用，比如规划、推理、工具结果分析各调一次。粗浅的统计方式是每次调用都记录 usage，最后加总；精确的统计方式是按任务维度打标签，在日志里记录每次调用的来源。
我个人的习惯是初期把每次调用的total_tokens打出来，做到心里有数。等你发现一个大任务消耗的 token 超过预期时，再回头优化消息历史数量、限制max_tokens、控制工具返回结果的大小，这些都是成本控制的有效手段。
5. 从 10 行代码到 Agent 的扩展路线
5.1 给模型加上“工具调用”能力
大模型调用跑通之后，Agent 的下一步核心能力是工具调用，也就是让模型在回答过程中决定“要不要调用某个函数”。模型本身不会去执行代码，但会在返回结果中声明它想调用哪个工具、传入什么参数，你拿到这些信息后在本地执行，再把执行结果回传给模型，让它基于结果继续回答。
在官方 SDK 里，工具调用的写法和普通调用非常接近，只要在请求参数里声明工具即可。不过这部分代码量会比 10 行多不少，我建议的基础调用流程是：先跑通纯文本问答，再跑通多轮对话，最后才加工具调用。每一步都在前一步的基础上叠加，问题出现时容易定位。
5.2 用什么标准判断“可以开始写 Agent 了”
一个很实际的问题：到什么时候才算具备了开始写 Agent 的能力？我的判断标准很简单，就三条：
- 能用一个函数兼容不同模型，切换
base_url和api_key就能用。 - 能正确处理多轮消息数组，包括追加历史消息和控制长度。
- 能拿到完整的返回结构并解析出所有关键字段，包括正文、结束原因、token 用量。
这三个能力都具备了，那你已经能自己手写一个简单的单轮 Agent，再加上循环判断逻辑，就变成一个多步推理 Agent。别小看这几步能力的积累，它们比任何框架文档都重要。
5.3 回归现实：手撸 Agent 的价值重估
写到这里，想稍微展开说一句关于“从零手撸”这件事本身。现在 Agent 框架非常多，成熟的开源项目，各种低代码平台，都在解决调度和编排的问题。那为什么还要手撸一次底层调用？
我的体会是，框架帮你省掉的是重复劳动，但帮不了你理解问题本质。当你亲手写过一遍请求、调试过返回结构、踩过超时和鉴权的坑之后，再去用任何框架，遇到报错你能大致猜到问题出在哪个环节，而不是两眼一抹黑到处问人。这份对底层的体感，是任何框架都代替不了的。
最后说两句实在的
整个“10 行代码跑通模型调用”的过程，看起来简单，但每一个步骤背后都有值得深挖的细节。我个人在实际操作中最深的一个体会是：第一次跑通时，不要追求代码量少，而要追求把每一步都走扎实——密钥怎么管理、网络怎么排障、返回怎么解析、异常怎么兜底，这四件事做完整，后面所有 Agent 功能的扩展都会非常顺畅。
还有一个每次都会分享的小技巧：把你项目里的.env文件第一时间加入.gitignore，永远不要让密钥有机会进到代码仓库里。这个习惯救了我好几次。
最后再补充一个善意的提醒：大模型调用看似简单，但它连接的是整个 Agent 体系的地基。这篇内容里每个环节都有可延展的空间——比如对话记忆怎么管理、工具结果怎么截断、多步调用怎么控制总成本。后续我会继续更新“从零手撸 Agent”系列，把每个环节单独拆出来分享。第一次跑通的那份兴奋感，值得你亲手体验一次。
