AI Agent实战：从零构建Agentic Coding编程助手

先问一个问题当一家做 AI 编程助手的创业公司被传新一轮融资估值可能达到 400 亿美元时这背后真正值得技术人关注的到底是什么我第一时间去看了 Cognition 这家公司的产品逻辑、团队背景和公开技术分享。坦白说估值数字本身离普通开发者很远但这家公司选择的赛道——AI Agent 与 Agentic Coding正切中了过去一年 AI 工程领域最核心的变革。今天不打算写融资新闻解读而是想从这次融资事件切入把 AI Agent 开发这条技术路线完整拆开讲清楚概念、架构、实战代码、部署评测和工程落地时容易踩的坑。无论你是刚接触 AI 应用开发的新手还是已经在做模型部署、AI Agent 落地的工程师这篇文章都值得认真看完。1. 背景与核心概念1.1 Cognition 是谁为什么估值能冲到 400 亿美元Cognition 是一家专注于 AI 编程与自动化智能体的创业公司核心产品是名为 Devin 的 AI 软件工程师。与传统代码补全工具不同Devin 被设计成能够独立理解任务、编写代码、执行命令、调试错误并提交最终成果的自主智能体。据公开报道Cognition 在 2024 年发布了 Devin 的预览版并迅速在开发者社区引发大量讨论。其背后团队来自 Cursor 等知名 AI 编程工具项目技术积累集中在大型语言模型的工程化应用、长上下文任务规划、代码生成与执行环境交互等方向。从技术视角看资本市场愿意给出高估值核心在于两点Agentic Coding 被视为继 Copilot 之后的下一代 AI 编程范式。能够把语言模型、沙箱环境、工具调用、任务编排串成完整产品闭环的团队目前仍然稀缺。这里的“闭环”不仅是指写一个 prompt 调用大模型而是指 AI 系统能够自主完成“理解需求 → 拆解任务 → 执行操作 → 验证结果 → 交付产出”的完整链路。这正是 AI Agent 与普通聊天机器人的本质区别。1.2 从 AI Agent 到 Agentic Coding要理解 Cognition 的产品价值必须先理解 AI Agent 的概念。AI Agent智能体是指以大语言模型为核心通过感知环境、制定计划、调用工具、执行动作来完成复杂任务的系统。它的典型特征包括特征说明对比传统程序自主性能根据目标自行决定执行步骤需要人工预先定义所有分支工具调用能调用外部 API、命令行、数据库、浏览器通常只依赖内部函数环境交互能读取执行结果并动态调整策略固定输入输出任务规划能将大目标分解为多个子任务单一流水线Agentic Coding 则是 AI Agent 在软件开发领域的具体应用。它不再只是“根据光标位置预测下一行代码”而是让 AI 承担起“初级开发者”的角色理解 GitHub Issue、修改代码、运行测试、修复编译错误、提交 Pull Request。这种范式转变带来的技术挑战很明显上下文长度与记忆管理Agent 需要记住长对话中的关键信息而不是简单拼接全文。工具选择的准确性从几十个可用工具中挑出当前最合适的一个需要模型具备很强的指令遵循能力。错误恢复能力执行命令失败后Agent 要能分析日志、定位原因、尝试替代方案。安全性边界赋予 Agent 执行权限后如何防止它执行危险命令或越权操作。1.3 为什么这条技术路线值得每个开发者关注即使你不打算创业AI Agent 与 Agentic Coding 也已经深度影响开发者的日常IDE 插件正向智能体化演进从补全转向自动执行多步任务。企业内部开始用 Agent 自动化处理运维脚本、SQL 生成、数据报表、测试用例编写。模型部署的重心正从“单次推理”转向“多轮工具交互”。以微软、谷歌、阿里云等云厂商的实践来看2025 年后 AI 应用的主流形态将是“模型 工具 业务逻辑”的 Agent 架构而不再是一个孤立的对话接口。掌握 Agent 开发技能等于提前掌握了下一代 AI 应用的核心开发范式。2. 环境准备与版本说明在动手写 Agent 代码之前需要先把开发环境准备好。本文后面的实战示例以 Python 为主版本选择与依赖管理比较关键。2.1 运行环境建议环境项推荐配置说明操作系统Windows 10/11、macOS 12、Ubuntu 20.04三种系统均可运行命令略有差异Python3.10 或 3.113.10 及以上对类型注解和异步支持更友好包管理工具pip 或 poetry建议使用虚拟环境隔离依赖IDEVS Code Python 插件也可以用 PyCharm凭个人习惯大模型 APIOpenAI 兼容接口或本地部署模型本文示例使用兼容接口方便替换需要注意不同版本的 LangChain、Pydantic 等库在 API 上存在差异。实际项目建议先锁定版本再开发避免依赖冲突。2.2 安装基础依赖建议创建独立虚拟环境python -m venv .venv source .venv/bin/activate # Windows 下执行 .venv\Scripts\activate安装本文所需的核心库pip install langchain langchain-openai openai pydantic python-dotenv如果你需要使用本地模型可以安装 Ollama 或 vLLM并把接口转换为 OpenAI 兼容格式。下面是一个 .env 文件示例OPENAI_API_KEYsk-xxxx OPENAI_BASE_URLhttps://api.openai.com/v1这里需要特别说明模型底座的选择直接影响 Agent 的任务拆解能力和工具调用准确性。小参数量模型在做复杂多步 Agent 任务时容易出现在工具选择上“犯迷糊”的情况。生产环境建议优先选用支持 function calling 的模型。3. 核心原理拆解一个 Agent 是怎么工作的要写清楚 Agent 代码必须先理解它的核心运行机制。很多人觉得 Agent 很神秘其实剥开来看本质是一个循环用户输入 → 模型理解并生成决策 → 判断是否调用工具 → 若调用则执行工具并返回结果 → 模型根据结果继续决策 → 直到模型认为任务完成输出最终答案下面按照关键模块逐个讲解。3.1 模型层不只是“聊天”而是“决策”大语言模型在 Agent 中承担的是“大脑”角色。它需要做三件事理解用户的最终目标。根据当前状态决定下一步动作。生成符合工具调用规范的结构化输出。不同模型的能力差异在这里体现得很明显。比如在复杂任务拆解中模型需要准确判断“完成这个目标需要哪几步”并把每一步映射到具体的工具参数。3.2 工具层Agent 的手脚工具是 Agent 与外界交互的桥梁。常见的工具类型包括代码执行器运行 Python、Shell 命令。搜索引擎获取实时信息。数据库查询执行 SQL。文件读写保存和读取中间产物。第三方 API调用 GitHub、Jira、飞书等接口。工具定义时必须包含清晰的名称、描述、参数结构。描述写得越准确模型选择正确工具的概率越高。这是实测中最重要的经验之一。3.3 记忆层长任务的命脉AI Agent 的难点不是“能聊”而是“能在长任务中不迷路”。因此记忆机制分成两种短期记忆当前任务会话中的对话历史、中间状态。长期记忆跨会话保存的用户偏好、历史决策、领域知识。常见的实现方式是把关键信息写回向量数据库或者以 JSON/Markdown 文件的形式保存到磁盘。在 Agentic Coding 场景下长期记忆往往表现为项目知识库文件。3.4 编排层把上面所有部分串起来编排层负责控制循环流程调用模型 → 解析响应 → 执行工具 → 再次调用模型。这一步可以直接用 LangChain 等框架也可以手写循环逻辑。手写循环在简单场景下反而更清晰便于理解 Agent 的本质。核心代码如下def run_agent(user_input, max_steps10): messages [{role: user, content: user_input}] for step in range(max_steps): response call_model(messages) if response.get(tool_calls): messages.append({role: assistant, content: response[content], tool_calls: response[tool_calls]}) for tool_call in response[tool_calls]: result execute_tool(tool_call) messages.append({role: tool, tool_call_id: tool_call[id], content: result}) else: return response[content] return 达到最大步数任务结束。这段代码是 Agent 循环的最小骨架。后面的完整实战会在这个基础上扩展。4. 完整实战案例从零构建一个 AI 编程辅助 Agent这一节将从零实现一个“轻量级 AI 编程辅助 Agent”它能够根据用户描述自动创建项目文件、编写 Python 代码并执行验证。虽然功能上无法与 Devin 相比但把 Agentic Coding 的核心思路完整跑通了。4.1 创建项目结构ai-coding-agent/ ├── .env ├── main.py ├── agent.py ├── tools.py ├── requirements.txt └── workspace/其中 workspace 目录用来存放 Agent 生成的代码文件。这样做可以将 Agent 的操作限制在隔离目录内降低误操作风险。4.2 添加依赖在 requirements.txt 中写入openai1.30.0 python-dotenv1.0.0 pydantic2.0.0执行安装pip install -r requirements.txt4.3 编写工具函数文件路径tools.pyimport os import subprocess from pathlib import Path WORKSPACE Path(__file__).parent / workspace WORKSPACE.mkdir(exist_okTrue) def write_file(file_path: str, content: str) - str: 在 workspace 目录下写入文件。 full_path WORKSPACE / file_path full_path.parent.mkdir(parentsTrue, exist_okTrue) full_path.write_text(content, encodingutf-8) return f文件已写入: {full_path} def run_python(file_path: str) - str: 在 workspace 目录下执行 Python 文件并返回标准输出。 full_path WORKSPACE / file_path if not full_path.exists(): return f文件不存在: {file_path} result subprocess.run( [python, str(full_path)], capture_outputTrue, textTrue, timeout30 ) if result.returncode ! 0: return f执行报错:\n{result.stderr} return f执行结果:\n{result.stdout} def list_files() - str: 查看 workspace 目录下所有文件。 files [str(p.relative_to(WORKSPACE)) for p in WORKSPACE.rglob(*) if p.is_file()] return 文件列表:\n \n.join(files) if files else 目录为空 def read_file(file_path: str) - str: 读取 workspace 目录下的文件内容。 full_path WORKSPACE / file_path if not full_path.exists(): return f文件不存在: {file_path} return full_path.read_text(encodingutf-8)这里有几个设计细节值得注意所有文件操作都被限制在 workspace 目录内防止 Agent 越权读写系统文件。执行外部命令使用 subprocess并设置了 timeout避免命令卡死整个程序。每个工具的返回值都是字符串格式方便大模型理解执行结果。4.4 定义工具 Schema由于 OpenAI 的函数调用需要描述每个工具下面在 agent.py 中定义文件路径agent.pyfrom openai import OpenAI from dotenv import load_dotenv import json import tools load_dotenv() client OpenAI() TOOLS [ { type: function, function: { name: write_file, description: 在 workspace 目录下写入文件如果父目录不存在会自动创建。, parameters: { type: object, properties: { file_path: {type: string, description: 相对路径如 src/main.py}, content: {type: string, description: 文件内容} }, required: [file_path, content] } } }, { type: function, function: { name: run_python, description: 在 workspace 目录下执行一个 Python 文件返回执行结果或报错信息。, parameters: { type: object, properties: { file_path: {type: string, description: 要执行的 Python 文件路径} }, required: [file_path] } } }, { type: function, function: { name: list_files, description: 查看 workspace 目录下所有文件列表。, parameters: {type: object, properties: {}} } }, { type: function, function: { name: read_file, description: 读取 workspace 目录下的文件内容。, parameters: { type: object, properties: { file_path: {type: string, description: 要读取的文件路径} }, required: [file_path] } } } ] TOOL_MAP { write_file: tools.write_file, run_python: tools.run_python, list_files: tools.list_files, read_file: tools.read_file, }这样做的好处是工具的实际实现与模型可见的描述分离后续新增工具时只需在 TOOLS 和 TOOL_MAP 中同步添加。4.5 实现 Agent 主循环继续在 agent.py 中完善SYSTEM_PROMPT 你是一个 AI 编程助手。你的任务是帮助用户编写、运行和调试 Python 代码。 你需要注意 1. 先明确任务目标再拆解步骤。 2. 使用 write_file 创建代码文件使用 run_python 验证代码。 3. 如果运行报错仔细分析错误信息修改代码后重试。 4. 所有文件路径都使用相对路径根目录为 workspace。 5. 全部完成后用简洁的语言总结你做了什么。 def run_agent(user_input: str, max_steps: int 20): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for step in range(max_steps): print(f\n--- Step {step 1} ---) response client.chat.completions.create( modelgpt-4o, # 请根据实际模型调整 messagesmessages, toolsTOOLS, tool_choiceauto ) message response.choices[0].message messages.append(message) if not message.tool_calls: print(AI 最终回复:, message.content) return message.content for tool_call in message.tool_calls: func_name tool_call.function.name try: args json.loads(tool_call.function.arguments) except json.JSONDecodeError: args {} print(f调用工具: {func_name}, 参数: {args}) if func_name in TOOL_MAP: result TOOL_MAP[func_name](**args) else: result f未知工具: {func_name} messages.append({ role: tool, tool_call_id: tool_call.id, content: result }) print(达到最大步数任务提前终止。) return None if __name__ __main__: task input(请输入你想让 AI 编程助手完成的任务: ) run_agent(task)这段代码的核心逻辑可以归纳为系统提示词system prompt约束 Agent 的行为方式。每次循环把最新的消息列表发送给模型。当模型返回 tool_calls 时解析并执行对应工具。工具执行结果以 roletool 的消息返回给模型模型继续决策。模型不再调用工具时输出最终回复循环结束。4.6 运行与验证在终端中输入python agent.py输入测试任务请帮我写一个 Python 脚本计算 1 到 100 的和并打印结果。然后运行它。预期执行过程如下--- Step 1 --- 调用工具: write_file, 参数: {file_path: sum.py, content: print(sum(range(1, 101)))} --- Step 2 --- 调用工具: run_python, 参数: {file_path: sum.py} --- Step 3 --- AI 最终回复: 我已经在 workspace 目录下创建了 sum.py 文件内容为计算 1 到 100 的和并成功运行。输出结果为 5050。到这里一个最小可运行的 Agentic Coding 示例就跑通了。虽然它很简单但已经具备 Agent 的核心四要素模型、工具、记忆对话历史、编排循环。4.7 进阶方向加入错误恢复机制真实项目中Agent 一次执行成功的概率并不高。以运行代码为例首次运行大概率会报错。目前代码的逻辑是把 stderr 发给模型模型自己判断如何修改。这就是“错误恢复”的核心策略不要试图在代码里硬编码处理每种异常而是把异常信息喂给模型让模型像人类开发者一样阅读报错、定位根因、修改代码。为了让效果更好可以在 SYSTEM_PROMPT 中额外强调如果工具执行结果包含 Error 或 Traceback你必须 1. 分析错误类型和出错位置。 2. 推断可能的原因。 3. 修改代码后重新运行。 4. 最多重试 3 次如果仍失败如实告知用户。这个思路与 Cognition Devin 公开演示中的行为一致——Devin 在遇到编译错误时会主动查看日志、搜索文档、尝试不同修复方案直到任务完成或确认无解。5. 常见问题与排查思路在动手实现 Agent 的过程中最容易踩坑的地方往往不是模型 API 调用而是下面这些工程细节。5.1 模型无法正确选择工具问题现象常见原因解决思路模型不调用工具直接给出建议工具描述不够清晰重写工具 description明确使用场景模型调用工具时参数格式错误参数 schema 定义有误检查 required 字段和 type 定义模型反复调用同一个工具上一步结果没被正确传递检查 tool_call_id 与 roletool 是否配对模型选择了不存在的工具tools 列表与实现不一致统一 TOOLS 与 TOOL_MAP要提升工具选择准确率可以尝试在工具描述中加入“当用户提到 XX 时使用此工具”这类指令。控制工具数量无关工具别暴露给模型。使用支持 function calling 且经过指令微调的模型。5.2 API 调用出现兼容性报错OpenAI 官方 SDK 更新较快部分参数在新版本中被标记为弃用。如果出现类似unexpected keyword argument functions的报错通常是因为 SDK 版本过低或参数名写错。建议pip install --upgrade openai并检查代码中是否使用了最新的tools参数。如果使用本地模型如 vLLM、Ollama 部署需要确认服务端是否支持 tools 参数不支持时只能退化为纯文本调用。5.3 Agent 陷入死循环或达到最大步数这在实际项目中非常常见。原因通常是工具执行结果没有发生变化模型反复重试同一操作。模型生成的下一步动作始终非法。任务前提本身无法实现模型却没有及时终止。解决方案设置 max_steps 上限防止无限循环。在系统提示词中强调“如果某个操作执行超过 3 次仍未改变结果请停止并上报”。记录每次工具调用的参数与结果摘要发现重复时主动终止。5.4 执行命令权限过高带来的安全风险给 Agent 开放 Shell 权限是危险操作。Cognition 的 Devin 也只运行在云端沙箱中不允许直接操作宿主机。安全建议始终使用沙箱、Docker 容器或独立虚拟机运行 Agent。限制文件系统访问范围不要给任意路径的读写权限。严禁容器内使用测试环境或生产环境的高权限账号。对 Agent 每次执行的外部命令记录完整日志。当 Agent 需要连接数据库时建议仅授予只读账号或最小权限账号并且连接字符串从环境变量注入不要写死在代码中。6. 最佳实践与工程建议读完上面内容如果准备把 AI Agent 从 demo 推向生产环境下面这些实践经验可以帮你少走很多弯路。6.1 从“单一职责”开始设计工具不要试图做一个“万能函数”。工具职责越单一模型就越容易判断何时调用它。例如把执行 Python 代码拆成运行 Python 脚本和执行 Shell 命令比只提供运行命令要安全得多。前者天然阻止了 Agent 执行rm -rf /这类危险操作至少多一层认知门槛。工具命名也有讲究。名字要动词开头比如search_docs、write_file、query_database。描述要写清楚输入输出的含义必要时给出示例如“file_path 应为相对路径示例: data/input.json”。6.2 系统提示词是 Agent 的“制度”很多 Agent 行为失控根源是系统提示词写得不够细。系统提示词应当包含角色定义你是谁负责什么。任务边界哪些事情绝对不能做。工作流程先做什么再做什么。失败策略遇到错误时怎么办重试多少次。输出要求最终回复的格式和语气。Cognition 在 Devin 产品中花了大量精力做“开发者行为规范”的提示词工程。这提醒我们prompt 不是简单几句话而是 Agent 的行为准则需要反复迭代测试。6.3 日志与可观测性是不可省略的基建Agent 运行是一个多步骤、非线性过程。没有完整日志出问题时基本无法排查。建议至少记录每一步的时间戳。发送给模型的完整消息列表脱敏后。模型返回的决策调用了哪个工具参数是什么。工具执行结果的前 500 字摘要。最终回复内容。日志格式可以每轮一行 JSON便于后续检索和分析。生产环境还可以把日志接入 Tracing 系统观察每一步耗时和 token 消耗。6.4 评测驱动开发用数据集约束 Agent 质量AI Agent 与传统程序最大的不同是你很难预判它在边界条件下的行为。因此必须建立评测集。评测集可以包含常见任务 10-20 条。边界输入 5-10 条。已知失败场景 5 条。每次修改 prompt 或工具定义后运行一遍评测集对比成功率、平均步数、平均 token 消耗。只有把 Agent 的行为量化才能持续优化。下面是一个简单的评测脚本骨架test_cases [ {input: 写一个快速排序算法并运行测试, expect: 包含 sorted}, {input: 读取 workspace/a.py 的内容, expect: 文件内容}, {input: 创建一个 README.md, expect: 文件已写入}, ] for case in test_cases: result run_agent(case[input]) if case[expect] in result or result is not None: print(fPASS: {case[input]}) else: print(fFAIL: {case[input]})6.5 模型选型与成本控制Agent 的 token 消耗远超普通聊天应用。一次 10 步的任务可能消耗数万 token。因此规划阶段可以使用更大参数模型追求推理质量。执行阶段可以切换到更小模型降低每次调用的成本。记忆只保留关键内容不要把全部历史无条件发给模型。成本控制的本质是减少无效的往返次数。工具描述写得越准确模型决策效率越高总 token 消耗自然越低。7. 总结与下一步学习建议Cognition 的估值传闻只是 AI Agent 浪潮的一个注脚。真正值得吸收的信息是AI 编程与 AI 应用开发正从“单轮问答”走向“多步骤自主执行”。这背后的核心能力包括了任务拆解、工具调用、错误恢复、记忆管理和安全隔离每一项都需要从工程层面反复打磨。本文通过一个最小可运行示例演示了 Agentic Coding 的核心循环。你可以在此基础上继续扩展接入更多工具Git 操作、数据库查询、HTTP 请求、测试框架。增加长期记忆把历史决策写入向量数据库。引入多 Agent 协作规划 Agent 与执行 Agent 分离。探索部署方案把 Agent 封装成 API 服务通过任务队列调度。如果本文对你有帮助可以收藏备用。下一步更推荐的做法是选一个日常重复性高的开发任务比如生成单元测试、批量重命名、自动格式化代码用这套流程亲手做一个自己的 Agent。从动手实践中获得的经验远比看十篇概念解析更有价值。