在业务迭代中引入AI大模型尤其是构建能够自主执行任务的智能体Agent已成为提升研发效能的关键路径。然而从概念验证到稳定融入真实研发交付流程团队常常面临“最后一公里”的挑战Agent如何与现有工程体系对接如何确保其行为可控、结果可度量如何管理其长期记忆与知识本文将基于一套经过大厂实战检验的架构方案完整拆解从运行底座搭建、Harness控制、Loop与度量到知识工程集成的全链路闭环。无论你是希望将AI能力引入现有项目的架构师还是探索Agent开发的工程师都能从中获得可直接复用的代码、配置与避坑指南。1. 背景与核心概念为什么需要“工程化”的AI Agent单纯调用大模型的API完成一次对话或文本生成与构建一个能持续、稳定、安全地参与软件研发流程的AI智能体是截然不同的两件事。后者要求我们将AI视为一个新型的、特殊的“软件组件”进行工程化治理。1.1 AI Agent 的本质与挑战一个AI Agent通常由大模型LLM、规划器、工具集、记忆模块等构成它能理解目标规划步骤调用工具如执行代码、查询API并基于结果进行迭代。其核心挑战在于不可预测性大模型的输出具有随机性可能导致任务偏离预期。状态管理复杂Agent在长周期任务中需要维护对话历史、工具调用结果等状态。工具调用安全赋予Agent执行代码、操作数据库等能力时必须建立严格的安全沙箱和权限控制。效果评估困难如何量化一个Agent在复杂任务如代码评审、Bug定位上的表现1.2 工程化落地的核心支柱为了解决上述挑战一个面向生产环境的Agent系统需要四大支柱运行底座提供稳定、可扩展的执行环境管理Agent的生命周期、资源隔离和工具调用。Harness控制像“缰绳”一样对Agent的行为进行约束、引导和监控防止其“脱缰”。Loop与度量设计任务执行循环并建立一套可观测性体系对Agent的决策、工具使用、最终结果进行量化评估。知识工程为Agent注入领域知识如公司代码规范、业务架构图使其决策更精准、更专业。接下来我们将围绕这四大支柱展开实战详解。2. 环境准备与版本说明本文的实战示例将采用Python作为主要开发语言并基于一些主流的开源框架构建。请注意AI领域迭代迅速以下版本是一个稳定的参考组合实际项目中请根据情况调整。操作系统: Ubuntu 20.04 LTS / macOS Monterey 或更高版本 / Windows 11 WSL2Python: 3.9 或 3.10 (推荐3.9兼容性最佳)关键框架与库:langchain-core0.1.0: Agent框架的核心编排库。langchain-openai0.0.5: 用于接入OpenAI系列模型。pydantic2.5.0: 用于数据验证和设置管理。fastapi0.104.1: 用于构建控制API。uvicorn0.24.0: ASGI服务器。大模型服务: 本文示例使用gpt-4-turbo-preview你需要准备相应的API Key。也可替换为其他兼容OpenAI API的模型服务如Azure OpenAI, 通义千问等。开发工具: 任意IDE (VSCode, PyCharm) 以及git。项目结构预览ai_agent_platform/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 应用入口 │ ├── core/ │ │ ├── __init__.py │ │ ├── agent_runner.py # 运行底座核心 │ │ ├── harness.py # 控制与约束逻辑 │ │ └── metrics.py # 度量与评估 │ ├── agents/ │ │ ├── __init__.py │ │ └── code_review_agent.py # 具体Agent实现 │ ├── tools/ │ │ ├── __init__.py │ │ └── code_tools.py # Agent可用的工具集 │ └── knowledge/ │ ├── __init__.py │ └── vector_store.py # 知识库相关 ├── config/ │ └── settings.py # 配置文件 ├── tests/ # 测试目录 ├── requirements.txt # 依赖文件 └── .env.example # 环境变量示例首先创建项目并安装基础依赖# 创建项目目录 mkdir ai_agent_platform cd ai_agent_platform # 创建虚拟环境 (推荐) python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 创建基础文件 mkdir -p app/core app/agents app/tools app/knowledge config tests touch app/main.py app/core/agent_runner.py app/core/harness.py app/core/metrics.py touch app/agents/code_review_agent.py app/tools/code_tools.py touch app/knowledge/vector_store.py config/settings.py requirements.txt .env.example编辑requirements.txt文件langchain-core0.1.0 langchain-openai0.0.5 langchain-community0.0.10 # 包含更多工具和集成 pydantic2.5.0 pydantic-settings2.1.0 fastapi0.104.1 uvicorn[standard]0.24.0 python-dotenv1.0.0 chromadb0.4.22 # 用于向量知识库 tiktoken0.5.2 # 用于Token计数 pytest7.4.4 # 测试框架安装依赖pip install -r requirements.txt3. 核心支柱一构建稳固的Agent运行底座运行底座负责Agent的实例化、调度、工具执行和环境隔离。它是整个系统的“发动机房”。3.1 设计一个基础的Agent Runnerapp/core/agent_runner.py文件将封装LangChain的Agent执行器并添加生命周期管理。# app/core/agent_runner.py import asyncio from typing import Any, Dict, List, Optional, Callable from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.messages import BaseMessage, HumanMessage, AIMessage from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_openai import ChatOpenAI from pydantic import BaseModel, Field import logging logger logging.getLogger(__name__) class AgentRunConfig(BaseModel): Agent单次运行的配置 agent_name: str system_prompt: str tools: List[Any] Field(default_factorylist) model_name: str gpt-4-turbo-preview temperature: float 0.1 # 降低随机性更适合任务执行 max_iterations: int 10 # 防止Agent无限循环 early_stopping_method: str force # 达到最大迭代后强制停止 class BaseAgentRunner: Agent运行底座基类 def __init__(self, config: AgentRunConfig): self.config config self.llm ChatOpenAI( modelconfig.model_name, temperatureconfig.temperature, api_keyself._get_api_key() # 从环境变量获取 ) self.agent_executor: Optional[AgentExecutor] None self._init_agent() def _get_api_key(self) - str: # 实际项目中应从安全的配置中心读取 import os key os.getenv(OPENAI_API_KEY) if not key: raise ValueError(OPENAI_API_KEY environment variable not set.) return key def _init_agent(self): 初始化LangChain Agent执行器 prompt ChatPromptTemplate.from_messages([ (system, self.config.system_prompt), MessagesPlaceholder(variable_namechat_history), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) agent create_openai_tools_agent(self.llm, self.config.tools, prompt) self.agent_executor AgentExecutor( agentagent, toolsself.config.tools, verboseTrue, # 输出详细执行日志生产环境可关闭 max_iterationsself.config.max_iterations, early_stopping_methodself.config.early_stopping_method, handle_parsing_errorsTrue, # 优雅处理输出解析错误 ) logger.info(fAgent {self.config.agent_name} initialized.) async def arun(self, input_text: str, chat_history: Optional[List[BaseMessage]] None) - Dict[str, Any]: 异步运行Agent if not self.agent_executor: raise RuntimeError(Agent executor not initialized.) try: # 准备输入 inputs { input: input_text, chat_history: chat_history or [], } # 调用Agent result await self.agent_executor.ainvoke(inputs) logger.info(fAgent {self.config.agent_name} completed task.) return { output: result.get(output, ), intermediate_steps: result.get(intermediate_steps, []), status: success } except Exception as e: logger.error(fAgent {self.config.agent_name} failed: {e}, exc_infoTrue) return { output: fAgent execution error: {str(e)}, intermediate_steps: [], status: error, error: str(e) } def run_sync(self, input_text: str, chat_history: Optional[List[BaseMessage]] None) - Dict[str, Any]: 同步运行Agent (包装异步方法) return asyncio.run(self.arun(input_text, chat_history))关键设计解析配置化通过AgentRunConfigPydantic模型管理配置保证类型安全且易于测试。错误处理在arun方法中包裹了异常捕获防止单个Agent崩溃导致整个服务不可用。资源控制max_iterations和early_stopping_method是防止Agent陷入死循环的关键参数。异步优先使用async/await支持高并发场景同时提供了同步接口run_sync方便调试。4. 核心支柱二实现Harness控制——给Agent套上“缰绳”Harness控制的核心是在Agent执行的关键节点插入钩子Hooks进行输入检查、过程干预和输出过滤。4.1 定义控制策略在app/core/harness.py中我们实现一个简单的控制层。# app/core/harness.py from typing import Dict, Any, Optional, List from langchain_core.tools import BaseTool from langchain_core.callbacks import BaseCallbackHandler import re import logging logger logging.getLogger(__name__) class SecurityPolicy: 安全策略检查输入和工具调用 staticmethod def validate_input(user_input: str) - tuple[bool, Optional[str]]: 验证用户输入是否安全 # 1. 禁止某些敏感命令模式 dangerous_patterns [ rrm\s-rf, rformat\sc:, rdrop\sdatabase, rsudo, rchmod\s777, rpasswd, ] for pattern in dangerous_patterns: if re.search(pattern, user_input, re.IGNORECASE): return False, fInput contains dangerous pattern: {pattern} # 2. 检查长度限制 (防止提示词注入攻击) if len(user_input) 5000: return False, Input too long, potential prompt injection risk. return True, None staticmethod def validate_tool_call(tool: BaseTool, tool_input: Dict[str, Any]) - tuple[bool, Optional[str]]: 验证工具调用是否被允许 tool_name tool.name # 示例禁止名为“execute_shell”的工具在特定条件下运行 if tool_name execute_shell: command tool_input.get(command, ) if rm in command or in command: # 简单示例实际应更复杂 return False, fShell tool call blocked for command: {command} return True, None class OutputGuard: 输出守卫对Agent的最终输出进行过滤和格式化 staticmethod def filter_sensitive_info(text: str) - str: 过滤可能的敏感信息如密钥、内部IP # 简单正则示例生产环境需更完善的规则 patterns { rsk-[a-zA-Z0-9]{48}: [OPENAI_KEY_REDACTED], r\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b: [IP_REDACTED], } for pattern, replacement in patterns.items(): text re.sub(pattern, replacement, text) return text staticmethod def ensure_format(output: Dict[str, Any]) - Dict[str, Any]: 确保输出格式符合下游系统要求 standardized { data: output.get(output, ), metadata: { steps: len(output.get(intermediate_steps, [])), status: output.get(status, unknown), } } if output.get(status) error: standardized[error] output.get(error) return standardized class HarnessCallbackHandler(BaseCallbackHandler): LangChain回调处理器用于在Agent执行过程中介入 def on_tool_start(self, serialized: Dict[str, Any], input_str: str, **kwargs): 在工具开始执行时触发 tool_name serialized.get(name, unknown) logger.info(fHarness: Tool {tool_name} is about to be called with input: {input_str[:100]}...) # 这里可以加入更复杂的审批或阻断逻辑 # 例如对于高风险工具可以暂停执行并等待人工确认 def on_agent_action(self, action, **kwargs): 在Agent决定采取行动时触发 logger.info(fHarness: Agent chose action: {action.tool}) def create_harnessed_runner(runner, security_policy: SecurityPolicy, output_guard: OutputGuard): 创建一个被Harness包裹的Agent Runner装饰器模式 original_arun runner.arun async def harnessed_arun(input_text: str, **kwargs): # 1. 输入安全检查 is_valid, msg security_policy.validate_input(input_text) if not is_valid: return {output: fSecurity validation failed: {msg}, status: rejected} # 2. 注入回调处理器用于过程监控 callbacks kwargs.get(callbacks, []) callbacks.append(HarnessCallbackHandler()) kwargs[callbacks] callbacks # 3. 执行原始Agent raw_result await original_arun(input_text, **kwargs) # 4. 输出后处理 raw_result[output] output_guard.filter_sensitive_info(raw_result.get(output, )) final_result output_guard.ensure_format(raw_result) return final_result runner.arun harnessed_arun return runnerHarness的价值安全边界SecurityPolicy在输入和工具调用层面建立了第一道防线。过程可观测HarnessCallbackHandler让我们能实时看到Agent的决策过程。输出标准化OutputGuard确保不同Agent的输出格式统一并过滤敏感信息便于下游系统消费。5. 核心支柱三设计Loop与度量体系一个强大的Agent系统需要能自我演进。Loop定义了任务执行和迭代的流程而度量体系则提供了评估和优化的依据。5.1 实现一个带度量的任务执行Loop在app/core/metrics.py中我们定义度量指标和评估循环。# app/core/metrics.py import time from typing import Dict, Any, List, Callable from dataclasses import dataclass from enum import Enum import json class AgentStatus(Enum): SUCCESS success FAILURE failure STOPPED stopped_by_guardrail # 被Harness停止 dataclass class AgentMetric: 单次Agent运行的度量数据 agent_name: str start_time: float end_time: float input_tokens: int 0 output_tokens: int 0 tool_calls: int 0 iterations: int 0 status: AgentStatus AgentStatus.SUCCESS error_msg: str custom_tags: Dict[str, Any] None property def duration(self) - float: return self.end_time - start_time property def total_tokens(self) - int: return self.input_tokens self.output_tokens class MetricCollector: 度量收集器 def __init__(self): self.metrics: List[AgentMetric] [] def start_run(self, agent_name: str) - AgentMetric: metric AgentMetric(agent_nameagent_name, start_timetime.time()) return metric def end_run(self, metric: AgentMetric, status: AgentStatus, **kwargs): metric.end_time time.time() metric.status status for key, value in kwargs.items(): if hasattr(metric, key): setattr(metric, key, value) self.metrics.append(metric) # 简单打印日志生产环境应推送至Prometheus/OpenTelemetry logger.info(fMetric recorded: {metric}) def get_summary(self) - Dict[str, Any]: 获取汇总统计信息 if not self.metrics: return {} successful [m for m in self.metrics if m.status AgentStatus.SUCCESS] return { total_runs: len(self.metrics), success_rate: len(successful) / len(self.metrics) if self.metrics else 0, avg_duration: sum(m.duration for m in self.metrics) / len(self.metrics) if self.metrics else 0, avg_tokens: sum(m.total_tokens for m in self.metrics) / len(self.metrics) if self.metrics else 0, } def evaluate_agent_output(task: str, agent_output: str, ground_truth: str None) - Dict[str, float]: 评估Agent输出质量示例简单基于规则的评分 score 0.0 feedback [] # 规则1输出是否为空 if not agent_output or agent_output.strip() : return {score: 0.0, feedback: [Output is empty]} # 规则2是否包含任务关键词简单示例 task_keywords [fix, review, suggest] # 根据任务动态生成 for kw in task_keywords: if kw in task.lower() and kw in agent_output.lower(): score 0.3 feedback.append(fContains task keyword {kw}) # 规则3输出长度适中避免过于简短或冗长 if 50 len(agent_output) 2000: score 0.4 feedback.append(Output length is appropriate) else: feedback.append(Output length may be suboptimal) # 如果有标准答案可以计算相似度 (例如使用BERTScore) if ground_truth: # 此处省略具体的NLP相似度计算实现 feedback.append(Ground truth comparison skipped in demo.) score min(1.0, score) # 确保分数在0-1之间 return {score: round(score, 2), feedback: feedback}5.2 集成Loop与度量的Agent执行流程现在我们将底座、Harness和度量串联起来形成一个完整的执行循环。修改app/core/agent_runner.py增加度量收集功能。# 在 agent_runner.py 的 BaseAgentRunner 类中添加 class BaseAgentRunner: def __init__(self, config: AgentRunConfig, metric_collector: Optional[MetricCollector] None): self.config config self.metric_collector metric_collector # ... 其他初始化 ... async def arun_with_metrics(self, input_text: str, **kwargs) - Dict[str, Any]: 带度量收集的Agent运行 metric None if self.metric_collector: metric self.metric_collector.start_run(self.config.agent_name) try: result await self.arun(input_text, **kwargs) status AgentStatus.SUCCESS if result.get(status) success else AgentStatus.FAILURE # 模拟收集Token和迭代次数 (实际需从LLM回调或结果中解析) token_estimate len(input_text) // 4 len(result.get(output, )) // 4 if self.metric_collector and metric: self.metric_collector.end_run( metric, statusstatus, input_tokenstoken_estimate, output_tokenstoken_estimate, tool_callslen(result.get(intermediate_steps, [])), iterationslen(result.get(intermediate_steps, [])), error_msgresult.get(error, ) ) # 执行评估 eval_result evaluate_agent_output(input_text, result.get(output, )) result[evaluation] eval_result return result except Exception as e: if self.metric_collector and metric: self.metric_collector.end_run(metric, statusAgentStatus.FAILURE, error_msgstr(e)) raise这个Loop不仅执行任务还自动收集耗时、Token使用、工具调用次数等指标并对输出结果进行初步评估为后续的优化提供数据基础。6. 核心支柱四集成知识工程——让Agent更“专业”对于研发场景让Agent理解项目特定的代码规范、API文档、架构上下文至关重要。这需要通过知识库RAG来实现。6.1 构建一个简单的代码知识库我们使用ChromaDB作为向量存储将项目文档嵌入其中。# app/knowledge/vector_store.py from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.document_loaders import TextLoader, DirectoryLoader import os from typing import List from langchain.schema import Document class CodeKnowledgeBase: 代码知识库管理类 def __init__(self, persist_directory: str ./data/chroma_db): self.embeddings OpenAIEmbeddings(api_keyos.getenv(OPENAI_API_KEY)) self.persist_directory persist_directory self.vector_store None self._init_vector_store() def _init_vector_store(self): 初始化或加载已有的向量存储 if os.path.exists(self.persist_directory) and os.listdir(self.persist_directory): # 加载已有数据库 self.vector_store Chroma( persist_directoryself.persist_directory, embedding_functionself.embeddings ) print(fLoaded existing knowledge base from {self.persist_directory}) else: # 创建新的空数据库 self.vector_store Chroma( persist_directoryself.persist_directory, embedding_functionself.embeddings ) print(fCreated new knowledge base at {self.persist_directory}) def ingest_code_docs(self, doc_paths: List[str]): 摄取代码文档如README、API文档、代码注释 all_docs [] text_splitter RecursiveCharacterTextSplitter( chunk_size1000, chunk_overlap200 ) for path in doc_paths: if os.path.isfile(path): loader TextLoader(path) docs loader.load() splits text_splitter.split_documents(docs) all_docs.extend(splits) elif os.path.isdir(path): loader DirectoryLoader(path, glob**/*.md) # 示例只加载markdown文件 docs loader.load() splits text_splitter.split_documents(docs) all_docs.extend(splits) if all_docs: self.vector_store.add_documents(all_docs) print(fIngested {len(all_docs)} document chunks into knowledge base.) def query(self, question: str, k: int 3) - List[Document]: 查询知识库获取相关上下文 if not self.vector_store: return [] return self.vector_store.similarity_search(question, kk) def as_retriever(self): 返回一个检索器方便与LangChain链集成 return self.vector_store.as_retriever(search_kwargs{k: 3})6.2 创建利用知识的代码评审Agent现在我们创建一个具体的Agent它能在评审代码时查询知识库中的编码规范。# app/agents/code_review_agent.py from app.core.agent_runner import BaseAgentRunner, AgentRunConfig from app.core.harness import SecurityPolicy, OutputGuard, create_harnessed_runner from app.core.metrics import MetricCollector from app.knowledge.vector_store import CodeKnowledgeBase from langchain.agents import Tool from typing import List def create_code_review_tool(knowledge_base: CodeKnowledgeBase) - Tool: 创建一个查询代码规范的工具 def query_code_guidelines(query: str) - str: 根据问题查询相关的代码规范和最佳实践。 docs knowledge_base.query(query) if not docs: return No relevant guidelines found in the knowledge base. context \n\n---\n\n.join([doc.page_content for doc in docs]) return fRelevant guidelines from knowledge base:\n{context} return Tool( namequery_code_guidelines, funcquery_code_guidelines, descriptionUseful for looking up company-specific coding standards, best practices, and API guidelines when reviewing code. Input should be a specific question about coding practices. ) class CodeReviewAgent: def __init__(self, knowledge_base_path: str ./docs): # 1. 初始化知识库 self.kb CodeKnowledgeBase() # 可以在这里预加载文档 # self.kb.ingest_code_docs([knowledge_base_path]) # 2. 创建工具集 self.tools [ create_code_review_tool(self.kb), # 未来可以添加更多工具如静态分析工具调用、代码复杂度计算等 ] # 3. 配置Agent system_prompt You are a senior software engineer performing a code review. Your goal is to identify bugs, security issues, performance problems, and deviations from company coding standards. You have access to a knowledge base of company guidelines. Use the query_code_guidelines tool if you are unsure about a specific rule. Be concise, constructive, and prioritize critical issues. Format your review as: 1. **Critical Issues** (Bugs, Security flaws) 2. **Major Issues** (Performance, Maintainability) 3. **Minor Issues Suggestions** (Style, Readability) 4. **Summary** config AgentRunConfig( agent_namecode_reviewer_v1, system_promptsystem_prompt, toolsself.tools, max_iterations5 # 代码评审不需要太多轮次 ) # 4. 初始化运行底座和度量 self.metric_collector MetricCollector() self.runner BaseAgentRunner(config, metric_collectorself.metric_collector) # 5. 应用Harness控制 security_policy SecurityPolicy() output_guard OutputGuard() self.runner create_harnessed_runner(self.runner, security_policy, output_guard) async def review(self, code_snippet: str) - Dict[str, Any]: 评审一段代码 prompt fPlease review the following code and provide feedback:\npython\n{code_snippet}\n result await self.runner.arun_with_metrics(prompt) return result def get_metrics_summary(self): 获取该Agent的度量摘要 return self.metric_collector.get_summary()7. 完整实战搭建一个可运行的Agent服务我们将上述所有模块整合通过FastAPI暴露一个简单的HTTP服务。7.1 创建FastAPI主应用app/main.py# app/main.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from app.agents.code_review_agent import CodeReviewAgent import uvicorn import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) app FastAPI(titleAI Agent Platform, version0.1.0) # 全局Agent实例 (简单示例生产环境需考虑并发和生命周期) code_review_agent None app.on_event(startup) async def startup_event(): 服务启动时初始化Agent global code_review_agent logger.info(Initializing Code Review Agent...) # 此处可以传入实际的知识库文档路径 code_review_agent CodeReviewAgent(knowledge_base_path./company_docs) logger.info(Code Review Agent initialized.) class CodeReviewRequest(BaseModel): code: str language: str python # 可扩展支持多语言 class CodeReviewResponse(BaseModel): review: str status: str evaluation: dict None metrics: dict None app.post(/api/v1/code-review, response_modelCodeReviewResponse) async def review_code(request: CodeReviewRequest): 代码评审接口 if not code_review_agent: raise HTTPException(status_code503, detailAgent not initialized.) try: result await code_review_agent.review(request.code) return CodeReviewResponse( reviewresult.get(output, No review generated.), statusresult.get(status, unknown), evaluationresult.get(evaluation, {}), metricscode_review_agent.get_metrics_summary() ) except Exception as e: logger.exception(Code review failed.) raise HTTPException(status_code500, detailfAgent execution error: {str(e)}) app.get(/health) async def health_check(): 健康检查端点 return {status: healthy, service: ai_agent_platform} if __name__ __main__: uvicorn.run(app.main:app, host0.0.0.0, port8000, reloadTrue)7.2 配置与运行创建配置文件config/settings.py和环境变量文件.env。# config/settings.py from pydantic_settings import BaseSettings class Settings(BaseSettings): openai_api_key: str chroma_persist_dir: str ./data/chroma_db agent_max_iterations: int 10 class Config: env_file .env settings Settings().env文件OPENAI_API_KEYyour_openai_api_key_here7.3 启动服务并进行测试确保.env文件已配置。在项目根目录运行python -m app.main服务将在http://localhost:8000启动。使用curl或 Postman 进行测试curl -X POST http://localhost:8000/api/v1/code-review \ -H Content-Type: application/json \ -d { code: def calculate_total(items):\n total 0\n for item in items:\n total item[\price\]\n return total\n\n# Test the function\nprices [{\price\: 10}, {\price\: 20}]\nprint(calculate_total(prices)), language: python }你将在控制台看到Agent详细的思考过程verboseTrue并在HTTP响应中收到结构化的评审结果和度量数据。8. 常见问题与排查思路在部署和运行此类AI Agent系统时你可能会遇到以下典型问题问题现象可能原因排查思路与解决方案Agent陷入无限循环或达到最大迭代次数1. 任务定义不清晰Agent无法找到终止条件。2. 可用工具不足以完成任务。3. 模型温度temperature过高导致决策不稳定。1.优化提示词在System Prompt中明确给出任务完成的判断标准例如“当你提供了完整的修改建议后就结束任务”。2.增强工具检查工具描述是否准确增加必要的工具或让工具返回更明确的结束信号。3.调整参数将temperature调低如0.1降低随机性适当增加max_iterations但需配合Harness监控。工具调用失败或返回意外结果1. 工具函数的输入参数格式与Agent预期不符。2. 工具执行过程中抛出异常未处理。3. 工具依赖的外部服务不可用。1.验证工具定义确保Tool的description和参数描述清晰。使用Pydantic模型严格定义输入。2.加强错误处理在工具函数内部使用try-except返回结构化的错误信息供Agent理解。3.添加健康检查在Harness层或工具调用前对关键依赖如数据库、API做连通性检查。Token消耗过高成本失控1. Agent在复杂任务中与模型交互轮次过多。2. 知识库返回的上下文过长。3. 提示词过于冗长。1.实施预算控制在MetricCollector中实时计算累计Token达到阈值时强制终止任务。2.优化检索知识库检索时使用search_kwargs{“k”: 2}减少返回片段对长文档进行更智能的分块和摘要。3.精简提示词移除不必要的背景描述使用更简洁的指令。Agent输出不符合格式要求或包含不安全内容1. 输出解析Output Parser失败。2. Harness中的输出过滤规则不完善。3. 模型产生了“幻觉”。1.强化解析使用LangChain的StructuredOutputParser或Pydantic解析器来约束输出格式。2.完善守卫规则在OutputGuard中增加针对业务场景的敏感词过滤和格式校验。3.后处理校验增加一个独立的“校验Agent”或规则引擎对主Agent的输出进行二次检查和修正。知识库检索结果不相关1. 文档分块策略不合理。2. 嵌入模型不适合领域文本。3. 查询问题表述不佳。1.调整分块尝试不同的chunk_size和chunk_overlap。对于代码可以按函数或类进行分块。2.微调或更换嵌入模型考虑使用针对代码训练的嵌入模型如text-embedding-3-large。3.查询重写在查询知识库前先用LLM对用户原始问题进行重写或扩展以提高检索命中率。9. 最佳实践与工程建议将AI Agent投入真实研发流程除了功能实现更需要关注工程规范和可持续性。1. 版本化与回滚提示词版本化将Agent的System Prompt、工具描述等存入Git与代码一同管理。任何修改都应通过PR流程。模型版本化记录每次部署所使用的具体模型版本如gpt-4-1106-preview便于在模型更新导致行为变化时进行回滚或对比测试。配置即代码AgentRunConfig等配置应使用配置文件或数据库管理避免硬编码。2. 测试策略单元测试针对工具函数、Harness策略、度量计算等独立模块编写单元测试。集成测试模拟端到端的Agent调用使用固定的“黄金标准”输入断言其输出关键部分是否符合预期。回归测试集建立一批涵盖核心场景的测试用例在每次Agent或模型更新后运行监控效果变化。3. 可观测性与监控结构化日志记录每次运行的完整上下文包括输入、输出、中间步骤、Token使用、耗时。使用JSON格式便于后续分析。关键指标告警监控成功率、平均耗时、Token消耗的P99分位值。设置告警阈值例如连续5次失败或单次Token消耗超过10万。追踪与调试集成OpenTelemetry等追踪系统可视化Agent的完整决策链路方便定位性能瓶颈或逻辑错误。4. 安全与权限最小权限原则为Agent工具分配尽可能少的权限。例如文件操作工具应限制在特定沙箱目录数据库工具应使用只读账号。输入输出净化Harness层的安全策略必须严格执行。对所有用户输入和工具输出进行验证和过滤。人工审核环节对于高风险操作如直接提交代码、操作生产数据库设计“人工确认”环节Agent生成计划由人最终批准执行。5. 持续迭代与评估A/B测试对于重要的Agent任务如代码评审可以并行运行新旧两个版本的Agent对比其输出质量和效率。反馈闭环建立用户反馈机制如“这条评审建议是否有用”将反馈数据用于微调提示词或优化知识库。定期复盘基于MetricCollector收集的数据定期分析Agent的薄弱环节有针对性地进行优化。构建一个工程化的AI Agent系统本质上是将不确定性的大模型能力通过确定的软件工程方法进行封装和管理。本文提供的运行底座、Harness控制、Loop与度量、知识工程四大支柱构成了一个稳健的起点。你可以在此基础上根据具体的业务场景扩展更复杂的工具、设计更精细的控制流、集成更丰富的知识来源。记住成功的Agent项目不是一蹴而就的它始于一个最小可行产品MVP并通过持续的度量和迭代走向成熟。 AI Agent工程化实战：从运行底座到知识集成的全链路架构
在业务迭代中引入AI大模型尤其是构建能够自主执行任务的智能体Agent已成为提升研发效能的关键路径。然而从概念验证到稳定融入真实研发交付流程团队常常面临“最后一公里”的挑战Agent如何与现有工程体系对接如何确保其行为可控、结果可度量如何管理其长期记忆与知识本文将基于一套经过大厂实战检验的架构方案完整拆解从运行底座搭建、Harness控制、Loop与度量到知识工程集成的全链路闭环。无论你是希望将AI能力引入现有项目的架构师还是探索Agent开发的工程师都能从中获得可直接复用的代码、配置与避坑指南。1. 背景与核心概念为什么需要“工程化”的AI Agent单纯调用大模型的API完成一次对话或文本生成与构建一个能持续、稳定、安全地参与软件研发流程的AI智能体是截然不同的两件事。后者要求我们将AI视为一个新型的、特殊的“软件组件”进行工程化治理。1.1 AI Agent 的本质与挑战一个AI Agent通常由大模型LLM、规划器、工具集、记忆模块等构成它能理解目标规划步骤调用工具如执行代码、查询API并基于结果进行迭代。其核心挑战在于不可预测性大模型的输出具有随机性可能导致任务偏离预期。状态管理复杂Agent在长周期任务中需要维护对话历史、工具调用结果等状态。工具调用安全赋予Agent执行代码、操作数据库等能力时必须建立严格的安全沙箱和权限控制。效果评估困难如何量化一个Agent在复杂任务如代码评审、Bug定位上的表现1.2 工程化落地的核心支柱为了解决上述挑战一个面向生产环境的Agent系统需要四大支柱运行底座提供稳定、可扩展的执行环境管理Agent的生命周期、资源隔离和工具调用。Harness控制像“缰绳”一样对Agent的行为进行约束、引导和监控防止其“脱缰”。Loop与度量设计任务执行循环并建立一套可观测性体系对Agent的决策、工具使用、最终结果进行量化评估。知识工程为Agent注入领域知识如公司代码规范、业务架构图使其决策更精准、更专业。接下来我们将围绕这四大支柱展开实战详解。2. 环境准备与版本说明本文的实战示例将采用Python作为主要开发语言并基于一些主流的开源框架构建。请注意AI领域迭代迅速以下版本是一个稳定的参考组合实际项目中请根据情况调整。操作系统: Ubuntu 20.04 LTS / macOS Monterey 或更高版本 / Windows 11 WSL2Python: 3.9 或 3.10 (推荐3.9兼容性最佳)关键框架与库:langchain-core0.1.0: Agent框架的核心编排库。langchain-openai0.0.5: 用于接入OpenAI系列模型。pydantic2.5.0: 用于数据验证和设置管理。fastapi0.104.1: 用于构建控制API。uvicorn0.24.0: ASGI服务器。大模型服务: 本文示例使用gpt-4-turbo-preview你需要准备相应的API Key。也可替换为其他兼容OpenAI API的模型服务如Azure OpenAI, 通义千问等。开发工具: 任意IDE (VSCode, PyCharm) 以及git。项目结构预览ai_agent_platform/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 应用入口 │ ├── core/ │ │ ├── __init__.py │ │ ├── agent_runner.py # 运行底座核心 │ │ ├── harness.py # 控制与约束逻辑 │ │ └── metrics.py # 度量与评估 │ ├── agents/ │ │ ├── __init__.py │ │ └── code_review_agent.py # 具体Agent实现 │ ├── tools/ │ │ ├── __init__.py │ │ └── code_tools.py # Agent可用的工具集 │ └── knowledge/ │ ├── __init__.py │ └── vector_store.py # 知识库相关 ├── config/ │ └── settings.py # 配置文件 ├── tests/ # 测试目录 ├── requirements.txt # 依赖文件 └── .env.example # 环境变量示例首先创建项目并安装基础依赖# 创建项目目录 mkdir ai_agent_platform cd ai_agent_platform # 创建虚拟环境 (推荐) python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 创建基础文件 mkdir -p app/core app/agents app/tools app/knowledge config tests touch app/main.py app/core/agent_runner.py app/core/harness.py app/core/metrics.py touch app/agents/code_review_agent.py app/tools/code_tools.py touch app/knowledge/vector_store.py config/settings.py requirements.txt .env.example编辑requirements.txt文件langchain-core0.1.0 langchain-openai0.0.5 langchain-community0.0.10 # 包含更多工具和集成 pydantic2.5.0 pydantic-settings2.1.0 fastapi0.104.1 uvicorn[standard]0.24.0 python-dotenv1.0.0 chromadb0.4.22 # 用于向量知识库 tiktoken0.5.2 # 用于Token计数 pytest7.4.4 # 测试框架安装依赖pip install -r requirements.txt3. 核心支柱一构建稳固的Agent运行底座运行底座负责Agent的实例化、调度、工具执行和环境隔离。它是整个系统的“发动机房”。3.1 设计一个基础的Agent Runnerapp/core/agent_runner.py文件将封装LangChain的Agent执行器并添加生命周期管理。# app/core/agent_runner.py import asyncio from typing import Any, Dict, List, Optional, Callable from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.messages import BaseMessage, HumanMessage, AIMessage from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_openai import ChatOpenAI from pydantic import BaseModel, Field import logging logger logging.getLogger(__name__) class AgentRunConfig(BaseModel): Agent单次运行的配置 agent_name: str system_prompt: str tools: List[Any] Field(default_factorylist) model_name: str gpt-4-turbo-preview temperature: float 0.1 # 降低随机性更适合任务执行 max_iterations: int 10 # 防止Agent无限循环 early_stopping_method: str force # 达到最大迭代后强制停止 class BaseAgentRunner: Agent运行底座基类 def __init__(self, config: AgentRunConfig): self.config config self.llm ChatOpenAI( modelconfig.model_name, temperatureconfig.temperature, api_keyself._get_api_key() # 从环境变量获取 ) self.agent_executor: Optional[AgentExecutor] None self._init_agent() def _get_api_key(self) - str: # 实际项目中应从安全的配置中心读取 import os key os.getenv(OPENAI_API_KEY) if not key: raise ValueError(OPENAI_API_KEY environment variable not set.) return key def _init_agent(self): 初始化LangChain Agent执行器 prompt ChatPromptTemplate.from_messages([ (system, self.config.system_prompt), MessagesPlaceholder(variable_namechat_history), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) agent create_openai_tools_agent(self.llm, self.config.tools, prompt) self.agent_executor AgentExecutor( agentagent, toolsself.config.tools, verboseTrue, # 输出详细执行日志生产环境可关闭 max_iterationsself.config.max_iterations, early_stopping_methodself.config.early_stopping_method, handle_parsing_errorsTrue, # 优雅处理输出解析错误 ) logger.info(fAgent {self.config.agent_name} initialized.) async def arun(self, input_text: str, chat_history: Optional[List[BaseMessage]] None) - Dict[str, Any]: 异步运行Agent if not self.agent_executor: raise RuntimeError(Agent executor not initialized.) try: # 准备输入 inputs { input: input_text, chat_history: chat_history or [], } # 调用Agent result await self.agent_executor.ainvoke(inputs) logger.info(fAgent {self.config.agent_name} completed task.) return { output: result.get(output, ), intermediate_steps: result.get(intermediate_steps, []), status: success } except Exception as e: logger.error(fAgent {self.config.agent_name} failed: {e}, exc_infoTrue) return { output: fAgent execution error: {str(e)}, intermediate_steps: [], status: error, error: str(e) } def run_sync(self, input_text: str, chat_history: Optional[List[BaseMessage]] None) - Dict[str, Any]: 同步运行Agent (包装异步方法) return asyncio.run(self.arun(input_text, chat_history))关键设计解析配置化通过AgentRunConfigPydantic模型管理配置保证类型安全且易于测试。错误处理在arun方法中包裹了异常捕获防止单个Agent崩溃导致整个服务不可用。资源控制max_iterations和early_stopping_method是防止Agent陷入死循环的关键参数。异步优先使用async/await支持高并发场景同时提供了同步接口run_sync方便调试。4. 核心支柱二实现Harness控制——给Agent套上“缰绳”Harness控制的核心是在Agent执行的关键节点插入钩子Hooks进行输入检查、过程干预和输出过滤。4.1 定义控制策略在app/core/harness.py中我们实现一个简单的控制层。# app/core/harness.py from typing import Dict, Any, Optional, List from langchain_core.tools import BaseTool from langchain_core.callbacks import BaseCallbackHandler import re import logging logger logging.getLogger(__name__) class SecurityPolicy: 安全策略检查输入和工具调用 staticmethod def validate_input(user_input: str) - tuple[bool, Optional[str]]: 验证用户输入是否安全 # 1. 禁止某些敏感命令模式 dangerous_patterns [ rrm\s-rf, rformat\sc:, rdrop\sdatabase, rsudo, rchmod\s777, rpasswd, ] for pattern in dangerous_patterns: if re.search(pattern, user_input, re.IGNORECASE): return False, fInput contains dangerous pattern: {pattern} # 2. 检查长度限制 (防止提示词注入攻击) if len(user_input) 5000: return False, Input too long, potential prompt injection risk. return True, None staticmethod def validate_tool_call(tool: BaseTool, tool_input: Dict[str, Any]) - tuple[bool, Optional[str]]: 验证工具调用是否被允许 tool_name tool.name # 示例禁止名为“execute_shell”的工具在特定条件下运行 if tool_name execute_shell: command tool_input.get(command, ) if rm in command or in command: # 简单示例实际应更复杂 return False, fShell tool call blocked for command: {command} return True, None class OutputGuard: 输出守卫对Agent的最终输出进行过滤和格式化 staticmethod def filter_sensitive_info(text: str) - str: 过滤可能的敏感信息如密钥、内部IP # 简单正则示例生产环境需更完善的规则 patterns { rsk-[a-zA-Z0-9]{48}: [OPENAI_KEY_REDACTED], r\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b: [IP_REDACTED], } for pattern, replacement in patterns.items(): text re.sub(pattern, replacement, text) return text staticmethod def ensure_format(output: Dict[str, Any]) - Dict[str, Any]: 确保输出格式符合下游系统要求 standardized { data: output.get(output, ), metadata: { steps: len(output.get(intermediate_steps, [])), status: output.get(status, unknown), } } if output.get(status) error: standardized[error] output.get(error) return standardized class HarnessCallbackHandler(BaseCallbackHandler): LangChain回调处理器用于在Agent执行过程中介入 def on_tool_start(self, serialized: Dict[str, Any], input_str: str, **kwargs): 在工具开始执行时触发 tool_name serialized.get(name, unknown) logger.info(fHarness: Tool {tool_name} is about to be called with input: {input_str[:100]}...) # 这里可以加入更复杂的审批或阻断逻辑 # 例如对于高风险工具可以暂停执行并等待人工确认 def on_agent_action(self, action, **kwargs): 在Agent决定采取行动时触发 logger.info(fHarness: Agent chose action: {action.tool}) def create_harnessed_runner(runner, security_policy: SecurityPolicy, output_guard: OutputGuard): 创建一个被Harness包裹的Agent Runner装饰器模式 original_arun runner.arun async def harnessed_arun(input_text: str, **kwargs): # 1. 输入安全检查 is_valid, msg security_policy.validate_input(input_text) if not is_valid: return {output: fSecurity validation failed: {msg}, status: rejected} # 2. 注入回调处理器用于过程监控 callbacks kwargs.get(callbacks, []) callbacks.append(HarnessCallbackHandler()) kwargs[callbacks] callbacks # 3. 执行原始Agent raw_result await original_arun(input_text, **kwargs) # 4. 输出后处理 raw_result[output] output_guard.filter_sensitive_info(raw_result.get(output, )) final_result output_guard.ensure_format(raw_result) return final_result runner.arun harnessed_arun return runnerHarness的价值安全边界SecurityPolicy在输入和工具调用层面建立了第一道防线。过程可观测HarnessCallbackHandler让我们能实时看到Agent的决策过程。输出标准化OutputGuard确保不同Agent的输出格式统一并过滤敏感信息便于下游系统消费。5. 核心支柱三设计Loop与度量体系一个强大的Agent系统需要能自我演进。Loop定义了任务执行和迭代的流程而度量体系则提供了评估和优化的依据。5.1 实现一个带度量的任务执行Loop在app/core/metrics.py中我们定义度量指标和评估循环。# app/core/metrics.py import time from typing import Dict, Any, List, Callable from dataclasses import dataclass from enum import Enum import json class AgentStatus(Enum): SUCCESS success FAILURE failure STOPPED stopped_by_guardrail # 被Harness停止 dataclass class AgentMetric: 单次Agent运行的度量数据 agent_name: str start_time: float end_time: float input_tokens: int 0 output_tokens: int 0 tool_calls: int 0 iterations: int 0 status: AgentStatus AgentStatus.SUCCESS error_msg: str custom_tags: Dict[str, Any] None property def duration(self) - float: return self.end_time - start_time property def total_tokens(self) - int: return self.input_tokens self.output_tokens class MetricCollector: 度量收集器 def __init__(self): self.metrics: List[AgentMetric] [] def start_run(self, agent_name: str) - AgentMetric: metric AgentMetric(agent_nameagent_name, start_timetime.time()) return metric def end_run(self, metric: AgentMetric, status: AgentStatus, **kwargs): metric.end_time time.time() metric.status status for key, value in kwargs.items(): if hasattr(metric, key): setattr(metric, key, value) self.metrics.append(metric) # 简单打印日志生产环境应推送至Prometheus/OpenTelemetry logger.info(fMetric recorded: {metric}) def get_summary(self) - Dict[str, Any]: 获取汇总统计信息 if not self.metrics: return {} successful [m for m in self.metrics if m.status AgentStatus.SUCCESS] return { total_runs: len(self.metrics), success_rate: len(successful) / len(self.metrics) if self.metrics else 0, avg_duration: sum(m.duration for m in self.metrics) / len(self.metrics) if self.metrics else 0, avg_tokens: sum(m.total_tokens for m in self.metrics) / len(self.metrics) if self.metrics else 0, } def evaluate_agent_output(task: str, agent_output: str, ground_truth: str None) - Dict[str, float]: 评估Agent输出质量示例简单基于规则的评分 score 0.0 feedback [] # 规则1输出是否为空 if not agent_output or agent_output.strip() : return {score: 0.0, feedback: [Output is empty]} # 规则2是否包含任务关键词简单示例 task_keywords [fix, review, suggest] # 根据任务动态生成 for kw in task_keywords: if kw in task.lower() and kw in agent_output.lower(): score 0.3 feedback.append(fContains task keyword {kw}) # 规则3输出长度适中避免过于简短或冗长 if 50 len(agent_output) 2000: score 0.4 feedback.append(Output length is appropriate) else: feedback.append(Output length may be suboptimal) # 如果有标准答案可以计算相似度 (例如使用BERTScore) if ground_truth: # 此处省略具体的NLP相似度计算实现 feedback.append(Ground truth comparison skipped in demo.) score min(1.0, score) # 确保分数在0-1之间 return {score: round(score, 2), feedback: feedback}5.2 集成Loop与度量的Agent执行流程现在我们将底座、Harness和度量串联起来形成一个完整的执行循环。修改app/core/agent_runner.py增加度量收集功能。# 在 agent_runner.py 的 BaseAgentRunner 类中添加 class BaseAgentRunner: def __init__(self, config: AgentRunConfig, metric_collector: Optional[MetricCollector] None): self.config config self.metric_collector metric_collector # ... 其他初始化 ... async def arun_with_metrics(self, input_text: str, **kwargs) - Dict[str, Any]: 带度量收集的Agent运行 metric None if self.metric_collector: metric self.metric_collector.start_run(self.config.agent_name) try: result await self.arun(input_text, **kwargs) status AgentStatus.SUCCESS if result.get(status) success else AgentStatus.FAILURE # 模拟收集Token和迭代次数 (实际需从LLM回调或结果中解析) token_estimate len(input_text) // 4 len(result.get(output, )) // 4 if self.metric_collector and metric: self.metric_collector.end_run( metric, statusstatus, input_tokenstoken_estimate, output_tokenstoken_estimate, tool_callslen(result.get(intermediate_steps, [])), iterationslen(result.get(intermediate_steps, [])), error_msgresult.get(error, ) ) # 执行评估 eval_result evaluate_agent_output(input_text, result.get(output, )) result[evaluation] eval_result return result except Exception as e: if self.metric_collector and metric: self.metric_collector.end_run(metric, statusAgentStatus.FAILURE, error_msgstr(e)) raise这个Loop不仅执行任务还自动收集耗时、Token使用、工具调用次数等指标并对输出结果进行初步评估为后续的优化提供数据基础。6. 核心支柱四集成知识工程——让Agent更“专业”对于研发场景让Agent理解项目特定的代码规范、API文档、架构上下文至关重要。这需要通过知识库RAG来实现。6.1 构建一个简单的代码知识库我们使用ChromaDB作为向量存储将项目文档嵌入其中。# app/knowledge/vector_store.py from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.document_loaders import TextLoader, DirectoryLoader import os from typing import List from langchain.schema import Document class CodeKnowledgeBase: 代码知识库管理类 def __init__(self, persist_directory: str ./data/chroma_db): self.embeddings OpenAIEmbeddings(api_keyos.getenv(OPENAI_API_KEY)) self.persist_directory persist_directory self.vector_store None self._init_vector_store() def _init_vector_store(self): 初始化或加载已有的向量存储 if os.path.exists(self.persist_directory) and os.listdir(self.persist_directory): # 加载已有数据库 self.vector_store Chroma( persist_directoryself.persist_directory, embedding_functionself.embeddings ) print(fLoaded existing knowledge base from {self.persist_directory}) else: # 创建新的空数据库 self.vector_store Chroma( persist_directoryself.persist_directory, embedding_functionself.embeddings ) print(fCreated new knowledge base at {self.persist_directory}) def ingest_code_docs(self, doc_paths: List[str]): 摄取代码文档如README、API文档、代码注释 all_docs [] text_splitter RecursiveCharacterTextSplitter( chunk_size1000, chunk_overlap200 ) for path in doc_paths: if os.path.isfile(path): loader TextLoader(path) docs loader.load() splits text_splitter.split_documents(docs) all_docs.extend(splits) elif os.path.isdir(path): loader DirectoryLoader(path, glob**/*.md) # 示例只加载markdown文件 docs loader.load() splits text_splitter.split_documents(docs) all_docs.extend(splits) if all_docs: self.vector_store.add_documents(all_docs) print(fIngested {len(all_docs)} document chunks into knowledge base.) def query(self, question: str, k: int 3) - List[Document]: 查询知识库获取相关上下文 if not self.vector_store: return [] return self.vector_store.similarity_search(question, kk) def as_retriever(self): 返回一个检索器方便与LangChain链集成 return self.vector_store.as_retriever(search_kwargs{k: 3})6.2 创建利用知识的代码评审Agent现在我们创建一个具体的Agent它能在评审代码时查询知识库中的编码规范。# app/agents/code_review_agent.py from app.core.agent_runner import BaseAgentRunner, AgentRunConfig from app.core.harness import SecurityPolicy, OutputGuard, create_harnessed_runner from app.core.metrics import MetricCollector from app.knowledge.vector_store import CodeKnowledgeBase from langchain.agents import Tool from typing import List def create_code_review_tool(knowledge_base: CodeKnowledgeBase) - Tool: 创建一个查询代码规范的工具 def query_code_guidelines(query: str) - str: 根据问题查询相关的代码规范和最佳实践。 docs knowledge_base.query(query) if not docs: return No relevant guidelines found in the knowledge base. context \n\n---\n\n.join([doc.page_content for doc in docs]) return fRelevant guidelines from knowledge base:\n{context} return Tool( namequery_code_guidelines, funcquery_code_guidelines, descriptionUseful for looking up company-specific coding standards, best practices, and API guidelines when reviewing code. Input should be a specific question about coding practices. ) class CodeReviewAgent: def __init__(self, knowledge_base_path: str ./docs): # 1. 初始化知识库 self.kb CodeKnowledgeBase() # 可以在这里预加载文档 # self.kb.ingest_code_docs([knowledge_base_path]) # 2. 创建工具集 self.tools [ create_code_review_tool(self.kb), # 未来可以添加更多工具如静态分析工具调用、代码复杂度计算等 ] # 3. 配置Agent system_prompt You are a senior software engineer performing a code review. Your goal is to identify bugs, security issues, performance problems, and deviations from company coding standards. You have access to a knowledge base of company guidelines. Use the query_code_guidelines tool if you are unsure about a specific rule. Be concise, constructive, and prioritize critical issues. Format your review as: 1. **Critical Issues** (Bugs, Security flaws) 2. **Major Issues** (Performance, Maintainability) 3. **Minor Issues Suggestions** (Style, Readability) 4. **Summary** config AgentRunConfig( agent_namecode_reviewer_v1, system_promptsystem_prompt, toolsself.tools, max_iterations5 # 代码评审不需要太多轮次 ) # 4. 初始化运行底座和度量 self.metric_collector MetricCollector() self.runner BaseAgentRunner(config, metric_collectorself.metric_collector) # 5. 应用Harness控制 security_policy SecurityPolicy() output_guard OutputGuard() self.runner create_harnessed_runner(self.runner, security_policy, output_guard) async def review(self, code_snippet: str) - Dict[str, Any]: 评审一段代码 prompt fPlease review the following code and provide feedback:\npython\n{code_snippet}\n result await self.runner.arun_with_metrics(prompt) return result def get_metrics_summary(self): 获取该Agent的度量摘要 return self.metric_collector.get_summary()7. 完整实战搭建一个可运行的Agent服务我们将上述所有模块整合通过FastAPI暴露一个简单的HTTP服务。7.1 创建FastAPI主应用app/main.py# app/main.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from app.agents.code_review_agent import CodeReviewAgent import uvicorn import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) app FastAPI(titleAI Agent Platform, version0.1.0) # 全局Agent实例 (简单示例生产环境需考虑并发和生命周期) code_review_agent None app.on_event(startup) async def startup_event(): 服务启动时初始化Agent global code_review_agent logger.info(Initializing Code Review Agent...) # 此处可以传入实际的知识库文档路径 code_review_agent CodeReviewAgent(knowledge_base_path./company_docs) logger.info(Code Review Agent initialized.) class CodeReviewRequest(BaseModel): code: str language: str python # 可扩展支持多语言 class CodeReviewResponse(BaseModel): review: str status: str evaluation: dict None metrics: dict None app.post(/api/v1/code-review, response_modelCodeReviewResponse) async def review_code(request: CodeReviewRequest): 代码评审接口 if not code_review_agent: raise HTTPException(status_code503, detailAgent not initialized.) try: result await code_review_agent.review(request.code) return CodeReviewResponse( reviewresult.get(output, No review generated.), statusresult.get(status, unknown), evaluationresult.get(evaluation, {}), metricscode_review_agent.get_metrics_summary() ) except Exception as e: logger.exception(Code review failed.) raise HTTPException(status_code500, detailfAgent execution error: {str(e)}) app.get(/health) async def health_check(): 健康检查端点 return {status: healthy, service: ai_agent_platform} if __name__ __main__: uvicorn.run(app.main:app, host0.0.0.0, port8000, reloadTrue)7.2 配置与运行创建配置文件config/settings.py和环境变量文件.env。# config/settings.py from pydantic_settings import BaseSettings class Settings(BaseSettings): openai_api_key: str chroma_persist_dir: str ./data/chroma_db agent_max_iterations: int 10 class Config: env_file .env settings Settings().env文件OPENAI_API_KEYyour_openai_api_key_here7.3 启动服务并进行测试确保.env文件已配置。在项目根目录运行python -m app.main服务将在http://localhost:8000启动。使用curl或 Postman 进行测试curl -X POST http://localhost:8000/api/v1/code-review \ -H Content-Type: application/json \ -d { code: def calculate_total(items):\n total 0\n for item in items:\n total item[\price\]\n return total\n\n# Test the function\nprices [{\price\: 10}, {\price\: 20}]\nprint(calculate_total(prices)), language: python }你将在控制台看到Agent详细的思考过程verboseTrue并在HTTP响应中收到结构化的评审结果和度量数据。8. 常见问题与排查思路在部署和运行此类AI Agent系统时你可能会遇到以下典型问题问题现象可能原因排查思路与解决方案Agent陷入无限循环或达到最大迭代次数1. 任务定义不清晰Agent无法找到终止条件。2. 可用工具不足以完成任务。3. 模型温度temperature过高导致决策不稳定。1.优化提示词在System Prompt中明确给出任务完成的判断标准例如“当你提供了完整的修改建议后就结束任务”。2.增强工具检查工具描述是否准确增加必要的工具或让工具返回更明确的结束信号。3.调整参数将temperature调低如0.1降低随机性适当增加max_iterations但需配合Harness监控。工具调用失败或返回意外结果1. 工具函数的输入参数格式与Agent预期不符。2. 工具执行过程中抛出异常未处理。3. 工具依赖的外部服务不可用。1.验证工具定义确保Tool的description和参数描述清晰。使用Pydantic模型严格定义输入。2.加强错误处理在工具函数内部使用try-except返回结构化的错误信息供Agent理解。3.添加健康检查在Harness层或工具调用前对关键依赖如数据库、API做连通性检查。Token消耗过高成本失控1. Agent在复杂任务中与模型交互轮次过多。2. 知识库返回的上下文过长。3. 提示词过于冗长。1.实施预算控制在MetricCollector中实时计算累计Token达到阈值时强制终止任务。2.优化检索知识库检索时使用search_kwargs{“k”: 2}减少返回片段对长文档进行更智能的分块和摘要。3.精简提示词移除不必要的背景描述使用更简洁的指令。Agent输出不符合格式要求或包含不安全内容1. 输出解析Output Parser失败。2. Harness中的输出过滤规则不完善。3. 模型产生了“幻觉”。1.强化解析使用LangChain的StructuredOutputParser或Pydantic解析器来约束输出格式。2.完善守卫规则在OutputGuard中增加针对业务场景的敏感词过滤和格式校验。3.后处理校验增加一个独立的“校验Agent”或规则引擎对主Agent的输出进行二次检查和修正。知识库检索结果不相关1. 文档分块策略不合理。2. 嵌入模型不适合领域文本。3. 查询问题表述不佳。1.调整分块尝试不同的chunk_size和chunk_overlap。对于代码可以按函数或类进行分块。2.微调或更换嵌入模型考虑使用针对代码训练的嵌入模型如text-embedding-3-large。3.查询重写在查询知识库前先用LLM对用户原始问题进行重写或扩展以提高检索命中率。9. 最佳实践与工程建议将AI Agent投入真实研发流程除了功能实现更需要关注工程规范和可持续性。1. 版本化与回滚提示词版本化将Agent的System Prompt、工具描述等存入Git与代码一同管理。任何修改都应通过PR流程。模型版本化记录每次部署所使用的具体模型版本如gpt-4-1106-preview便于在模型更新导致行为变化时进行回滚或对比测试。配置即代码AgentRunConfig等配置应使用配置文件或数据库管理避免硬编码。2. 测试策略单元测试针对工具函数、Harness策略、度量计算等独立模块编写单元测试。集成测试模拟端到端的Agent调用使用固定的“黄金标准”输入断言其输出关键部分是否符合预期。回归测试集建立一批涵盖核心场景的测试用例在每次Agent或模型更新后运行监控效果变化。3. 可观测性与监控结构化日志记录每次运行的完整上下文包括输入、输出、中间步骤、Token使用、耗时。使用JSON格式便于后续分析。关键指标告警监控成功率、平均耗时、Token消耗的P99分位值。设置告警阈值例如连续5次失败或单次Token消耗超过10万。追踪与调试集成OpenTelemetry等追踪系统可视化Agent的完整决策链路方便定位性能瓶颈或逻辑错误。4. 安全与权限最小权限原则为Agent工具分配尽可能少的权限。例如文件操作工具应限制在特定沙箱目录数据库工具应使用只读账号。输入输出净化Harness层的安全策略必须严格执行。对所有用户输入和工具输出进行验证和过滤。人工审核环节对于高风险操作如直接提交代码、操作生产数据库设计“人工确认”环节Agent生成计划由人最终批准执行。5. 持续迭代与评估A/B测试对于重要的Agent任务如代码评审可以并行运行新旧两个版本的Agent对比其输出质量和效率。反馈闭环建立用户反馈机制如“这条评审建议是否有用”将反馈数据用于微调提示词或优化知识库。定期复盘基于MetricCollector收集的数据定期分析Agent的薄弱环节有针对性地进行优化。构建一个工程化的AI Agent系统本质上是将不确定性的大模型能力通过确定的软件工程方法进行封装和管理。本文提供的运行底座、Harness控制、Loop与度量、知识工程四大支柱构成了一个稳健的起点。你可以在此基础上根据具体的业务场景扩展更复杂的工具、设计更精细的控制流、集成更丰富的知识来源。记住成功的Agent项目不是一蹴而就的它始于一个最小可行产品MVP并通过持续的度量和迭代走向成熟。