前言

这篇文章为可直接落地的Agent工程实战教程。无空泛理论，所有代码可直接复制使用。全程从零搭建Agent基础能力、开发自定义技能、实现多技能协同业务。配套生产环境调整方法，帮助开发者快速了解商用级Agent项目开发能力。

项目基于Python+LangChain开发，兼容各类主流大模型。代码解耦性高，可直接迁移至个人项目及公司业务程序，同时配套完整Java复刻版本，适配公司微服务生产场景。

使用者痛点一览

• ① 无限循环调用缺少步骤限制导致Agent卡死。
• ② Token超限报错长对话累积未裁剪，频繁出现“context length exceeded”。话说回来，
• ③ Skill参数解析失败模型输出格式不统一。导致参数无法正确提取，话说回来，
• ④ 网络波动导致接口超时无重试机制的请求经常失败。
• ⑤ 多技能协同调度混乱任务指令不结构化，Agent难以按序执行。
• ⑥ 敏感技能无权限管控所有技能全局开放，引发数据安全风险。

一、开发环境与依赖准备

技术栈选型

主要采用LangChain框架。具备入门简单、环境完善、 性强、模型兼容性广的特点，适配新手入门与公司生产落地。配套环境的观点是，Python3.+、python-dotenv、pydantic、tenacity、loguru。

依赖安装与密钥配置

项目依赖清单

# 主要框架
langchain==0.1.x
langchain-openai==0.x
# 环境配置
python-dotenv==0.x
# 参数校验
pydantic==1.x
# 重试机制
tenacity==8.x
# 日志打印
loguru==0.x

环境变量配置

# 大模型接口配置
OPENAI_API_KEY=你的大模型密钥
OPENAI_API_BASE=大模型接口地址
MODEL_NAME=gpt-4o-mini
# Agent运行配置
AGENT_MAX_STEPS=20 # 最大步骤限制防止无限循环
AGENT_TIMEOUT=300 # 超时秒数防止长时间挂起

全局配置初始化

import os
from dotenv import load_dotenv
load_dotenv
LLM_CONFIG = {
"api_key": os.getenv,"api_base": os.getenv,"model_name": os.getenv,"temperature": 0.1,"max_tokens": 2000,}
AGENT_CONFIG = {
"max_steps": int),"timeout": int)。}

二、基础Agent从零搭建

LLM客户端封装

from langchain_openai import ChatOpenAI
class LLMClient:
_instance = None
def __new__:
if cls._instance is None:
cls._instance = super.__new__
cls._instance._init_client
return cls._instance
def _init_client:
self.client = ChatOpenAI(
api_key=LLM_CONFIG,base_url=LLM_CONFIG,model=LLM_CONFIG,temperature=LLM_CONFIG,max_tokens=LLM_CONFIG,)
def chat:
return self.client.invoke.content
llm_client = LLMClient

长短双记忆程序实现

from langchain.memory import ConversationBufferMemory,ConversationSummaryMemory
class AgentMemory:
def __init__:
self.short_memory = ConversationBufferMemory
self.long_memory = ConversationSummaryMemory
memory = AgentMemory
**注**这方面，文件存储方式便于本地调试；在分布式部署时可替换为 Redis。

ReAct基础Agent搭建
python
from langchain.agents import AgentExecutor。create_react_agent
from langchain.prompts import PromptTemplate
REACT_PROMPT_TEMPLATE = """
你是一个智能Agent，严格遵循ReAct模式完成任务。说起来，可用工具的观点是，{tools}
工具名称的观点是，{tool_names}
对话历史的观点是，{chat_history}
说到使用者任务，{input}
严格按照以下固定格式输出：
Thought: ...
从Action来看。...
Action Input: ...
Observation: ...
Final Answer: ...
最大执行步骤限制：{max_steps} 步。"""
REACT_PROMPT = PromptTemplate.from_template
class BaseReActAgent:
def __init__:
self.llm = llm_client.client
self.memory = memory.short_memory
self.tools =
self.agent_executor=None
def register_tools:...


