AI Agent从零到一：LLM、Tools、Context、Harness四大组件详解与实战-北京尧图网络

1. 从零理解AI Agent它到底是什么为什么突然这么火1.1 一个真实场景引发的思考去年年底我帮一个做电商的朋友处理售后问题。他每天要面对几百条用户咨询内容无非是“我的货到哪了”“能不能退换”“这个尺码适合我吗”。他试过关键词自动回复但用户换个说法就识别不了试过外包客服成本高不说响应还慢。后来我给他搭了一个简单的AI Agent能自己查订单系统、调物流接口、根据退换货政策判断是否合规然后生成一段人话回复用户。上线第一周自动处理率到了73%。这件事让我意识到AI Agent不是实验室里的概念它已经在解决非常具体的问题了。但与此同时我也看到大量开发者在群里问“Agent和普通的LLM调用有什么区别”“为什么我的Agent总是跑偏”“context爆了怎么办”。这些问题背后其实是对Agent的核心机制理解不够深。这篇内容我想把AI Agent从概念到落地拆开讲一遍。不管你是刚接触LLM应用开发的新手还是已经写过一些demo但总觉得不够“智能”的开发者都能从中找到可以直接用的思路和代码。我会重点讲清楚Agent的四大核心组件——LLM、Tools、Context、Harness——它们各自扮演什么角色怎么配合以及在实际工程中会遇到哪些坑。1.2 Agent和普通LLM调用的本质区别很多人第一次接触Agent会觉得“不就是让模型多轮对话吗”。这个理解不能说错但太浅了。普通的LLM调用本质是一次输入对应一次输出你给模型一段prompt它给你一段completion结束。哪怕你做了多轮对话每一轮也是独立的请求模型本身不会“记住”上一轮做了什么全靠你把历史消息重新塞进去。Agent不一样。Agent的核心是让模型具备自主决策和行动的能力。具体来说它需要做到三件事感知环境知道当前有哪些信息可用比如用户说了什么、系统里有什么数据、上一步操作的结果是什么。做出决策根据当前状态判断下一步该做什么。是直接回答用户还是调用某个工具去查数据还是需要再问用户一个问题。执行动作把决策转化为具体的操作比如调用API、查询数据库、发送消息然后把结果反馈给自己继续下一轮决策。这个“决策-执行-反馈”的循环就是Agent的基本运行逻辑。而支撑这个循环的是四个关键组件LLM负责决策Tools负责执行Context负责记忆Harness负责调度。缺了任何一个Agent都跑不起来。1.3 为什么现在值得学AI Agent有几个信号值得注意。第一主流大模型的function calling能力越来越成熟模型本身就能输出结构化的工具调用请求不需要你再写复杂的解析逻辑。第二开源框架越来越多从LangChain到AutoGPT再到国内的Dify、Coze搭建一个Agent的门槛已经降到了“会写Python就能上手”的程度。第三企业需求真实存在——客服自动化、数据分析助手、代码审查机器人、内容运营工具这些场景都在招Agent开发。但门槛降低不代表做好容易。我见过太多Agent项目demo阶段惊艳上线之后问题百出工具调用参数传错、context超限导致模型失忆、多轮对话后逻辑混乱。这些问题不是框架能帮你解决的需要你对Agent的底层机制有清晰的理解。这也是我写这篇内容的出发点——不堆概念讲清楚每个组件为什么存在、怎么配合、哪里容易出问题。2. 核心组件拆解LLM、Tools、Context、Harness各自扮演什么角色2.1 LLMAgent的大脑但别把它当万能神LLM在Agent里的角色是决策引擎。它接收当前的状态信息用户输入、历史对话、工具返回结果输出下一步的动作指令。这个指令通常有两种形式一种是自然语言回复直接给用户另一种是结构化的工具调用请求告诉系统“我要调用哪个工具参数是什么”。选LLM的时候很多人只看“哪个模型最强”。但实际工程中你需要考虑的是性价比和稳定性。我自己的经验是复杂推理任务比如多步数据分析、逻辑判断用能力强的模型比如GPT-4级别或Claude 3.5 Sonnet。这类任务对模型的指令遵循和推理能力要求高便宜模型容易跑偏。简单工具调用比如查天气、查订单用轻量模型就够了比如GPT-3.5 Turbo或国内的通义千问Turbo。成本能降一个数量级响应速度也快。需要长上下文的任务注意模型的context window限制。比如有些模型标称128K tokens但实际有效利用的可能只有一半。如果你的Agent需要处理长文档要么选context更大的模型要么做上下文压缩。还有一个容易被忽略的点模型的function calling能力差异很大。有些模型虽然通用能力强但输出工具调用请求时格式不稳定经常多一个括号少一个引号导致解析失败。选模型之前一定要用你的实际工具定义做一轮测试看模型能不能稳定输出合法的调用格式。2.2 ToolsAgent的手脚设计好坏决定成败Tools是Agent与外部世界交互的接口。没有Tools的Agent本质上只是一个聊天机器人有了Tools它才能查数据、发消息、操作文件、调用API。设计Tools的时候有几个原则我踩过坑之后觉得必须遵守第一工具粒度要适中。太粗的工具比如一个“处理用户请求”的工具模型不知道怎么用太细的工具比如“查询订单表第3列”模型要调十几次才能完成一个任务。比较好的粒度是一个工具对应一个明确的业务动作比如“根据订单号查询物流状态”“根据用户ID查询历史订单”“提交退换货申请”。第二工具描述要写清楚。模型是根据你的工具描述来决定调不调的。描述里要包含这个工具做什么、什么时候用、参数是什么格式、返回什么结果。我见过有人写“查询数据”四个字就完事了模型根本不知道查什么数据、怎么查。第三参数设计要简单。尽量用基本类型字符串、数字、布尔值避免嵌套对象。如果确实需要复杂参数考虑拆成多个工具或者让模型分步调用。第四错误处理要完善。工具调用失败是常态——网络超时、参数错误、权限不足。你的工具要返回清晰的错误信息让模型知道发生了什么才能决定下一步怎么做。比如返回“订单号格式错误应为12位数字”模型就能自动修正参数重试。2.3 ContextAgent的记忆也是最容易爆的地方Context是Agent运行过程中积累的所有信息系统提示词、历史对话、工具调用记录、工具返回结果、中间思考过程。这些信息在每一轮决策时都要塞给LLM所以context的管理直接决定了Agent能不能跑得久、跑得稳。我见过最常见的错误是无限制地往context里塞东西。每轮对话都把完整历史加进去每个工具返回的原始JSON都保留结果跑了几轮之后context就爆了。报错信息通常是“maximum context length exceeded”或者“context is too large and auto-compaction could not recover”。解决这个问题有几个实用策略滑动窗口只保留最近N轮对话更早的对话做摘要或者直接丢弃。N的取值取决于你的任务复杂度一般5-10轮够用。工具结果压缩工具返回的原始数据往往很大但模型只需要关键字段。在把结果塞回context之前先做一层提取和格式化。比如物流接口返回了50个字段你只保留“当前状态”“预计到达时间”“最新位置”三个。分层记忆把信息分成短期记忆当前对话和长期记忆用户偏好、历史摘要。长期记忆存到外部数据库需要的时候再检索出来塞进context而不是一直放在里面。主动摘要当context接近上限时让模型对之前的对话做一次摘要用摘要替换原始对话。这个操作要谨慎因为摘要会丢失细节可能导致Agent忘记关键信息。2.4 HarnessAgent的骨架最容易被忽视但最重要Harness这个词在国内讨论得不多但它是Agent工程化的核心。简单说Harness是把LLM、Tools、Context串起来的调度层。它负责接收用户输入组装context调用LLM获取决策解析LLM的输出判断是直接回复还是工具调用执行工具调用获取结果把结果塞回context进入下一轮循环处理异常情况LLM输出格式错误、工具调用失败、context超限、循环次数过多你可以把Harness理解成Agent的“操作系统”。LLM是CPUTools是外设Context是内存Harness是内核。内核写得好整个系统就稳定内核写得烂再强的CPU也跑不出好结果。我自己的Harness实现里有几个关键设计最大循环次数限制防止Agent陷入死循环。一般设5-10次超过就强制返回当前结果并提示用户。输出解析容错LLM输出的工具调用请求可能格式不对要有重试机制。比如第一次解析失败把错误信息塞回去让模型重新输出。超时控制每个工具调用设超时避免某个工具卡死导致整个Agent挂起。日志记录每一轮的输入、输出、工具调用、耗时都记下来方便排查问题。3. 动手搭建从零实现一个可用的AI Agent3.1 环境准备和技术选型在开始写代码之前先确定技术栈。我的建议是编程语言Python。生态最成熟LangChain、LlamaIndex、OpenAI SDK都有Python版本社区资源也最多。如果你对性能有极致要求可以考虑Rust但目前Agent开发的主流还是Python。LLM接入OpenAI API兼容的接口最通用。国内可以用DeepSeek、通义千问、智谱GLM都提供了兼容OpenAI格式的API。这样你的代码不用改换个base_url和api_key就能切换模型。框架新手建议先用原生Python写一遍理解Agent的运行机制。之后再上LangChain或Dify能少踩很多坑。直接上框架的话出了问题你都不知道是框架的bug还是自己的逻辑问题。工具调用先用本地函数模拟比如写几个Python函数返回假数据。等逻辑跑通了再接入真实的API。环境配置很简单pip install openai python-dotenv requests然后创建一个.env文件存API keyOPENAI_API_KEYyour_api_key_here OPENAI_BASE_URLhttps://api.openai.com/v1如果你用国内模型把OPENAI_BASE_URL换成对应的地址就行。3.2 定义工具从最简单的开始我们先定义两个工具一个查天气一个查时间。虽然简单但能完整演示Agent的工具调用流程。import json from datetime import datetime def get_weather(city: str) - str: 查询指定城市的天气情况。 Args: city: 城市名称比如北京、上海 Returns: 天气描述字符串 # 实际项目中这里会调用天气API这里用假数据演示 weather_data { 北京: 晴气温25°C湿度40%, 上海: 多云气温28°C湿度65%, 深圳: 阵雨气温30°C湿度80% } return weather_data.get(city, f暂时查不到{city}的天气数据) def get_current_time() - str: 获取当前日期和时间。 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) # 工具注册表告诉Agent有哪些工具可用 TOOLS [ { type: function, function: { name: get_weather, description: 查询指定城市的天气情况。当用户询问天气时使用此工具。, parameters: { type: object, properties: { city: { type: string, description: 城市名称比如北京、上海、深圳 } }, required: [city] } } }, { type: function, function: { name: get_current_time, description: 获取当前日期和时间。当用户询问时间或日期时使用此工具。, parameters: { type: object, properties: {}, required: [] } } } ] # 工具名到函数的映射 TOOL_FUNCTIONS { get_weather: get_weather, get_current_time: get_current_time }这里有几个细节值得注意。工具描述里我写了“当用户询问天气时使用此工具”这是给模型看的提示帮助它判断什么时候该调用。参数定义里required字段明确哪些参数必填模型会据此生成调用请求。3.3 实现HarnessAgent的核心调度逻辑接下来是Harness的实现。这是整个Agent最核心的部分我把它拆成几个关键步骤。import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL) ) SYSTEM_PROMPT 你是一个智能助手可以调用工具来帮助用户解决问题。规则 1. 如果用户的问题需要实时数据天气、时间等调用对应的工具。 2. 如果不需要工具就能回答直接回复用户。 3. 调用工具后根据工具返回的结果组织自然语言回复。 4. 如果工具返回错误向用户说明情况不要编造数据。 def run_agent(user_input: str, max_turns: int 5) - str: 运行Agent处理用户输入并返回最终回复。 Args: user_input: 用户输入的问题 max_turns: 最大循环次数防止死循环 Returns: Agent的最终回复 # 初始化context messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for turn in range(max_turns): print(f\n--- 第 {turn 1} 轮 ---) # 调用LLM获取决策 try: response client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, toolsTOOLS, tool_choiceauto ) except Exception as e: return f调用模型失败{str(e)} assistant_message response.choices[0].message # 情况一模型直接回复没有工具调用 if not assistant_message.tool_calls: return assistant_message.content # 情况二模型请求调用工具 # 先把模型的回复加入context messages.append(assistant_message) # 依次执行每个工具调用 for tool_call in assistant_message.tool_calls: tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) print(f调用工具{tool_name}参数{tool_args}) # 执行工具 if tool_name in TOOL_FUNCTIONS: try: result TOOL_FUNCTIONS[tool_name](**tool_args) except Exception as e: result f工具执行失败{str(e)} else: result f未知工具{tool_name} print(f工具返回{result}) # 把工具结果加入context messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result) }) # 超过最大轮次强制返回 return 抱歉处理这个问题需要的步骤太多了请换个方式提问。这段代码虽然不长但包含了Harness的所有关键逻辑context组装、LLM调用、工具调用解析、结果回填、循环控制、异常处理。3.4 跑起来看看效果写个简单的测试if __name__ __main__: # 测试1需要调用工具 print(用户北京今天天气怎么样) print(Agent, run_agent(北京今天天气怎么样)) print(\n *50 \n) # 测试2不需要工具 print(用户你好请介绍一下你自己。) print(Agent, run_agent(你好请介绍一下你自己。)) print(\n *50 \n) # 测试3需要多个工具 print(用户现在几点了另外上海天气如何) print(Agent, run_agent(现在几点了另外上海天气如何))跑出来的效果大概是这样的第一轮模型判断需要调用get_weather参数是{city: 北京}。Harness执行工具拿到“晴气温25°C湿度40%”塞回context。第二轮模型根据工具结果生成回复“北京今天晴天气温25°C湿度40%适合外出。”第三个测试比较有意思模型会在一轮里同时请求调用两个工具。Harness依次执行把两个结果都塞回去模型再综合生成回复。这就是Agent比普通LLM调用强的地方——它能自主编排多个动作来完成一个复杂请求。3.5 加入Context管理让Agent跑得更久上面的实现有个问题如果对话轮次多了context会越来越大。我们加一个简单的滑动窗口机制。def trim_context(messages: list, max_messages: int 20) - list: 裁剪context保留system prompt和最近的消息。 Args: messages: 完整的消息列表 max_messages: 最大保留消息数 Returns: 裁剪后的消息列表 if len(messages) max_messages: return messages # 保留system prompt system_msg messages[0] # 保留最近的消息 recent_msgs messages[-(max_messages - 1):] return [system_msg] recent_msgs然后在每轮循环开始前调用messages trim_context(messages)这个简单的策略能解决大部分context超限的问题。但要注意裁剪可能会丢掉关键的工具调用记录导致模型不知道之前做了什么。更稳妥的做法是保留最近N轮完整的对话包括工具调用只裁剪更早的部分。4. 进阶实战常见问题与排查技巧4.1 模型不调用工具怎么办这是最常见的问题。用户问“北京天气怎么样”模型直接编了一个“北京今天晴天25度”根本没调工具。原因通常有几个工具描述不够清晰。模型不知道这个工具是干什么的自然就不会调。解决方法是把描述写得更具体包含使用场景。比如把“查询天气”改成“查询指定城市的实时天气情况。当用户询问天气、气温、是否下雨等问题时使用此工具”。系统提示词没有强调工具的使用。在system prompt里明确告诉模型“对于需要实时数据的问题必须调用工具不要自己编造。”我试过加了这句话之后工具调用率明显提升。模型本身能力不足。有些轻量模型对function calling的支持不好经常忽略工具。这种情况要么换模型要么在prompt里给更明确的指令比如“你必须调用get_weather工具来获取天气信息”。工具参数定义有问题。如果参数定义太复杂模型可能不知道怎么填干脆就不调了。尽量简化参数必填项要明确。4.2 工具调用参数传错怎么排查模型生成的参数可能不符合预期。比如用户说“查一下北京的天气”模型可能生成{city: 北京市}而你的工具只认“北京”。这种问题很难完全避免但可以通过几个手段降低概率参数描述里给示例在description里写“城市名称比如北京、上海、深圳”模型会倾向于用你给的示例格式。工具内部做容错比如get_weather里对城市名做归一化处理“北京市”和“北京”都映射到同一个key。返回清晰的错误信息如果参数不对工具返回“未找到城市‘北京市’的天气数据请使用标准城市名如北京”模型看到之后会自动修正重试。我踩过最坑的一次是模型把日期格式传成了“2024年1月1日”而我的工具期望“2024-01-01”。后来在参数描述里明确写了“日期格式为YYYY-MM-DD”问题就解决了。4.3 Context超限的应急处理报错信息“maximum context length is 1048576 tokens”或者“context is too large and auto-compaction could not recover”说明context已经爆了。应急处理方案立即裁剪。保留system prompt和最近3-5轮对话其余全部丢弃。这能快速恢复运行但可能丢失关键信息。压缩工具结果。检查工具返回的数据是不是太大了。比如某个API返回了完整的JSON但你只需要其中几个字段。在工具函数里就做好提取只返回必要信息。启用摘要。如果对话历史很重要不能丢让模型对之前的对话做摘要用摘要替换原始消息。摘要的prompt可以是“请用200字总结以下对话的关键信息包括用户的需求、已执行的操作、得到的结果。”换更大context的模型。如果业务场景确实需要长上下文考虑换用context window更大的模型。但要注意context越大推理成本越高响应也越慢。4.4 Agent陷入死循环怎么破有时候Agent会反复调用同一个工具或者在两个工具之间来回跳。比如查天气失败它重试又失败再重试。这种情况需要Harness层面做限制最大轮次限制设一个硬上限比如10轮超过就强制返回。重复调用检测记录最近几次的工具调用如果发现连续调用同一个工具且参数相同就中断并返回错误。失败次数限制同一个工具连续失败3次就不再重试直接告诉用户“暂时无法获取数据”。我在Harness里加了一个简单的检测逻辑def detect_loop(tool_calls_history: list, threshold: int 3) - bool: 检测是否陷入循环调用。 if len(tool_calls_history) threshold: return False recent tool_calls_history[-threshold:] # 如果最近threshold次调用的工具名和参数都相同判定为循环 first recent[0] return all( call[name] first[name] and call[args] first[args] for call in recent )4.5 常见问题速查表问题现象可能原因排查方向解决方案模型不调用工具工具描述不清、prompt未强调检查工具description和system prompt补充使用场景说明强调必须调用工具参数格式错误参数描述不明确查看模型生成的arguments在description里给示例工具内做容错context超限历史消息过多、工具结果太大打印context长度滑动窗口、结果压缩、摘要Agent死循环工具反复失败、逻辑判断错误查看工具调用历史最大轮次限制、重复检测模型输出格式错误模型能力不足、prompt不清晰查看原始输出换模型、加格式示例、重试机制工具调用超时外部API响应慢检查工具执行耗时设超时、异步调用、降级处理5. 工程化建议从demo到上线的关键考量5.1 日志和可观测性Demo阶段你可以靠print调试但上线之后必须有完整的日志。我建议记录以下信息每次请求的完整context脱敏后LLM的原始输出工具调用的名称、参数、返回值、耗时每一轮的决策结果最终回复和总耗时这些日志不仅能帮你排查问题还能用来分析Agent的行为模式。比如你发现某个工具调用率特别低可能是描述有问题某个环节耗时特别长可能是外部API需要优化。5.2 成本控制Agent的成本主要来自LLM调用。每一轮循环都是一次API请求如果Agent跑了5轮成本就是普通对话的5倍。控制成本的手段简单任务用轻量模型不是所有任务都需要GPT-4。查天气、查时间这种用最便宜的模型就够了。减少不必要的循环优化prompt让模型尽量一次决策到位减少来回。缓存工具结果如果某个工具的结果在短时间内不会变比如用户信息可以缓存起来避免重复调用。设置token上限在API调用时设max_tokens防止模型输出过长。5.3 安全边界Agent能调用工具就意味着它能执行真实操作。如果工具包括“发送消息”“删除数据”“提交订单”那必须加安全限制敏感操作二次确认Agent判断需要执行敏感操作时先返回给用户确认用户同意后再执行。权限控制不同用户能调用的工具不同。比如普通用户只能查数据管理员才能改数据。操作审计所有工具调用都记录日志方便追溯。输入过滤防止prompt注入攻击。用户可能通过精心构造的输入诱导Agent执行非预期操作。5.4 持续迭代Agent上线不是终点。你需要持续收集bad case分析哪些场景处理不好然后针对性优化。优化的方向包括补充工具、改进工具描述、调整system prompt、增加few-shot示例、换更合适的模型。我自己的习惯是每周review一次日志把失败的case整理出来分类归因。坚持一个月Agent的成功率能从60%提到85%以上。6. 学习路线和资源推荐6.1 新手入门路径如果你刚接触AI Agent建议按这个顺序来第一周理解概念。搞清楚LLM、Tools、Context、Harness分别是什么Agent的基本运行流程。不用写代码多看几篇入门文章和视频。第二周跑通demo。用OpenAI API或国内模型的API照着本文的代码写一遍。先跑通最简单的工具调用再逐步加功能。第三周接入真实工具。把假数据换成真实API比如天气API、数据库查询、文件操作。体验真实场景下的问题。第四周优化和扩展。加入context管理、错误处理、日志记录。尝试用LangChain或Dify重构对比原生实现的差异。6.2 进阶方向跑通基础Agent之后可以往这几个方向深入多Agent协作多个Agent分工合作比如一个负责理解需求一个负责执行一个负责审核。RAG与Agent结合用检索增强生成给Agent提供知识库支持让它能回答领域问题。Agent评估建立测试集量化Agent的成功率、耗时、成本用数据驱动优化。Harness工程化把Harness做成可配置、可扩展的框架支持不同模型、不同工具、不同策略的热插拔。6.3 我踩过的坑和给你的建议最后分享几个我个人踩过的坑希望能帮你少走弯路不要一开始就追求完美架构。我见过有人花两周设计“可扩展的Agent框架”结果连一个能跑的工具调用都没写出来。先用最笨的方式跑通再重构。工具描述比模型选择更重要。同样的模型工具描述写得好调用准确率能差30%以上。花时间打磨工具描述比换模型划算。Context管理要提前做。不要等到报错了才想起来裁剪。一开始就设计好context的组装和裁剪策略后面会省很多事。测试要覆盖异常场景。正常流程谁都能跑通真正体现水平的是异常处理工具超时怎么办、参数错误怎么办、模型输出格式不对怎么办。这些场景测试到位了上线才稳。保持简单。Agent很容易越做越复杂工具越加越多prompt越写越长。定期回顾砍掉不必要的工具和逻辑保持核心流程清晰。简单的东西才可靠。

AI Agent从零到一：LLM、Tools、Context、Harness四大组件详解与实战

相关推荐

数字孪生技术在智能网联汽车教学中的应用与实现

Android Modbus RTU主站开发实战：串口调试与源码解析

Python实现搜索增强问答API调用：从请求构造到异常处理实战解析

更多资讯

电子遗嘱活体验证V步骤1：Python构建司法级身份证据链

多智能体协同优化：冲突解决与性能提升实践

AI内容创作工具链搭建与商业变现实战

AI Agent入门：先建心智模型，再学框架

YOLOv11与CLIP结合的半自动交通标注框架解析

GPT-4断崖式领先：开发者如何应对AI冲击与技能升级

今日更新

基于YOLOv11的石油泄漏智能检测系统开发实践

AI行业变局：合规、Mod化与上下文管理的实战启示

计算机视觉与AI原生应用融合的技术实践

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？