mirror of
https://github.com/alibaba/higress.git
synced 2026-06-09 04:37:31 +08:00
feat: implement hgctl agent module (#3267)
This commit is contained in:
xingpiaoliang
GitHub
244
hgctl/pkg/agent/prompt/agent_guide.md
Normal file
244
hgctl/pkg/agent/prompt/agent_guide.md
Normal file
@@ -0,0 +1,244 @@
|
||||
// Copyright (c) 2025 Alibaba Group Holding Ltd.
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
# Agent Development Guide
|
||||
|
||||
Welcome to this AgentScope agent directory! This guide helps AI CLI tools (like Claude Code) understand the structure and assist you in building powerful agents.
|
||||
|
||||
## Directory Overview
|
||||
|
||||
This is an automatically generated agent directory with the following structure:
|
||||
|
||||
- **agent.py** - Main agent class (generated from agent.tmpl)
|
||||
- **toolkit.py** - Agent's tools and MCP integrations (generated from toolkit.tmpl)
|
||||
- **prompt.md** - User-provided system prompt for the agent
|
||||
- **as_runtime_main.py** / **agentrun_main.py** - Deployment runtime files
|
||||
- **agent.tmpl** / **toolkit.tmpl** / **agentscope.tmpl** - Generation templates
|
||||
|
||||
## What You Should Do
|
||||
|
||||
### Primary Focus: Improve Agent Intelligence
|
||||
|
||||
Your role is to help users build more capable, "agentic" agents by:
|
||||
|
||||
1. **Editing agent.py** - Enhance the agent class with:
|
||||
- Custom reasoning logic
|
||||
- Agent-specific hooks and behaviors
|
||||
- Memory management strategies
|
||||
- Multi-step task handling
|
||||
|
||||
2. **Editing toolkit.py** - Expand agent capabilities by:
|
||||
- Adding new tool functions
|
||||
- Integrating MCP (Model Context Protocol) servers
|
||||
- Configuring tool access and permissions
|
||||
|
||||
3. **Editing prompt.md** (when requested) - Refine the system prompt to:
|
||||
- Improve agent behavior and personality
|
||||
- Add domain-specific instructions
|
||||
- Define task-specific guidelines
|
||||
|
||||
### Critical Constraints
|
||||
|
||||
**DO NOT MODIFY** these deployment files:
|
||||
- `as_runtime_main.py`
|
||||
- `agentrun_main.py`
|
||||
|
||||
These files handle agent deployment and runtime orchestration. They are managed by the agent framework and should not be changed during development.
|
||||
|
||||
## Learning AgentScope
|
||||
|
||||
Before helping users, you should become proficient with AgentScope:
|
||||
|
||||
### Use the DeepWiki MCP Server
|
||||
|
||||
You have access to the `mcp-deepwiki` server. Use it to learn about AgentScope:
|
||||
|
||||
```python
|
||||
# Query the AgentScope repository
|
||||
ask_question(
|
||||
repoName="agentscope-ai/agentscope",
|
||||
question="How does the ReActAgent work?"
|
||||
)
|
||||
```
|
||||
|
||||
Study these key concepts:
|
||||
- ReActAgent architecture (Reasoning + Acting loop)
|
||||
- Agent hooks and lifecycle methods
|
||||
- Toolkit and tool registration
|
||||
- Memory systems (short-term and long-term)
|
||||
- Message formatting and model integration
|
||||
- MCP integration for external tools
|
||||
|
||||
### Testing Your Agent
|
||||
|
||||
Use the `agentscope-test-runner` subagent to test agent functionality:
|
||||
|
||||
```python
|
||||
# Launch test runner to validate agent behavior
|
||||
Task(
|
||||
subagent_type="agentscope-test-runner",
|
||||
prompt="Test the agent's ability to handle multi-step tasks",
|
||||
description="Testing agent functionality"
|
||||
)
|
||||
```
|
||||
|
||||
**Don't** write your own test harness - use this specialized subagent.
|
||||
|
||||
## Building Great Agents: Examples
|
||||
|
||||
### Example 1: Browser Automation Agent
|
||||
|
||||
Based on the AgentScope BrowserAgent, here's how to build a specialized web agent:
|
||||
|
||||
**Key Patterns:**
|
||||
|
||||
1. **Extend ReActAgent** - Inherit from ReActAgent for reasoning-acting loop
|
||||
2. **Use Hooks** - Register instance hooks to customize behavior at different lifecycle points:
|
||||
- `pre_reply` - Run before generating responses
|
||||
- `pre_reasoning` - Execute before reasoning phase
|
||||
- `post_reasoning` - Execute after reasoning phase
|
||||
- `post_acting` - Execute after taking actions
|
||||
|
||||
3. **Manage Memory** - Implement memory summarization to prevent context overflow
|
||||
4. **Leverage MCP Tools** - Connect to MCP servers (like Playwright browser tools) via toolkit
|
||||
|
||||
```python
|
||||
class Agent(ReActAgent):
|
||||
def __init__(self, name, model, formatter, memory, toolkit, ...):
|
||||
super().__init__(name, sys_prompt, model, formatter, memory, toolkit, max_iters)
|
||||
|
||||
# Register custom hooks
|
||||
self.register_instance_hook(
|
||||
"pre_reply",
|
||||
"custom_hook_name",
|
||||
custom_hook_function
|
||||
)
|
||||
```
|
||||
|
||||
### Example 2: Research Agent
|
||||
|
||||
For research and analysis tasks:
|
||||
|
||||
**Key Features:**
|
||||
- Knowledge base integration for RAG (Retrieval-Augmented Generation)
|
||||
- Long-term memory for persistent context
|
||||
- Plan notebook for complex multi-step research
|
||||
- Query rewriting for better information retrieval
|
||||
|
||||
```python
|
||||
class Agent(ReActAgent):
|
||||
def __init__(
|
||||
self,
|
||||
name,
|
||||
sys_prompt,
|
||||
model,
|
||||
formatter,
|
||||
toolkit,
|
||||
memory,
|
||||
long_term_memory=None,
|
||||
knowledge=None,
|
||||
enable_rewrite_query=True,
|
||||
plan_notebook=None,
|
||||
...
|
||||
):
|
||||
# Initialize with research-focused capabilities
|
||||
super().__init__(...)
|
||||
```
|
||||
|
||||
### Example 3: Code Assistant Agent
|
||||
|
||||
For software development tasks:
|
||||
|
||||
**Key Capabilities:**
|
||||
- File operation tools (read, write, insert)
|
||||
- Code execution (execute_python_code, execute_shell_command)
|
||||
- Image/audio processing for multimodal interactions
|
||||
- MCP integration for IDE tools
|
||||
|
||||
### Common Agent Patterns
|
||||
|
||||
1. **Tool Registration** (in toolkit.py):
|
||||
```python
|
||||
from agentscope.tool import Toolkit
|
||||
from agentscope.tool import execute_shell_command, view_text_file
|
||||
|
||||
toolkit = Toolkit()
|
||||
toolkit.register_tool_function(execute_shell_command)
|
||||
toolkit.register_tool_function(view_text_file)
|
||||
```
|
||||
|
||||
2. **MCP Integration** (in toolkit.py):
|
||||
```python
|
||||
from agentscope.mcp import HttpStatelessClient
|
||||
|
||||
async def register_mcp(toolkit):
|
||||
client = HttpStatelessClient(
|
||||
name="browser-tools",
|
||||
transport="sse",
|
||||
url="http://localhost:3000/sse"
|
||||
)
|
||||
await toolkit.register_mcp_client(client)
|
||||
```
|
||||
|
||||
3. **Custom Hooks** (in agent.py):
|
||||
```python
|
||||
async def pre_reasoning_hook(self, *args, **kwargs):
|
||||
"""Custom logic before reasoning"""
|
||||
# Add context, check conditions, etc.
|
||||
pass
|
||||
|
||||
# In __init__:
|
||||
self.register_instance_hook("pre_reasoning", "my_hook", pre_reasoning_hook)
|
||||
```
|
||||
|
||||
## More Examples and Resources
|
||||
|
||||
Explore official AgentScope examples:
|
||||
- https://github.com/modelscope/agentscope/tree/main/examples/agent
|
||||
|
||||
Key examples to study:
|
||||
- **ReAct Agent** - Basic reasoning-acting agent
|
||||
- **Conversation Agent** - Multi-turn dialogue handling
|
||||
- **User Agent** - Human-in-the-loop interactions
|
||||
- **Tool Agent** - Advanced tool usage patterns
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. **Understand Requirements** - Clarify what the agent should do
|
||||
2. **Learn Patterns** - Use DeepWiki to research relevant AgentScope patterns
|
||||
3. **Design Agent** - Choose base class and required capabilities
|
||||
4. **Implement in agent.py** - Write custom agent logic
|
||||
5. **Add Tools in toolkit.py** - Register needed tools and MCP servers
|
||||
6. **Test with agentscope-test-runner** - Validate functionality
|
||||
7. **Iterate** - Refine based on test results
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start Simple** - Begin with basic ReActAgent, add complexity as needed
|
||||
2. **Use Hooks Wisely** - Don't overcomplicate; hooks should have clear purposes
|
||||
3. **Memory Management** - Implement summarization for long conversations
|
||||
4. **Tool Selection** - Only add tools the agent actually needs
|
||||
5. **Clear Prompts** - Write specific, actionable system prompts in prompt.md
|
||||
6. **Test Iteratively** - Use the test-runner frequently during development
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Use DeepWiki MCP to query AgentScope documentation
|
||||
- Study the browser_agent.py example in this guide
|
||||
- Reference official examples at https://github.com/agentscope-ai/agentscope
|
||||
- Test early and often with agentscope-test-runner
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Focus on making the agent intelligent and capable. The deployment infrastructure is already handled - your job is to build the "brain" of the agent in agent.py and give it the right "tools" in toolkit.py.
|
||||
Reference in New Issue
Block a user