任务测试与日志解析

python
def test_single_step_task:
res=base_agent.run
assert res


日志主要字段说明


Thought – 需求分析 

Action – 调用工具 

Observation – 工具返回 

Final Answer – 结果 



三、自定义Agent Skill开发规范与实战

Skill标准化开发规范

1️⃣ 命名使用小写下划线；2️⃣ 参数类型显式声明；
3️⃣ 异常捕获全覆盖，4️⃣ 返回统一JSON结构；

轻量函数式Skill示例

python
@tool
def calc->str:
return str)


公司级标准化Skill示例

python
@tool
def query->str:
params=json.loads
# 参数校验 + 数据查询 + JSON返回 …

技能统一注册管理

python
ALL_SKILLS=
base_agent.register_tools



四、多Skill协同复杂业务实战

python
task="""查询2025‑10月全部门报表。计算环比增长率，生成简洁"""
result=base_agent.run



五、Agent生产级调整方法

Token裁剪 & 记忆压缩

python
class MemoryOptimizer:
def crop:…

重试熔断 & 权限隔离

python
@retry
def run_prod: …class SkillPermission:
NORMAL=
ADMIN=
@classmethod def filter_skills: …


六、常见问题与代码级方法



痛点
原因
对策




无限循环调用
未设最大步骤
AGENT_MAX_STEPS 与 max_iterations 强制


Token 超限
长对话未裁剪
crop_chat_history 自动裁剪


Skill 参数解析失败
模型输出不一致
Pydantic 校验 + JSON 格式强制


网络波动/接口超时
无重试机制
Tenacity 指数退避重试


多技能调度混乱
指令无结构化拆分
明确分步语句 + 标准工具返回





七、MD轻量化技能开发模式


优势无需编写 Python，只需编辑 Markdown 即可注册新 Skill。

目录结构


plaintext
agent-project/
├─ config.py # 全局配置
├─ llm_client.py # LLM 单例
├─ memory.py # 双记忆程序
├─ base_agent.py # ReAct Agent
├─ skill_register.py # 技能注册入口
├─ md_skill_parser.py # MD解析引擎
└─ skill_md/
├─ skill_calc.md
├─ skill_summary.md
└─ skill_report.md



MD模板示例


markdown
说到status。enable
version: . 

再看tag，public 

一...


八、项目验收与整体

1️⃣ 安装依赖 → pip install -r requirements.txt
2️⃣ 配置 .env → 填写密钥等信息
3️⃣ 创建 memory/,skill_md/ 文件夹并放入 MD 文件
4️⃣ 运行 python main.py 完成初始化 & 功能测试。

✅ 所有模块均，包括无限循环防护和 Token 裁剪。✅ 支持 Python 与 Java 双版本部署。✅ 可快速迭代添加 MD 或 Python Skill。✅ 满足公司生产级容错、安全隔离和日志持久化需求。


九、Java版 Agent 与 Skill 极简复刻


基于 Spring Boot + Spring AI，实现完整对齐的 LLM 客户端封装。

Redis 分布式会话记忆取代文件存储。

ReAct 推理逻辑完全对应 Python 实现。话说回来，

Java Skill 接口统一为 SkillTool 并提供参数校验与 JSON 返回。


详细实现代码请参考附带 Java 源文件。


十、双版本适配与落地建议



项目维度
Python版优势
Java版优势




开发效率
快速原型 & 调试
稳定并发性能更佳


部署场景
本地或容器快速启动
微服务集群部署优选




说到建议流程，

1️⃣ 原型阶段先用 Python 快速验证业务逻辑和 Skill 可行性。话说回来，2️⃣ 上线阶段切换到 Java。实现高并发、高可靠的微服务部署。3️⃣ 两个版本共享同一套 Skill 开发规范，实现无缝迁移。


以上即为完整的双版本 Agent 开发实战教程。从零搭建到生产调整，再到 MD 与 Java 双栈支持，全程贴合真实痛点，并给出具体代码示例与操作步骤，为您提供一站式落地方案。