1. 从零开始AI、大模型、LLM 和 Agent 到底谁是谁如果你刚开始接触智能体开发大概率已经被一串名词绕晕过人工智能、机器学习、深度学习、生成式 AI、大模型、LLM、聊天机器人、Agent、Agentic System。它们经常出现在同一篇技术文章、同一个产品发布会里让人产生一种错觉——这些词说的好像都是“那个会聊天、会写代码的东西”。这个模糊印象在入门阶段问题不大但一旦你准备动手写 Agent Harness 工程它就会变成绊脚石。后面你会遇到一连串想不通的问题既然模型已经这么聪明了为什么还要写循环既然模型能生成命令为什么还要自己实现 Bash handler既然模型学过那么多知识为什么还要读取当前目录这些问题的根源不是代码细节而是对象边界没分清。先建立一张适合入门的坐标图。AI 是最大的目标领域只要系统表现出某种通常需要人类智能的能力比如识别图像、理解语言、规划路线、做预测都可以归到 AI 里。机器学习是一类让系统从数据中学习规律的方法而不是把每条规则手工写死。深度学习是机器学习里使用多层神经网络的那条路线。生成式 AI 换了个观察维度描述的是“能生成新内容”的能力类别。LLM 则是面向语言序列训练的大规模模型接收上下文预测并生成后续内容。而 Agent是围绕目标、状态、行动和反馈组织起来的系统。它和 LLM 不是同一个层面的东西。LLM 是 Agent 系统里的一个组成部分负责语义判断和内容生成Agent 还需要运行环境、工具接口、执行器、权限边界这些外部设施。这个外部运行环境就是本系列反复要讲的 Harness。我建议你记住三个判断问题比背二十个定义有用得多。看到一个新术语时先问它描述的是模型本身、训练方法还是完整应用它产生的是内容还是会对外部环境产生真实动作下一步由预先写好的代码决定还是由模型根据新状态动态决定第一问把 LLM 和 Agent 分开第二问把“生成命令”和“执行命令”分开第三问帮你区分 Workflow 和 Agent。还有一个容易混淆的点Model 和 Application 不是一回事。你在网页里看到的聊天界面是应用应用内部可能调用一个或多个模型还会加上系统指令、检索、文件上传、内容安全、会话存储和用户权限。用户感觉自己在“和模型聊天”但真正提供体验的是模型和外部软件共同组成的系统。同理Agent 也不是模型的另一个名字模型提供理解和决策能力Agent 系统还需要运行环境让模型能接触状态、提出动作、获得结果并继续工作。把这些概念放回各自的位置之后你才能理解为什么本系列不从框架 API 开始而是从最小 Harness 逐层搭建。因为只有先看清模型能做什么、不能做什么你才知道 Harness 到底要补上哪些能力。这也是后面所有工程实践的地基。2. 大模型能生成什么为什么还不能独立完成任务暂时放下所有 Agent 术语只看一次最普通的大模型调用。你把问题、历史消息或资料作为上下文交给模型模型根据这些输入生成下一段输出然后这次调用结束。输出可以是一段解释也可以是一段 Python 代码、一个 JSON 对象甚至是“建议调用某个工具”的结构化意图。形式不同但基本边界没有变化当前上下文进入模型模型进行计算文本或结构化意图返回给调用方。假设你问模型“请帮我找出当前项目里所有超过 500 行的 Python 文件并说明它们各自负责什么。”模型很擅长理解这个目标它知道可以先枚举 .py 文件、统计行数、挑出目标文件再阅读内容并总结职责。它甚至可能给出一条可用命令Get-ChildItem -Recurse -Filter *.py | Where-Object { (Get-Content $_.FullName).Count -gt 500 }但这条命令出现在回复里时真实任务仍未完成。模型没有因为输出了 Get-ChildItem 就自动进入你的电脑也没有看到命令运行后的文件列表。它生成的是符号不是副作用。这里的“副作用”不是贬义词而是工程里的准确说法读取当前目录、写入文件、发送网络请求、修改数据库、创建工单都会让程序接触或改变模型之外的世界。模型输出可以描述这些动作却不等于动作已经发生。如果你复制命令到终端执行再把输出粘贴回聊天窗口任务就能继续。可这时形成闭环的人是你模型建议动作你判断是否允许你执行你复制结果模型根据结果继续回答。这是一条“人肉 Harness”。它非常适合低频、高风险任务因为每一步都有人工检查但如果目标是让程序自主完成大量可控任务就需要把其中可自动化的连接工作交给外部代码。第二个边界是模型训练时学到的知识不等于任务发生此刻的环境状态。模型可能知道 Python 项目的常见结构知道 README.md 往往介绍项目知道 main.py 可能是入口。但你的当前目录里可能根本没有这两个文件也可能入口叫 app.py项目说明放在 docs/index.md。如果模型没有读取当前目录却直接依据常见模式回答它给出的只是合理猜测不是观察结果。“知道一般规律”和“看到当前事实”必须分开。训练知识帮助模型理解什么是 Python 文件、怎样判断职责用户提供的上下文告诉模型本次任务的目标与已知信息工具或环境接口提供此刻真实存在的目录、文件内容和运行结果Harness 负责把这些对象接入同一条执行链。第三个边界是一次调用没有天然的持续任务状态。在普通请求里模型只处理调用方这次提交的上下文。如果第一次调用返回“请先列出目录”外部程序却没有执行也没有把结果加入下一次上下文模型不会凭空知道目录发生了什么。即使应用保存了聊天记录也只是保存文本是否保存结构化动作、是否执行动作、怎样把结果与原动作配对仍由应用负责。这解释了为什么“模型很聪明”不能替代系统工程。模型能力提高后它可以更准确地选择动作、更好地阅读结果、更少走弯路但文件访问权、网络连接、权限审批和状态持久化不会自动从模型参数里长出来。可以用一个简单的责任表来判断对象擅长或负责的内容本身不保证的内容LLM理解目标、生成内容、提出下一步、根据上下文调整判断真实执行命令、访问未提供的实时状态、保证动作获准Tool封装一种外部能力例如读文件、执行 Shell、查询 API决定整个任务下一步、维护完整会话Harness组织消息、暴露工具、执行或拒绝动作、回填结果、控制循环替代模型完成开放式语义判断Environment返回当前文件、进程、网页、数据库等真实状态自动把结果解释成任务结论这张表也给出一个关键认识大模型并不是“缺少一条神奇提示词”才不能独立完成任务。限制来自系统边界。提示词可以告诉模型应当怎样做却不能授予操作系统权限模型可以生成严谨的调用参数却仍需要外部程序解析和执行。后续所有 Tool Calling 和 handler 代码本质上都在为这次受控交接服务。3. 用 TaoToken 统一 Key 打通最小调用链路理解了模型和 Agent 的边界之后下一步就是动手跑通一次真实调用。这一步的意义不在于“学会调 API”而在于让你亲眼看到模型输出和外部执行之间的那道边界。本系列后续所有 Harness 代码都会围绕这条最小链路生长。在开始之前先说明为什么这里选择 TaoToken 作为统一入口。对于零基础读者来说最麻烦的往往不是写代码而是同时管理多个模型厂商的 Key、Base URL 和模型 ID。TaoToken 提供统一的 API 通道你只需要一个 Key、一个 Base URL就能调用不同模型省去了反复切换配置的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先拿到你的 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key。建议给 Key 起一个能看出用途的名字比如 “agent-harness-dev”方便后续排查。创建完成后立刻复制保存因为页面刷新后通常不会再完整显示。接下来配置调用环境。我推荐用环境变量的方式管理 Key避免把密钥硬编码进代码。在项目根目录创建一个.env文件TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Python可以安装 openai 官方 SDK因为 TaoToken 的接口与 OpenAI 兼容pip install openai python-dotenv然后写一个最小的调用脚本first_call.pyimport os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) response client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释什么是 Agent Harness。}, ], ) print(response.choices[0].message.content)这里三个关键配置必须对齐Base URL 填https://taotoken.net/apiAPI Key 填你刚创建的那串Model ID 填你要调用的模型名称。三者缺一不可任何一个写错都会导致请求失败。如果你更习惯用配置文件的方式也可以创建一个config.toml[taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet-4-20250514 timeout 60然后在代码里读取这个配置。这样做的好处是后续你要切换模型时只需要改一处配置不用翻遍整个项目。对于使用 Claude Code 的读者配置方式略有不同。你需要在 settings 文件里指定 Base URL 和 Key。具体路径和字段名请以接入文档为准核心是三件套Base URL 指向 TaoToken 的 API 地址Key 用你创建的那串Model ID 填你要用的模型。配置完成后Claude Code 的请求就会走 TaoToken 通道。如果你用的是 Cline 或类似的编辑器插件配置逻辑是一样的。在插件的 API 设置里把 Provider 选成 OpenAI CompatibleBase URL 填https://taotoken.net/apiAPI Key 填你的 KeyModel ID 填模型名称。保存后就能在编辑器里直接调用。这一步做完你已经有了一条可用的调用链路。但请注意这还只是“模型调用”不是 Agent。模型返回的仍然只是文本它没有读取你的文件没有执行任何命令。下一节我们会验证这条链路是否真的通了然后再讨论怎样把它扩展成带反馈的循环。4. 验证请求看到成功结果才算跑通配置写完之后不要急着往下走先确认这条链路真的通了。很多初学者在这一步跳过验证结果后面遇到问题时分不清是配置错了还是代码逻辑错了。运行刚才的脚本python first_call.py如果一切正常你会在终端看到模型返回的一句话解释。这说明 Base URL、API Key、Model ID 三件套都对齐了请求成功到达模型并返回了结果。如果想让验证更充分一点可以写一个稍微完整些的测试脚本覆盖多轮对话和结构化输出import os import json from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) # 测试一普通对话 resp1 client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 回复 OK 两个字母即可。}], ) print(测试一返回, resp1.choices[0].message.content) # 测试二结构化输出 resp2 client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[ {role: system, content: 你只输出 JSON不要任何其他文字。}, {role: user, content: 返回一个 JSON包含字段 name 和 versionname 为 harnessversion 为 0.1}, ], ) content resp2.choices[0].message.content print(测试二返回, content) parsed json.loads(content) print(解析成功, parsed[name], parsed[version])这个脚本做了两件事第一验证基本对话能通第二验证模型能返回可解析的 JSON。第二点对后续 Agent 开发特别重要因为 Harness 需要模型输出结构化的动作意图而不是自由文本。如果模型返回的 JSON 能被json.loads成功解析说明你的链路已经具备承载工具调用的基础。实测下来只要三件套配置正确这两个测试通常几秒内就能返回。如果测试二偶尔返回带 markdown 代码块的 JSON可以在系统提示里更强调“只输出纯 JSON”或者在代码里做一层清洗。验证通过后你可以做一个更有意思的观察。把测试二的用户消息改成“请帮我列出当前目录下所有 Python 文件。”你会发现模型可能会返回一段命令或者一段描述但它不会真的去读你的目录。这正是上一节讲的边界模型生成的是符号不是副作用。你可以在终端手动执行它建议的命令然后把结果粘贴回去看看模型能否基于真实结果继续回答。这个过程就是“人肉 Harness”也是你后面要用代码自动化的对象。到这里你已经完成了从概念理解到实际调用的闭环。你知道了 LLM 是什么、Agent 是什么、Harness 补的是什么也亲手跑通了一次真实请求。接下来要做的就是把这个单次调用扩展成能持续获得环境反馈的循环。5. 常见报错排查401、local proxy failed 和 reading choices配置和调用过程中最容易卡住新手的不是概念而是几个反复出现的报错。这一节把最常见的几类整理出来对照排查。第一类是 401 错误通常长这样openai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key, type: invalid_request_error}}这个报错几乎只有一个原因API Key 不对。排查顺序是先确认.env文件里的 Key 没有多余空格或换行再确认代码里读取的环境变量名和.env里写的一致然后确认这个 Key 在控制台里没有被删除或禁用。如果 Key 是从网页复制的注意不要漏掉开头或结尾的字符。还有一种情况是 Key 本身没问题但 Base URL 写错了请求发到了错误的地址也会返回 401。所以三件套要一起检查。第二类是 local proxy failed 或连接超时APIConnectionError: Connection error.这类报错通常和网络环境有关。先确认你的 Base URL 是https://taotoken.net/api没有多写或少写路径。然后确认本机网络能正常访问该地址。如果你在公司内网或使用了某些网络工具可能会影响连接。可以先用 curl 测试一下curl -I https://taotoken.net/api如果 curl 也连不上说明是网络层的问题不是代码问题。如果 curl 能通但 Python 脚本报错检查是否有代理环境变量干扰比如HTTP_PROXY或HTTPS_PROXY被设置了。第三类是 reading choices 相关的错误AttributeError: NoneType object has no attribute choices或者IndexError: list index out of range这类错误说明请求本身可能成功了但返回结构和你预期的不一样。常见原因是模型名称写错了服务端返回了一个错误对象而不是正常的 completion 对象。排查方法是先把原始返回打印出来print(response)看看返回的到底是什么。如果返回里包含 error 字段就按错误信息去查。另一个原因是有些模型不支持某些参数比如你传了temperature但该模型不接受也可能导致返回异常。先把参数精简到最小确认能通之后再逐步加回。第四类是 OAuth 或权限相关的问题如果你用的是 Claude Code 或类似工具可能会遇到OAuth token expired or invalid这类问题通常出现在工具自身的认证层而不是 TaoToken 的 API Key。解决方法是检查工具配置里的认证方式确认你用的是 API Key 模式而不是 OAuth 模式。如果你在 Claude Code 里配置确保 Base URL、Key、Model ID 三件套都填对了不要混用不同来源的凭证。第五类是模型返回空内容response.choices[0].message.content 返回 None 或空字符串这种情况可能是模型触发了内容过滤也可能是 max_tokens 设置得太小。先把 max_tokens 调大再检查提示词里是否有容易触发过滤的内容。如果用的是推理模型还要注意有些模型会把内容放在 reasoning 字段而不是 content 字段里需要根据具体模型调整读取方式。把这几类报错对照排查一遍大部分配置问题都能定位。关键习惯是遇到报错先打印原始返回不要只看异常类型三件套一起检查不要只改一个先用最小请求验证再逐步加复杂度。6. 下一步从单次调用到 Agent Loop走到这里你已经完成了 Agent Harness 工程的第一块地基。你分清了 AI、大模型、LLM 和 Agent 的边界理解了模型能生成什么、不能直接改变什么也用 TaoToken 统一 Key 跑通了一次真实调用。现在回到那个核心问题模型先请求列出目录程序执行后得到真实文件列表这份结果怎样重新进入模型上下文让它继续选择要读的文件这就是下一篇要解决的问题。我们会从 ReAct 的 reasoning、action、observation 关系出发分清方法范式、工具调用协议和运行循环再把抽象反馈链落到具体的 Python 程序里。如果你已经跑通了本文的调用验证建议你接着做一件事把测试二的用户消息改成需要多步才能完成的任务比如“先列出当前目录再挑一个文件总结它的作用”。观察模型在没有工具的情况下会怎么回答然后想象一下如果有一个 Harness 帮它执行动作、回填结果整个流程会变成什么样。这个想象出来的流程就是下一篇要动手实现的东西。需要继续深入的话可以先去 TaoToken 的接入文档看看完整的参数说明和模型列表也可以直接在模型对话页面里试试不同模型的表现。如果你打算长期做编码类 AgentCoding Plan 会更适合你它在调用额度和模型选择上更灵活。API Keys 页面则随时可以管理你的凭证。把这条最小链路跑稳后面的 Harness 工程才有坚实的地基。
