higress/hgctl/pkg/agent/prompt/agent_guide.md

// 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:

# 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:

# 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

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

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):

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):

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):

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.