大家做 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 KeyOPENAI_API_KEYsk-你的密钥代码里用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_keyos.getenv(OPENAI_API_KEY)) response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好请用一句话介绍你自己}], timeout30 ) 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_keyos.getenv(OPENAI_API_KEY)) models client.models.list() for m in models: print(m.id)运行之后把模型列表和自己代码里的模型名对一下多一个字符、少一个连字符、大小写不对全都原形毕露。这个坑算不上高深但它告诉我们一个道理不要凭记忆写模型名一定要以官方文档或列表接口返回为准。3.3 踩坑实录二超时设置缺失程序假装死掉第二个坑是超时问题。我第一次写代码的时候没有加timeout参数想着让模型慢慢返回也没关系。结果有一次赶上服务波动请求发出去之后整整一分多钟没有任何响应程序一直挂在那里看起来就像死掉了一样。后来我在所有请求里都显式加上超时参数并且会依据具体场景选择合适的值普通聊天/简单生成建议timeout30默认情况足够。复杂推理/长文生成可以放宽到timeout60或timeout120。对响应时间要求高的场景建议timeout10超时后走降级逻辑。加超时还有一个额外好处能帮你快速定位网络问题。如果请求总是超过 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_urlhttps://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( modelgpt-4o-mini, messages[{role: user, content: 写一篇短文}], streamTrue ) 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, retry3): for i in range(retry): try: response client.chat.completions.create( modelgpt-4o-mini, messagesmessages, timeout30 ) return response.choices[0].message.content except Exception as e: print(f第{i1}次调用失败: {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”系列把每个环节单独拆出来分享。第一次跑通的那份兴奋感值得你亲手体验一次。