在探索 LLM 应用的过程中，LLM作为 Agent 的"大脑"有着无限可能。其中，"代码编写"已经成为了少数几个成功大规模落地的场景之一，这让我们不禁想到：既然 LLM 可以写出高质量的代码，为什么不能让它更进一步，编写并运行代码来控制 Agent 自身的行为呢？这样运行逻辑，就不简简单单的是“下一个”这么简单，而是让Agent拥有分支、循环等各种复杂逻辑。
这个想法虽然听起来有点魔幻，但仔细想想确实是可行的。在这篇文章中，我想和大家分享我们是如何一步步构建这样一个能够"自我编程"的 Agent 的历程。
我们的目标是将Agent模式，打造成一个“师弟”，一个真正能在内部的DevOps系统中，能帮得上忙的AI助手。
改造传统 JSON + 组装调用方式，基于Py4j，实现"Code+泛化调用"机制，显著提升工具调用的灵活性和执行效率；
采用 Spring Boot 技术栈构建后端架构，整合 Spring AI 生态及 Spring AI Alibaba 能力完成模型接入；
通过 内部评测平台 和 内部观测平台 实现全链路评测与观测；
底层工具采用 MCP 协议实现业务能力补充；
基于 A2A 协议实现 Multi Agent 架构，高效对接各子 Agent；
翻译/数据提取任务：Qwen3-Turbo（低延迟优先）；
思考/动态代码生成：Qwen3-Coder（强化代码能力）；
通用场景：按需调用各个平台提供的Qwen、DeepSeek等模型 （Agent内部模块分布）；
（Agent内部模块分布）
Short Term Memory 短期记忆: Session维度的记忆，仅在当前Session内生效；
Sansory Memory 感知记忆: 通过悬浮球，捕捉的页面、url等环境感知记忆；
Experience 经验: 来自配置、总结的经验，主要用于指导Agent各个环节的内容生成；
Round “轮”: 在复杂任务执行时，每轮会作为一个单独的Segment用作当前轮次的执行总结和后续轮次的目标定义；
Express 表达: Agent返回给用户的内容；
Thought 思考: Agent在每一步执行时的思考内容；
Code 代码: 代码也会作为一个段落，出现在Prompt中；
其他: 如果后续有其他的环节，将作为新的Segment加入到User Prompt中；
公众号后台回复【核心Coding驱动逻辑】查看清晰大图
在我们的Agent中，Segment采用 "[Segment]: [Content]" 的结构，通过组合不同的Segment来形成Prompt，从而实现CoT（Chain of Thought）推理。
除了"外界"工具，我们还为Agent提供了"系统"工具，使其能够获取和控制自身能力。这些能力包括：检查已发起的任务、查询掌握的技能、主动休眠、主动与用户对话、通过大模型进行深度思考，以及利用大模型解析数据等。
在实现上，每个工具箱都被设计为Python的一个Class，其中的各项工具则作为函数实现。我们将不同的描述和属性都相应地映射为Python中的各种定义。
由此，我们打造出了一个"自我编程"驱动的Agent。在运行时，它不仅能够调用外部能力，还可以充分利用Python的原生功能保障数据的确定性，如字符串运算、数字运算、时间运算等。更重要的是，它能够实现自我控制，可以发起复杂任务，并对自身能力进行检查评估。
（PS：除了我们的“人类程序员”外，AI在这次迭代功不可没，凭感觉大概有50-60%的无修改代码，来自AI编写，尤其是《代码驱动》环节，几乎有80%的代码来自AI编写）
Agent
在我们的系统中，一个Agent是一个线程。在Agent运行过程中，将会在线程池中，同时运行各个Area和Act。其生命周期如下图所示：
Area —— 功能区介绍
Area的最初设计，是来自1.0向2.0演进时，创造出来的概念。其设计理念来源于人类的大脑分区，我们将Agent的逻辑区域分成了：感知区、认知区、表达区、自我评估区、运动区，将不同种类的Act收纳到Area中，让整个架构体系看着更加的清晰，也让相同能力的动作，可以具备相互沟通的可能。
各功能区关系和详细介绍
（1）感知区
主要负责接收外部信息，包括但不限于：用户发送的消息、用户点击的卡片事件、子Agent的异步返回结果等。在接收到消息后，感知区还会调用内部的Act，对数据进行系列处理、评估：
用户主语言解析
模糊化解析
场景分析
用户问题的增强
解析环境感知的数据
解析附件的数据
针对不同搜索场景的
（2）认知区
当感知区完成系列解析后，会将解析数据，传递到认知区，由认知区的IntentPlanner来使用Segment机制，处理用户需求并生成对应代码。生成代码后，提交给Python执行引擎，进行执行。
IntentPlanner├──SegmentBuilder(成员变量)│├──List<InferencePromptNewBuilder>promptBuilders│├──InferencePromptConfigManager(prompt配置管理)│├──build(type,segments,context,config)->InferenceSegment│└──路由到具体的PromptBuilder│└──PromptBuilder实现类├──BaseInferencePromptBuilder(抽象父类)│└──使用InferencePromptConfigManager获取配置化prompt├──ThoughtPromptBuilder├──CmdPromptBuilder└──其他自定义PromptBuilder
[Act] IntentPlanner 核心思想
用户输入后，仅执行一轮逻辑；
若存在复杂任务，则将任务移交给运动区处理；
（3）运动区(高级认知区)
在当前Agent系统中，运动区作为一种高级认知区，将会承担复杂任务。当认知区的无法处理的任务被提交过来后。运动区将会发起一个内部循环，来使用Segment的机制，逐步完成任务。
[Act] TaskExecutor 核心思想
Round1Segments:[User,Context,Thought1,Plan1,Cmd1,Evaluation1,NextGoal1]Round2Segments:[User,Context,Thought1,Plan1,Cmd1,Evaluation1,NextGoal1,Thought2,Plan2,Cmd2,Evaluation2,NextGoal2]Round3Segments:[所有历史Segments+Thought3,Plan3,Cmd3,Evaluation3,NextGoal3]
（4）表达区
表达区负责将内部信息传递给外部，包括但不限于：发送给用户的话、发送给用户的卡片、发送给用户的系列事件。
（5）自我评估区
当IntentPlanner、TaskExecutor，执行完初始目标后。将触发自我评估区的SelfTaskCheck评估任务完成情况。如果发现任务失败，或是能执行的，那么将重新触发回来源。
Context Engineering 上下文工程
在Agent中，上下文和Prompt体系是整个Agent决策的核心组件。该体系通过Segment机制统一管理不同类型的Prompt构建过程，实现了配置化、模块化的上下文组装和Prompt生成机制。
在Prompt和上下文拼装的过程，主要代码结构和逻辑如下图所示：
Context上下文组成
1. Segments
Segments : 来自历史轮次的所有Segment集合；
作用 : 为Agent提供长期记忆和上下文连续性；
内容 : 包含用户输入、思考过程、执行代码、结果反馈等完整历史；
成功案例 : 基于历史成功案例的工具使用经验；
失败总结 : 从历史失败中提取的经验教训；
最佳实践 : 经过验证的代码模式和调用方式；
动态知识检索 : 基于用户查询的实时知识获取；
领域知识注入 : 特定场景下的专业知识补充；
上下文关联 : 与当前任务相关的背景知识；
2. 环境上下文
ToolkitContext : 包含会话ID、追踪ID、租户信息、执行过程的变量存储等执行环境；
SegmentBuildConfig : 包含模型配置、功能开关、知识增强设置等；
Agent状态 : 当前Agent的内部状态和能力配置；
3. 工具上下文
Prompt组成架构
Prompt示例
为了更好地理解我们的Prompt设计，这里展示一个基于Prompt拼接思路编写的案例：
（1）System Prompt示例
## 平台介绍你是一个Agent，专注于阿里巴巴DevOps平台的智能助手，能够操作DevOps的相关平台。
## 角色定义你是一个专业的DevOps智能助手，具备代码生成、工具调用、任务执行等核心能力。
## 工作机制基于用户输入和上下文信息，通过思考-执行-评估的循环模式完成任务。
## 输入格式说明用户输入可能包含自然语言描述、页面截图、URL信息等多模态内容。
## 输出格式要求代码将以Fill-in-Middle(FIM)格式提供,包含三个部分:- <|fim_prefix|> 前缀代码 <|fim_suffix|> 后缀代码 <|fim_middle|> 你需要在 <|fim_middle|> 处续写代码,使前缀代码和后缀代码能够正确连接并执行。 注意:- 仅在 <|fim_middle|> 处续写代码- 确保续写的代码与前后文逻辑连贯- 不要修改或重复前缀和后缀中的代码
## 可用工具classexample_toolkit: defget_project_info(project_id): """获取项目基本信息""" pass defsearch_requirements(project_id, query): """搜索需求信息""" pass defcreate_requirement(project_id, title, description): """创建新需求""" pass
classnormandy_toolkit: defget_app_list(project_id): """获取应用列表""" pass defdeploy_app(app_id, version): """部署应用""" pass defget_deploy_status(deploy_id): """获取部署状态""" pass
## 重要原则1.严格按照FIM格式输出代码2.确保代码的安全性和正确性3.优先使用提供的工具包完成任务4.对于不确定的操作要进行二次确认
## 补充的增强知识（在后台配置的一些知识点，比如DevOps各个子系统间的关系、变更和分支的关系等）%s
## 历史经验（自动学习+后台配置的一些代码示例，基于知识库团队提供的检索能力进行相关性召回）%s
（2）User Prompt示例
User: 帮我查询项目123的需求信息，关键词是"登录功能"Context: 当前页面URL为https://example.com/project/123，用户正在查看项目概览页面Thought: 用户想要查询项目123中关于"登录功能"的需求信息。我需要使用example_toolkit的search_requirements方法来完成这个任务。Python:<|fim_prefix|># 查询项目需求信息project_id ="123"query ="登录功能"
try: <|fim_suffix|>exceptExceptionase: print(f"查询过程中发生错误:{str(e)}")<|fim_middle|>
期望返回结果：
#调用工具查询需求result=example_toolkit.search_requirements(id=123,keyword="登录功能")#处理查询结果ifresultandresult.get('success'):requirements=result.get('data',[])ifrequirements:print(f"找到{len(requirements)}个相关需求:")forreqinrequirements:print(f"-{req.get('title')}:{req.get('description')}")else:print("未找到相关需求信息")else:print("查询失败，请检查项目ID或网络连接")System Prompt 结构
我们采用配置化 + 动态化的系统提示词设计，主要包含以下模块：
1. 基础配置
## 平台介绍基于OpsInferencePrompt配置的平台能力介绍
## 角色定义Agent的角色定位和核心职责描述
## 工作机制Agent的工作流程和决策机制说明
2. 规范相关
## 输入格式说明用户输入的解析规则和格式要求
## 输出格式要求不同PromptBuilder的专属输出格式定义- ThoughtPromptBuilder: 思考过程的结构化输出- CmdPromptBuilder: FIM格式的代码续写规范
3. 能力增强
## 系统基础Agent的基础能力和限制说明
## 可用工具动态生成的工具包描述和使用方法-Python语义化模板设计-泛化调用接口说明-工具调用示例
4. 经验
## 使用经验基于历史成功案例的少样本示例
## 重要原则核心的执行原则和安全约束
## 常见错误常见问题的预防和处理方案
User Prompt 结构
1. Segment List
用户提示词主要由Segment序列组成，按时间顺序排列：
UserSegment:用户的原始输入ContextSegment:环境感知数据（页面信息、URL等）ThoughtSegment:Agent的思考过程CommandSegment:生成的执行代码EvaluationSegment:执行结果评估NextGoalSegment:下一步目标规划...
2. FIM格式 (Fill-In-Middle)
我们使用FIM格式进行代码续写。FIM技术基于论文"Efficient Training of Language Models to Fill in the Middle"[ https://arxiv.org/abs/2207.14255 ]，是一种专门针对代码生成优化的技术：
代码将以Fill-in-Middle(FIM)格式提供,包含三个部分:-<|fim_prefix|>前缀代码<|fim_suffix|>后缀代码<|fim_middle|>你需要在<|fim_middle|>处续写代码,使前缀代码和后缀代码能够正确连接并执行。注意:-仅在<|fim_middle|>处续写代码-确保续写的代码与前后文逻辑连贯-不要修改或重复前缀和后缀中的代码
FIM技术的核心优势 ：
上下文感知 : 模型能够同时理解前缀和后缀代码的语义；
精准填充 : 专门训练用于中间代码片段的生成，而非从头编写；
逻辑连贯 : 确保生成的代码能够与前后文完美衔接；
FIM格式的实际结构：
<|fim_prefix|>#已有上下文和代码#包含函数定义、变量声明等前置逻辑<|fim_suffix|>#后续期望的代码结构#包含返回值处理、异常处理等后置逻辑<|fim_middle|>#LLM需要在此处填充代码#生成连接前后文的核心业务逻辑
在Agent中的应用场景 ：
记忆系统是构建真正智能Agent的关键组件。正如人类认知系统依赖于复杂的记忆机制来学习、推理和决策，AI Agent也需要类似的记忆架构来：
Agent在处理复杂任务时，主要依赖于上下文窗口来维持对话状态和任务记忆，这种方式存在明显的局限性：
1. 上下文长度限制 ：上下文窗口有固定的token限制，无法处理超长的历史信息；
2. 记忆组织缺失 ：简单的上下文拼接无法有效组织和检索历史信息；
3. 知识更新困难 ：静态的上下文无法动态更新和优化已有知识；
4. 计算成本高昂 ：长上下文处理需要大量的计算资源；
为了解决这些问题，需要在Agent工程侧开发各种Agent记忆系统，旨在为AI Agent提供持久化、结构化、可检索的记忆能力，它记录了Agent过往的所见所闻和互动历程。
按照存储时间的记忆分类法最早是在 1968 年发布的 Atkinson-Shiffrin Memory Model 中提出，将记忆分为感知记忆（Sensory Memory）、短期记忆（Short-term Memory）和长期记忆（Long-term Memory）。
感知记忆存储了人脑从环境中捕获的信息，例如声音、视觉等信息，在感知记忆区这类信息只能保留很短的时间；
短期记忆存储人脑在思考过程中所需要处理的信息，也被称为工作记忆（在 1974 年 Baddeley & Hitch 模型中提出），通常也只能保留很短的时间；
长期记忆是指Agent中存储时间较长的信息，它类似于人类大脑中的记忆，能够保留大量的数据和经验，并且可以存储很长时间，甚至是永久性的。
长期记忆和短期记忆在Agent中是相互补充的。短期记忆可以快速访问和处理当前需要的信息，而长期记忆则提供了丰富的背景知识和历史数据。Agent需要将短期记忆中的信息与长期记忆中的知识结合起来，以实现更智能的行为和决策。
┌─────────────────────────────────────────────────────────────┐│记忆分层├─────────────────────────────────────────────────────────────┤│感知记忆-标签页维度├─────────────────────────────────────────────────────────────┤│短期记忆-会话纬度│├─会话记忆|├─实体记忆│└─工作记忆├─────────────────────────────────────────────────────────────┤│长期记忆│├─用户偏好(业务实体记忆,...)-用户纬度│├─历史会话(历史会话记忆总结)│├─用户画像(角色定位、技能标签、工作习惯)|├─平台知识│└─经验└─────────────────────────────────────────────────────────────┘
鱼的记忆只有 7 秒，实际上人也有非常多的记忆过目就忘，但不管怎样，这个记忆始终存在过。
环境感知记忆是最短期的记忆，只在当下这一瞬间有效的数据，不具有长期价值。
使用场景
在答疑场景中，用户打开对话时，大概率是遇到了问题，需要寻找对应的解决方案。这个时候需要用户编写一些文字向 Agent 说明在哪个页面进行什么操作时，遇到了什么问题。如果 Agent 能有一双眼睛，跟用户一样看着当前的页面，那么或许就能够提前帮用户预输入当前的上下文，减少用户的使用成本。
在Agent中，我们设计了基于Session级别的短期记忆存储，基于ES实现。在短期记忆中，会话、实体、工作记忆均被设计统一的Segment格式存储，为Agent提供上下文连续性。
用户对话→内部产生Segment→短期记忆存储→下轮对话时检索→提供上下文
记忆消息类型
1. 段落记忆消息
存储推理段落信息，是Agent执行过程的核心记忆载体。
数据结构 :
classSegmentMemoryMessageextendsShortTerm3MemoryMessage{InferenceSegmentsegment;//推理段落内容(Thought/Command/Evaluation等)StringexecId;//所属执行ID，标识当前轮次List<String>parentExecId;//父节点执行ID列表，支持执行链追溯}2. 实体记忆消息
存储结构化实体信息，用于记录关键对象和状态。
数据结构 :
classEntity3MemoryMessageextendsShortTerm3MemoryMessage{Stringtitle;//实体标题/名称Objectdata;//实体数据内容(可为任意对象)}使用场景 :
3. 基础消息类型
所有短期记忆消息的基类，提供通用属性。
数据结构 :
abstractclassShortTerm3MemoryMessage{Stringuuid;//唯一标识符，用于更新和删除操作StringsessionId;//会话ID，Session级别隔离List<String>tags;//标签列表，支持多维度分类Longtimestamp;//创建时间戳，用于时序管理LongsortValue;//排序值，控制记忆优先级}知识点
知识点目标是将内部积累的研发经验和专业知识系统化。特别是在与MCP系统集成后，将能够模拟开发人员的问题解决思路，提供更加专业和精准的支持。
知识点的内容，需要主要覆盖几个关键领域：
除了正面的知识注入，系统还包含了约束性知识，例如平台使用的注意事项、特定场景下的最佳实践以及常见问题的标准处理流程。这些知识将直接影响Agent的响应策略和问题处理方式。
值得注意的是，这些新增的知识点与知识库的区别 ：
代码执行经验
这里描述的是接下来将推出的形态，在目前版本中，大模型投票机制还没有，记忆的存储与检索目前只是在向量数据库中，知识图谱方案还在对接中。
在Agent每轮逻辑执行完成后，本轮执行的细节将会被记录到经验记录表中。经过人工审核+大模型投票机制，会将记忆录入到知识库团队提供的经验图谱进行存储。
在Agent每次使用大模型生成代码时，将会从知识图谱中检索到对应的经验，随后拼接到Prompt中的固定位置。
用户偏好记忆
通过环境感知，根据用户页面访问情况，实时动态上报业务实体操作，作为业务实体记忆上下文。
Memory部分，接收环境感知上报的数据，进而转换成业务实体记忆存储(BizEntityMemroy),BizEntityMemroy主要组成部分:
历史会话记忆
用户通过助手进行会话时，由Agent规划模块进行意图识别，并规划Task。在规划Task执行完成时，对会话记忆进行总结。
HistoryChatMemory(历史会话总结记忆)存储结构：
{"time":"2025-09-1817:14:00""question_type":"操作实施","keys":"应用名:example","summary":"用户在明天(2025-09-1814:00:00)有一个example的发布计划","userId":""}历史会话记忆检索，通过全文向量融合查询，召回会话记忆：
记忆淘汰策略：
在 Agent 开发的早期，我们用业界必选的Agent实现方式，走了LLM返回"JSON " + "固定文本前缀"的路。这看起来是最直观的选择，我们的Agent 1.0 和 2.0 版本都是这么实现的。
但随着项目深入，作为一个重工具调用的Agent，频繁调用Mcp、Agent的问题接踵而至：
数据格式虽然可以保证，但是内容质量并不能保证；
Token 超长导致的性能下降；
JSON 格式不够稳定；
多轮对话既要保证灵活性又要保证速度；
无论是对接 Mcp 还是 A2A，想要又快又准确地调用各种能力，都面临着重重困难。我们也在不断借鉴业界各领域的优秀实践，从 mem0 到 JManus，但始终觉得差点意思。为了提高任务成功率，我们牺牲了响应速度；为了提升速度，我们又不得不降低灵活性；而灵活性的降低，恰恰又导致了任务成功率的下降。这似乎成了一个难解的死循环。
2.0 版本虽然是对 1.0 的全面重构，但经过一段时间的实践，我们发现它在执行逻辑时总是一条路走到黑，一旦开始节点错了，就很难再纠正回来。正当我们为此困扰时，一次偶然的发现给了我们启发：在研究 Github Copilot Agent 时，我们注意到它使用 JavaScript 来定义工具。虽然它最终还是用 JSON 来调用，但这个设计却让我们灵光一现 —— 为什么不让 Agent 直接通过编写代码来实现自己的逻辑呢？
在Agent中，代码与执行部分是整个系统的核心执行引擎。它实现了从代码生成到执行再到结果反馈的完整闭环，让Agent真正具备了"自我编程"的能力。
Python Execution Engine [Java]
PythonExecutionEngine作为整个代码执行的引擎，设计上采用了"线程池+异步执行+监控"的架构模式。本质上就是用Java发起Python，让Python执行代码，调用工具时回调Java，同时Java负责调度和监控。
核心设计思想：
异步执行 : 每个Python脚本都在独立线程中运行，避免阻塞主流程；
生命周期管理 : 从执行ID生成到结果回收，全程可追踪；
超时控制 : 防止Python脚本死循环，默认3600秒超时；
资源隔离 : 每个执行都有独立的上下文环境；
脚本执行流程
执行流程：
1. 准备阶段 : Agent把生成的Python代码传递给PythonExecutionEngine；
2. 初始化 : 分配执行ID，设置上下文，注册工具包；
3. 执行 : 启动Python进程，加载toolkit_bridge.py；
4. 监控 : ExecutionMonitor实时跟踪执行状态；
5. 收尾 : 收集结果，清理资源，反馈给Agent；
代码执行的核心逻辑在PythonScriptExecutor中，它负责：
安全与监控
Toolkit Bridge [Python]
Toolkit Bridge是整个Python和Java沟通的桥梁，可以说是这套架构中最关键的一环。它解决了"
ython怎么调用Java工具包"这个核心问题。
Py4j桥接机制
我们用Py4j来实现Python和Java的双向通信。简单来说，Java实现一个Py4j的Gateway Server，Python对接到这个Server中，就能互相调用了。
关键设计点：
单例Gateway : 全局只维护一个Gateway连接，避免重复连接开销；
连接池化 : Gateway连接失败时自动重试，保证连接的稳定性；
端口固定 : 默认使用15333端口，避免端口冲突；
会话上下文管理
SessionContext解决了"ython代码怎么知道当前是哪个用户、哪个会话"的问题：
classSessionContext:def__init__(self):self._data={}self._toolkit_context=Nonedefset_data(self,key,value):"""设置会话数据，如session_id、trace_id等"""self._data[key]=value每次Python脚本执行前，Java会把session_id、trace_id、用户信息等存储到SessionContext里，这样Python代码调用工具包时就知道自己代表哪个用户在执行了。
异步调用支持
PythonToolkitProxy这个类是我们的核心调用逻辑，他提供一个动态代理入口，它让Python代码可以像调用本地函数一样调用Java工具包：
classPythonToolkitProxy:def__init__(self,toolkit_name):self.toolkit_name=toolkit_namedef__getattr__(self,operation_name):asyncdefasync_operation_method(*args,**kwargs):returnawaitcall_toolkit_async(self.toolkit_name,operation_name,kwargs)returnasync_operation_method
这样，Python代码就能这么写：
#这样调用就行了，简单直观result=awaitexample_toolkit.get_project_info(project_id="123")
就可以调用到在Java中的代码了：
publicclassExampleToolkit{publicObjectget_project_info(StringprojectId){returnnull;}}运行参数捕捉机制
参数处理这块我们踩了不少坑。最开始位置参数和命名参数混用会出问题，后来做了参数规范化：
1. 捕获运行参数 ：使用装饰器，标记在对应的函数上，那么就能获取到函数中的临时变量了；
2. 参数统一 : 优先使用命名参数，位置参数自动转换；
3. 类型转换 : DynamicEntity等Java对象自动转换为Python字典；
4. 序列化 : 所有参数最终都序列化为JSON传递给Java端；
defcapture_execution_variables_async(): """装饰器：捕获异步Python函数执行时的局部变量""" defdecorator(func): @functools.wraps(func) asyncdefwrapper(*args, **kwargs): captured = {} deftracer(frame, event, arg): ifevent =='return'andframe.f_code == func.__code__: try: # 复制局部变量，过滤掉内部变量 forkey, valueinframe.f_locals.items(): ifnot key.startswith('_')andkeynotin['args','kwargs']: # 检查值是否可序列化 try: json.dumps(value, default=str, ensure_ascii=False, cls=DynamicEntityJSONEncoder) captured[key] = value except(TypeError, ValueError): # 对于不可序列化的对象，转换为字符串 captured[key] =str(value) exceptExceptionase: print(f"ExecutionVariableMonitor capture error:{e}") returntracer
sys.settrace(tracer) try: result =awaitfunc(*args, **kwargs) finally: sys.settrace(None)
# 保存变量到全局context中供Java侧获取 ifhasattr(sys.modules[__name__],'captured_variables'): sys.modules[__name__].captured_variables.update(captured) else: sys.modules[__name__].captured_variables = captured.copy()
# 输出捕获的变量，使用特殊格式供Java端解析 forkey, valueincaptured.items(): print(f"VARIABLE_CAPTURED:{key}={json.dumps(value, default=str, ensure_ascii=False, cls=DynamicEntityJSONEncoder)}")
returnresult returnwrapper returndecorator
通过注解捕捉到运行参数后，会在完成运行后，由java解析，并存储到redis里面。当下次执行的时候，会从redis取出会话中的参数。以实现在下轮对话中，可以感知到上轮对话的变量及内容。
# 第一轮对话
defmain(): a =1
# 第二轮对话a =1# 通过redis回放回来的参数
defmain(): print(a+1)
Toolkit Mapper [Java]
ToolkitMapper是整个工具包体系的调度中心，它负责把Python的调用请求路由到具体的Java工具包实现。
工具包映射与路由
核心路由逻辑很直接：根据toolkit_name找到对应的实现类，然后调用对应的operation方法。但实际实现中有几个关键点：
动态路由 : 通过sessionId找到对应的Agent3实例，再通过Agent的AgentToolkitManager来执行具体操作；
类型适配 : 不同类型的工具包有不同的接口，ToolkitMapper负责做适配；
结果包装 : 所有返回结果都通过ResultWrapper进行统一包装；
数据传递机制
为了实现让历史Python运行的临时参数，可以被传递到下次运行Python的过程中，我们在数据传递过程中，在Java内部通过Base64将原始数据反编译，然后使用参数，传递到python脚本中。Python脚本拿到Base64之后，自行解码，将数据在内存恢复到目标参数中。
方法调用机制
我们在Agent、Mcp的Toolkit中，将技能/工具映射成方法，Agent/McpServer映射成Class。每个Agent、McpServer都对应一个独立的Toolkit。
因此当某个Toolkit被调用时，将会拿到自身的class、方法名，从而找到对应的技能/工具，进行泛化调用。
Toolkit体系是整个Agent能力的具体体现，它把抽象的"智能助手"落地为可执行的工具包。我们设计了四大类工具包，每类都有自己的特色和应用场景。
Custom Card Toolkit
自定义卡片工具包是我们为了解决"Agent怎么和用户交互"这个问题而设计的。传统的文本对话太单调，我们需要更丰富的交互形式。
卡片组件系统
卡片系统采用了组件化的设计思路，每个卡片都是一个独立的UI组件：
支持的卡片类型：
Mcp Toolkit
Mcp（Model Context Protocol）Toolkit是我们对接外部服务的标准化接口。通过Mcp协议，我们可以快速集成各种外部能力，而不需要为每个服务单独开发适配器。
Agent Toolkit
Agent Toolkit实现了Agent之间的协作机制。在复杂任务场景下，单个Agent可能无法独立完成所有工作，需要和其他专业Agent协作。
A2A协议支持
A2A（Agent to Agent）协议定义了Agent间交互的标准格式：
任务分发 : 主Agent将复杂任务分解后分发给子Agent；
进度汇报 : 子Agent定期汇报任务执行进度；
异常处理 : 子Agent执行失败时的异常上报机制；
资源协调 : 多个Agent竞争同一资源时的协调机制；
工具包注册与管理
工具包的注册与管理是整个Toolkit体系的基础设施，它支持多种注册方式和管理机制。我们设计了两套并行的注册体系：基于接口的动态工具包和基于注解的声明式工具包，它们各有适用场景，互不耦合。
动态工具包注册
动态工具包是我们的核心注册机制，通过实现DynamicToolkit接口来定义工具包：
publicinterfaceDynamicToolkit{Stringname();//工具包名称StringgetClassComment();//工具包描述Map<String,String>getMethodPython();//Python方法定义Map<String,Type[]>getMethods();//方法参数类型Map<String,String[]>getParameterNames();//参数名称Objectexecute(StringmethodName,StringexecId,Map<String,Object>params);}接口驱动 : 所有动态工具包都实现DynamicToolkit接口，保证接口的一致性；
运行时注册 : 工具包可以在运行时动态注册和卸载，支持热插拔；
元数据自描述 : 工具包自己描述自己的能力和接口，无需外部配置；
典型的动态工具包实现：
@ComponentpublicclassExampleDynamicToolkitimplementsDynamicToolkit{@OverridepublicStringname(){return"example_toolkit";}@OverridepublicObjectexecute(StringmethodName,StringexecId,Map<String,Object>params){//动态分发到具体方法switch(methodName){case"get_project_info":returngetProjectInfo(params);//其他方法...}}}注解式工具包注册
注解式注册是一种声明式的工具包定义方式，适合结构相对固定的工具包：
@ToolkitComponent(python="system_toolkit",description="系统级工具包，提供基础的系统操作能力")publicclassSystemToolkit{@ToolkitOperation(python="send_message")publicToolkitResultsendMessage(Map<String,Object>params){//发送消息的具体实现}@ToolkitOperation(python="get_current_time",enabled=true)publicToolkitResultgetCurrentTime(Map<String,Object>params){//获取当前时间的具体实现}}注册机制分离设计
两种注册机制在实现上完全分离，各自有独立的处理流程：
独立注册表 : DynamicToolkitRegistry和AnnotationToolkitRegistry分别管理两类工具包；
统一访问 : ToolkitMapper提供统一的访问接口，屏蔽底层注册机制的差异；
互不干扰 : 两种机制可以独立开启或关闭，不会相互影响；
经过三轮Agent的升级与优化，关于如何打造优质AI Agent，我结合Agent实践经验总结几点核心要素：
1. Prompt组装与上下文工程的合理设计
上下文管理影响多轮对话的稳定性。
在搭建Agent时，需要对Prompt进行单独的设计，明确Prompt的组成部分、上下文的选择、Agent运行过程的不同形态下，上下文的组装方式等。
推荐的Prompt/上下文开发过程：
可以先准备一段完整的比较粗糙的prompt，其中记忆、经验相关的内容都先使用mock的方式拼接在其中，然后使用LLM的api对prompt的效果进行初步验证；
验证没问题后，可以进入代码实现，将prompt按逻辑和结构拆分成多个部分，例如自我介绍、工作机制、输入格式、输出格式、示例等，然后分别实现每个部分；
后续需要在运行过程中不断调整prompt，可以在每次发现bad case的时候，将目前的prompt、出现的问题和自己的思路发给LLM，让LLM帮助优化；
我们在前两个版本的时候，Prompt组装，是没有系统性、结构性设计的，这也就导致了过程中出现了一个900多行的超级大的Prompt，它里面各个位置的内容都是比较乱的。Prompt和上下文的组装、拼接经过了单独的设计，实现的代码中，对其组装也模板设计模式、Builder设计模式的组合，来完成Prompt的拼接。
2. Agent的工程架构设计也很重要
工程架构直接影响交互体验的流畅度。
工程层面，Agent需要考虑：Agent运行过程如何持久化、优雅上下线、任务的完成与失败如何定义和管理、日志/监控/可观测/评测制度的建立、记忆如何管理。
"模型决定上限，工程决定下限"这种说法就像曾经的"HP是世界上最好的语言"一样片面。实际上二者是相辅相成的关系。有些产品即便采用了Claude这样的强大模型，整体效果反而不如使用Deepseek但工程实现更优秀的同类产品。
关键在于模型能力与工程细节的契合度。在工程层面比如工具调用编排、用户交互设计、内部流程优化等，都需要在工程层面深度打磨，才能充分发挥模型潜力。过分迷信模型能力而"死等模型升级"是不可取的。
3. Agent提高运行质量和稳定性，可以通过让他自我积累、自我学习
经验积累则确保跨会话的一致性。
不论是JSON、文本前缀还是Coding驱动，经验都是一个好东西。它可以大大地提高返回数据的稳定性。这里分享几篇论文：
《ExpeL: LLM Agents Are Experiential Learners》
《How Memory Management Impacts LLM Agents: An Empirical Study of Experience-Following Behavior》
《Get Experience from Practice: LLM Agents with Record & Replay》
简单来说，经验的组装，就是：
在Agent运行过程中，收集一切有用的信息，随后在完成运行后，通过 LLM 或者各种解析逻辑加工成一段文本、一个json，代表本次执行的起因、经过、结果、思考等信息。随后存储到数据库中（不仅局限于向量数据库）。在Agent运行阶段，将用户文本做简单加工，随后进行检索。 只不过在工程层面，检索过后的结果，可以用作“回放”，可以用作“Prompt”拼接。单纯的向量数据库检索，不一定能让经验检索变得准确，我们目前正在向图索引的方向探索，让图谱的能力辅助经验的检索与加工。
目标定位
我们的最终目标是致力于让它成为可靠的"1.5线"答疑助手，具备初级程序员（1-3年）的知识储备和问题解决能力，同时拥有自我进化和持续学习能力。
优化路径
1. 除了调用过程是代码，拼接Prompt能否变得更加动态？甚至在Cmd、Thought阶段的Prompt，都是由Agent自我选择Toolkit拼装的；
2. 在IntentPlanner阶段，并非是不可循环的，我们后续会把IntentPlanner、TaskExecutor的底层能力合并，提供一个通用的Coding驱动Agent模型，基于此模型，实现各层的ReAct操作；
3. 任务间的上下文隔离还需要做的更加精细；
4. 知识点和经验的数据，需要持续保鲜；
5. Mcp和Agent的深度和广度，都需要持续提升；
6. 开发一个桌面应用程序，随时随地可以唤起；
7. 日志、观测、报表、监控、评测机制的的完善
