| # OpenHands Agent System Prompt 架构说明 |
|
|
| ## 🏗️ 整体架构 |
|
|
| ``` |
| ┌─────────────────────────────────────────────────────────────────┐ |
| │ OpenHands Agent │ |
| │ │ |
| │ ┌──────────────────────────────────────────────────────────┐ │ |
| │ │ System Prompt (Jinja2 模板) │ │ |
| │ │ ┌────────────────────────────────────────────────────┐ │ │ |
| │ │ │ <ROLE> Agent 的角色定义 │ │ │ |
| │ │ ├────────────────────────────────────────────────────┤ │ │ |
| │ │ │ <PRINCIPLES> 核心行为原则 │ │ │ |
| │ │ ├────────────────────────────────────────────────────┤ │ │ |
| │ │ │ <WORKFLOW> 工作流程 │ │ │ |
| │ │ ├────────────────────────────────────────────────────┤ │ │ |
| │ │ │ <CONSTRAINTS> 约束条件 │ │ │ |
| │ │ ├────────────────────────────────────────────────────┤ │ │ |
| │ │ │ {% if custom_instructions %} │ │ │ |
| │ │ │ {{ custom_instructions }} ← 变量注入 │ │ │ |
| │ │ │ {% endif %} │ │ │ |
| │ │ └────────────────────────────────────────────────────┘ │ │ |
| │ └──────────────────────────────────────────────────────────┘ │ |
| │ │ |
| │ ┌──────────────────────────────────────────────────────────┐ │ |
| │ │ Tools │ │ |
| │ │ • TerminalTool - 执行命令 │ │ |
| │ │ • FileEditorTool - 编辑文件 │ │ |
| │ │ • TaskTrackerTool - 跟踪任务 │ │ |
| │ └──────────────────────────────────────────────────────────┘ │ |
| │ │ |
| │ ┌──────────────────────────────────────────────────────────┐ │ |
| │ │ LLM │ │ |
| │ │ Model: vertex_ai/gemini-2.5-flash │ │ |
| │ │ API Key: *** │ │ |
| │ └──────────────────────────────────────────────────────────┘ │ |
| └─────────────────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌──────────────────┐ |
| │ Conversation │ |
| │ (对话管理器) │ |
| └──────────────────┘ |
| │ |
| ▼ |
| ┌──────────────────┐ |
| │ Workspace │ |
| │ (工作目录) │ |
| └──────────────────┘ |
| ``` |
|
|
| ## 📊 自定义 System Prompt 的三层架构 |
|
|
| ``` |
| ┌───────────────────────────────────────────────────────────────┐ |
| │ 第 1 层: Agent 初始化参数 │ |
| ├───────────────────────────────────────────────────────────────┤ |
| │ │ |
| │ agent = Agent( │ |
| │ llm=llm, │ |
| │ tools=tools, │ |
| │ system_prompt_filename="custom.j2", ← 指定模板文件 │ |
| │ system_prompt_kwargs={...} ← 传递变量 │ |
| │ ) │ |
| │ │ |
| └───────────────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌───────────────────────────────────────────────────────────────┐ |
| │ 第 2 层: Jinja2 模板文件 (custom.j2) │ |
| ├───────────────────────────────────────────────────────────────┤ |
| │ │ |
| │ You are an AI agent... │ |
| │ │ |
| │ <ROLE> │ |
| │ * Your primary role is... │ |
| │ </ROLE> │ |
| │ │ |
| │ {% if custom_instructions %} ← 条件判断 │ |
| │ <CUSTOM> │ |
| │ {{ custom_instructions }} ← 变量引用 │ |
| │ </CUSTOM> │ |
| │ {% endif %} │ |
| │ │ |
| │ {% if project_name %} │ |
| │ <CONTEXT> │ |
| │ Project: {{ project_name }} │ |
| │ Task: {{ task_type }} │ |
| │ </CONTEXT> │ |
| │ {% endif %} │ |
| │ │ |
| └───────────────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌───────────────────────────────────────────────────────────────┐ |
| │ 第 3 层: 渲染后的最终 Prompt (发送给 LLM) │ |
| ├───────────────────────────────────────────────────────────────┤ |
| │ │ |
| │ You are an AI agent... │ |
| │ │ |
| │ <ROLE> │ |
| │ * Your primary role is... │ |
| │ </ROLE> │ |
| │ │ |
| │ <CUSTOM> │ |
| │ Focus on code evolution and optimization... │ |
| │ </CUSTOM> │ |
| │ │ |
| │ <CONTEXT> │ |
| │ Project: ShinkaEvolve │ |
| │ Task: Code Evolution │ |
| │ </CONTEXT> │ |
| │ │ |
| └───────────────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| 发送给 LLM 执行 |
| ``` |
|
|
| ## 🔄 数据流程图 |
|
|
| ``` |
| ┌─────────────────┐ |
| │ User Message │ "请优化这段代码" |
| └────────┬────────┘ |
| │ |
| ▼ |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ Conversation │ |
| │ • 管理对话历史 │ |
| │ • 格式化用户消息 │ |
| └────────┬────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ Agent │ |
| │ ┌─────────────────────────────────────────────────────┐ │ |
| │ │ System Prompt (自定义的演化 prompt) │ │ |
| │ ├─────────────────────────────────────────────────────┤ │ |
| │ │ User Message: "请优化这段代码" │ │ |
| │ ├─────────────────────────────────────────────────────┤ │ |
| │ │ Conversation History: [...] │ │ |
| │ └─────────────────────────────────────────────────────┘ │ |
| └────────┬────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ LLM │ |
| │ • 理解指令和上下文 │ |
| │ • 生成响应 │ |
| │ • 决定使用哪些工具 │ |
| └────────┬────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ Tool Execution │ |
| │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ |
| │ │ TerminalTool │ │FileEditorTool│ │TaskTracker │ │ |
| │ ├──────────────┤ ├──────────────┤ ├──────────────┤ │ |
| │ │ 运行测试 │ │ 修改代码 │ │ 创建任务 │ │ |
| │ │ 检查性能 │ │ 保存文件 │ │ 更新状态 │ │ |
| │ └──────────────┘ └──────────────┘ └──────────────┘ │ |
| └────────┬────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ Tool Results │ |
| │ • 命令输出 │ |
| │ • 文件修改确认 │ |
| │ • 任务状态 │ |
| └────────┬────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ LLM (再次处理) │ |
| │ • 分析工具执行结果 │ |
| │ • 生成最终响应 │ |
| │ • 或决定执行更多工具 │ |
| └────────┬────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────┐ |
| │ User Response │ "代码已优化，性能提升 20%" |
| └─────────────────┘ |
| ``` |
|
|
| ## 🎯 四种自定义方法对比 |
|
|
| ``` |
| ┌─────────────────────────────────────────────────────────────────────────┐ |
| │ 方法 1: 默认 Prompt │ |
| ├─────────────────────────────────────────────────────────────────────────┤ |
| │ │ |
| │ Agent(llm, tools) │ |
| │ │ │ |
| │ ├─→ 自动使用 system_prompt.j2 │ |
| │ └─→ 通用指令，适用于大多数任务 │ |
| │ │ |
| │ ✓ 最简单 │ |
| │ ✗ 无法自定义 │ |
| └─────────────────────────────────────────────────────────────────────────┘ |
| |
| ┌─────────────────────────────────────────────────────────────────────────┐ |
| │ 方法 2: 选择内置模板 │ |
| ├─────────────────────────────────────────────────────────────────────────┤ |
| │ │ |
| │ Agent( │ |
| │ llm, tools, │ |
| │ system_prompt_filename="system_prompt_planning.j2" │ |
| │ ) │ |
| │ │ │ |
| │ ├─→ 使用 OpenHands 预定义的模板 │ |
| │ └─→ 针对特定任务类型优化（规划/交互/长期任务等） │ |
| │ │ |
| │ ✓ 简单，无需自己写 prompt │ |
| │ ✗ 选择有限（只有 5-6 个模板） │ |
| └─────────────────────────────────────────────────────────────────────────┘ |
| |
| ┌─────────────────────────────────────────────────────────────────────────┐ |
| │ 方法 3: 自定义模板 + 变量注入 (推荐) │ |
| ├─────────────────────────────────────────────────────────────────────────┤ |
| │ │ |
| │ Agent( │ |
| │ llm, tools, │ |
| │ system_prompt_filename="custom_evolution_prompt.j2", │ |
| │ system_prompt_kwargs={ │ |
| │ "custom_instructions": "...", │ |
| │ "project_name": "ShinkaEvolve", │ |
| │ "task_type": "Code Evolution", │ |
| │ } │ |
| │ ) │ |
| │ │ │ |
| │ ├─→ 使用自定义模板文件 │ |
| │ ├─→ 动态注入任务特定信息 │ |
| │ └─→ 灵活适应不同场景 │ |
| │ │ |
| │ ✓ 高度灵活 │ |
| │ ✓ 可重用模板 │ |
| │ ✓ 动态配置 │ |
| │ ✗ 需要维护模板文件 │ |
| └─────────────────────────────────────────────────────────────────────────┘ |
| |
| ┌─────────────────────────────────────────────────────────────────────────┐ |
| │ 方法 4: 完全自定义模板 │ |
| ├─────────────────────────────────────────────────────────────────────────┤ |
| │ │ |
| │ Agent( │ |
| │ llm, tools, │ |
| │ system_prompt_filename="path/to/fully_custom.j2" │ |
| │ ) │ |
| │ │ │ |
| │ ├─→ 完全从零编写 prompt │ |
| │ ├─→ 针对特定领域深度定制 │ |
| │ └─→ 包含专业领域知识 │ |
| │ │ |
| │ ✓ 最大灵活性 │ |
| │ ✓ 完全控制 │ |
| │ ✗ 需要深入理解 prompt engineering │ |
| │ ✗ 维护成本高 │ |
| └─────────────────────────────────────────────────────────────────────────┘ |
| ``` |
|
|
| ## 🔧 关键 API 参数详解 |
|
|
| ### Agent 类的核心参数 |
|
|
| ```python |
| class Agent: |
| def __init__( |
| self, |
| llm: LLM, # LLM 配置 |
| tools: List[Tool], # 可用工具列表 |
| |
| # System Prompt 相关 |
| system_prompt_filename: str = "system_prompt.j2", |
| system_prompt_kwargs: Dict[str, Any] = {}, |
| |
| # 其他配置 |
| security_policy_filename: str = "security_policy.j2", |
| agent_context: Optional[AgentContext] = None, |
| condenser: Optional[CondenserBase] = None, |
| critic: Optional[CriticBase] = None, |
| |
| # 工具过滤 |
| filter_tools_regex: Optional[str] = None, |
| include_default_tools: List[str] = [], |
| |
| # MCP 配置 |
| mcp_config: Dict[str, Any] = {}, |
| ): |
| ... |
| ``` |
|
|
| ### 参数说明 |
|
|
| | 参数 | 类型 | 默认值 | 说明 | |
| |-----|------|--------|------| |
| | `llm` | `LLM` | 必需 | LLM 配置对象 | |
| | `tools` | `List[Tool]` | 必需 | Agent 可用的工具列表 | |
| | `system_prompt_filename` | `str` | `"system_prompt.j2"` | Prompt 模板文件名或路径 | |
| | `system_prompt_kwargs` | `Dict` | `{}` | 传递给模板的变量字典 | |
| | `security_policy_filename` | `str` | `"security_policy.j2"` | 安全策略模板文件 | |
| | `agent_context` | `AgentContext` | `None` | Agent 上下文信息 | |
| | `condenser` | `CondenserBase` | `None` | 对话压缩器 | |
| | `critic` | `CriticBase` | `None` | 批评者组件 | |
|
|
| ## 🎨 Jinja2 模板语法速查 |
|
|
| ### 基本变量引用 |
|
|
| ```jinja2 |
| {{ variable_name }} # 直接输出变量 |
| {{ project_name }} # 输出: ShinkaEvolve |
| ``` |
|
|
| ### 条件判断 |
|
|
| ```jinja2 |
| {% if custom_instructions %} |
| <CUSTOM> |
| {{ custom_instructions }} |
| </CUSTOM> |
| {% endif %} |
| |
| {% if not use_default %} |
| 使用自定义配置 |
| {% else %} |
| 使用默认配置 |
| {% endif %} |
| ``` |
|
|
| ### 循环 |
|
|
| ```jinja2 |
| {% for tool in available_tools %} |
| - {{ tool.name }}: {{ tool.description }} |
| {% endfor %} |
| ``` |
|
|
| ### 包含其他模板 |
|
|
| ```jinja2 |
| {% include 'security_policy.j2' %} |
| {% include 'self_documentation.j2' %} |
| ``` |
|
|
| ### 注释 |
|
|
| ```jinja2 |
| {# 这是注释，不会出现在最终输出中 #} |
| ``` |
|
|
| ### 过滤器 |
|
|
| ```jinja2 |
| {{ text | upper }} # 转大写 |
| {{ text | trim }} # 去除首尾空白 |
| {{ items | length }} # 获取长度 |
| ``` |
|
|
| ## 📁 文件组织结构 |
|
|
| ``` |
| eval_agent/ |
| │ |
| ├── 📄 openhands_sample.py |
| │ └─→ 基础示例和自定义示例 |
| │ • basic_example() 使用默认 prompt |
| │ • custom_evolution_example() 使用自定义 prompt |
| │ |
| ├── 📄 openhands_custom_prompt_examples.py |
| │ └─→ 详细的方法对比和示例 |
| │ • example_custom_prompt_file() 方法 1 |
| │ • example_with_kwargs() 方法 2 |
| │ • example_builtin_templates() 方法 3 |
| │ • example_with_custom_evolution_prompt() 方法 4 |
| │ • print_comparison() 打印对比 |
| │ |
| ├── 📄 custom_evolution_prompt.j2 |
| │ └─→ 代码演化专用的 system prompt 模板 |
| │ 包含： |
| │ • <ROLE> 角色定义 |
| │ • <CODE_EVOLUTION_PRINCIPLES> 演化原则 |
| │ • <MUTATION_STRATEGIES> 变异策略 |
| │ • <WORKFLOW> 工作流程 |
| │ • 变量注入点 |
| │ |
| ├── 📖 README_CUSTOM_PROMPT.md |
| │ └─→ 完整的使用指南（中文） |
| │ • 基础概念 |
| │ • 四种自定义方法详解 |
| │ • 完整代码示例 |
| │ • 最佳实践 |
| │ • 常见问题 |
| │ |
| ├── 📖 QUICK_START_ZH.md |
| │ └─→ 快速入门指南（中文） |
| │ • 核心要点 |
| │ • 方法对比 |
| │ • 立即可用的示例代码 |
| │ |
| └── 📖 ARCHITECTURE_ZH.md (本文件) |
| └─→ 架构说明和可视化图表 |
| • 整体架构图 |
| • 数据流程图 |
| • API 参数详解 |
| ``` |
|
|
| ## 💼 实际使用场景 |
|
|
| ### 场景 1: 代码优化任务 |
|
|
| ```python |
| agent = Agent( |
| llm=llm, |
| tools=[TerminalTool, FileEditorTool], |
| system_prompt_filename="custom_evolution_prompt.j2", |
| system_prompt_kwargs={ |
| "custom_instructions": "Focus on performance optimization", |
| "task_type": "Performance Optimization", |
| } |
| ) |
| |
| conversation.send_message("Optimize the sorting algorithm in utils.py") |
| ``` |
|
|
| ### 场景 2: Bug 修复任务 |
|
|
| ```python |
| agent = Agent( |
| llm=llm, |
| tools=[TerminalTool, FileEditorTool, TaskTrackerTool], |
| system_prompt_filename="custom_evolution_prompt.j2", |
| system_prompt_kwargs={ |
| "custom_instructions": "Focus on finding and fixing bugs", |
| "task_type": "Bug Fixing", |
| } |
| ) |
| |
| conversation.send_message("Find and fix the memory leak in server.py") |
| ``` |
|
|
| ### 场景 3: 代码重构任务 |
|
|
| ```python |
| agent = Agent( |
| llm=llm, |
| tools=[TerminalTool, FileEditorTool], |
| system_prompt_filename="custom_evolution_prompt.j2", |
| system_prompt_kwargs={ |
| "custom_instructions": "Refactor for better readability and maintainability", |
| "task_type": "Code Refactoring", |
| } |
| ) |
| |
| conversation.send_message("Refactor the authentication module") |
| ``` |
|
|
| ## 🎓 最佳实践总结 |
|
|
| ### ✅ 推荐做法 |
|
|
| 1. **使用方法 3（自定义模板 + 变量注入）** 对于大多数专业任务 |
| 2. **保持模板结构清晰** 使用 `<SECTION>` 标签组织内容 |
| 3. **使用条件块** 让模板更灵活：`{% if variable %}` |
| 4. **提供具体指令** 而不是模糊的描述 |
| 5. **包含示例** 在 prompt 中展示期望的行为 |
| 6. **版本控制** 对 prompt 模板文件进行版本管理 |
| 7. **测试验证** 通过实际任务验证 prompt 的效果 |
|
|
| ### ❌ 避免做法 |
|
|
| 1. **过于冗长** 的 prompt 可能降低效果 |
| 2. **矛盾的指令** 会让 agent 困惑 |
| 3. **硬编码** 任务特定信息（应该用变量注入） |
| 4. **忽略测试** 直接在生产环境使用未验证的 prompt |
| 5. **过度复杂** 的条件逻辑 |
|
|
| ## 🔍 调试技巧 |
|
|
| ### 查看最终 Prompt |
|
|
| ```python |
| agent = Agent(...) |
| print("="*80) |
| print("Final System Prompt:") |
| print("="*80) |
| print(agent.system_message) |
| print("="*80) |
| ``` |
|
|
| ### 验证模板渲染 |
|
|
| ```python |
| from pathlib import Path |
| from jinja2 import Template |
| |
| template_path = Path("custom_evolution_prompt.j2") |
| template = Template(template_path.read_text()) |
| |
| rendered = template.render( |
| custom_instructions="Test instructions", |
| project_name="TestProject" |
| ) |
| |
| print(rendered) |
| ``` |
|
|
| ### 测试 Agent 行为 |
|
|
| ```python |
| # 简单任务测试 |
| conversation.send_message("Describe your role and capabilities") |
| conversation.run() |
| |
| # 检查是否理解特定指令 |
| conversation.send_message("What are your constraints?") |
| conversation.run() |
| ``` |
|
|
| ## 📚 相关资源 |
|
|
| - **完整指南**: `README_CUSTOM_PROMPT.md` |
| - **快速入门**: `QUICK_START_ZH.md` |
| - **代码示例**: `openhands_custom_prompt_examples.py` |
| - **基础示例**: `openhands_sample.py` |
| - **模板文件**: `custom_evolution_prompt.j2` |
|
|
| --- |
|
|
| **创建日期**: 2026-01-29 |
| **版本**: 1.0 |
| **项目**: ShinkaEvolve - OpenHands Integration |
|
|
