hermes-agent-guide

# Hermes Agent Guide > Skill by [ara.so](https://ara.so) — Hermes Skills collection. This skill provides comprehensive knowledge of the Hermes Agent framework based on the most extensive Chinese guide available. Hermes Agent is a powerful open-source AI Agent framework that inherits from OpenClaw with significant upgrades in architecture, memory systems, skill ecosystem, and automation capabilities. ## What is Hermes Agent Hermes Agent is an advanced AI Agent framework developed by Nous Research that enables: - **Autonomous Task Execution**: Agents can plan, execute, and learn from complex multi-step tasks - **Three-Layer Memory System**: Session memory, persistent memory, and skill-level memory - **Rich Skill Ecosystem**: 47+ built-in tools across 7 categories, plus Skills Hub integration - **MCP Protocol Support**: Access to 6000+ Model Context Protocol services - **Multi-Platform Integration**: Connect to Discord, Slack, WeChat, Feishu, and 15+ platforms - **Multi-Agent Orchestration**: Coordinate multiple agents for complex workflows ## Installation ### Local Installation (Recommended for Development) ```bash # Clone the repository git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent # Create virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Copy environment template cp .env.example .env # Edit .env with your configuration # Required: OPENAI_API_KEY or other LLM provider keys ``` ### Docker Installation (Recommended for Production) ```bash # Pull the official image docker pull nousresearch/hermes-agent:latest # Create docker-compose.yml cat > docker-compose.yml << EOF version: '3.8' services: hermes: image: nousresearch/hermes-agent:latest environment: - OPENAI_API_KEY=\${OPENAI_API_KEY} - HERMES_MEMORY_TYPE=persistent volumes: - ./data:/app/data - ./skills:/app/skills ports: - "8080:8080" restart: unless-stopped EOF # Start the service docker-compose up -d ``` ### VPS Deployment ```bash # On Ubuntu/Debian sudo apt update && sudo apt install -y python3.11 python3-pip git # Clone and setup git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent pip3 install -r requirements.txt # Setup systemd service sudo tee /etc/systemd/system/hermes-agent.service << EOF [Unit] Description=Hermes Agent Service After=network.target [Service] Type=simple User=$USER WorkingDirectory=$(pwd) Environment="OPENAI_API_KEY=${OPENAI_API_KEY}" ExecStart=$(which python3) main.py Restart=always [Install] WantedBy=multi-user.target EOF sudo systemctl enable hermes-agent sudo systemctl start hermes-agent ``` ## Core Architecture Hermes Agent uses a five-layer architecture: ### 1. Interface Layer Handles user interactions across multiple platforms: ```python from hermes.interface import DiscordInterface, SlackInterface, CLIInterface # CLI interface cli = CLIInterface() cli.start() # Discord bot discord = DiscordInterface( token=os.getenv("DISCORD_BOT_TOKEN"), intents=["messages", "guilds"] ) discord.run() # Slack app slack = SlackInterface( token=os.getenv("SLACK_BOT_TOKEN"), signing_secret=os.getenv("SLACK_SIGNING_SECRET") ) slack.start() ``` ### 2. Orchestration Layer Manages agent lifecycle and task coordination: ```python from hermes.orchestrator import AgentOrchestrator from hermes.agent import HermesAgent orchestrator = AgentOrchestrator() # Create and register agents research_agent = HermesAgent( name="research_assistant", model="gpt-4", skills=["web_search", "summarization"] ) code_agent = HermesAgent( name="code_assistant", model="claude-3-opus", skills=["code_generation", "code_review"] ) orchestrator.register_agent(research_agent) orchestrator.register_agent(code_agent) # Execute coordinated task result = await orchestrator.execute_task( "Research the latest AI frameworks and generate a comparison report", agents=["research_assistant", "code_assistant"] ) ``` ### 3. Agent Core Layer The brain of each agent: ```python from hermes.agent import HermesAgent from hermes.memory import MemoryConfig from hermes.skills import SkillRegistry agent = HermesAgent( name="my_assistant", model="gpt-4-turbo", temperature=0.7, memory_config=MemoryConfig( session_memory=True, persistent_memory=True, vector_store="chromadb" ), skill_registry=SkillRegistry.load_default(), system_prompt="""You are a helpful AI assistant with access to various tools and a persistent memory system.""" ) # Agent automatically plans and executes response = await agent.chat("Analyze my project's GitHub issues and create a priority matrix") ``` ### 4. Tool Layer 47+ built-in tools organized in 7 categories: ```python from hermes.tools import ( WebSearchTool, FileSystemTool, GitHubTool, DatabaseTool, CodeExecutionTool, APIRequestTool ) # Configure tools tools = [ WebSearchTool(api_key=os.getenv("SERPER_API_KEY")), GitHubTool(token=os.getenv("GITHUB_TOKEN")), FileSystemTool(allowed_paths=["/workspace"]), CodeExecutionTool(sandbox_mode=True), DatabaseTool(connection_string=os.getenv("DATABASE_URL")) ] # Attach to agent agent.add_tools(tools) ``` ### 5. Integration Layer Connects to external services via MCP: ```python from hermes.mcp import MCPClient mcp = MCPClient() # Add MCP servers mcp.add_server("filesystem", "npx -y @modelcontextprotocol/server-filesystem /workspace") mcp.add_server("github", "npx -y @modelcontextprotocol/server-github") mcp.add_server("postgres", "npx -y @modelcontextprotocol/server-postgres") # Use in agent agent.connect_mcp(mcp) ``` ## Memory System ### Session Memory Temporary conversation context: ```python from hermes.memory import SessionMemory session = SessionMemory( max_tokens=4096, summarization_threshold=3000 ) # Automatically managed during conversation agent.memory.session = session ``` ### Persistent Memory Long-term knowledge storage: ```python from hermes.memory import PersistentMemory persistent = PersistentMemory( backend="chromadb", collection_name="hermes_memory", embedding_model="text-embedding-3-small" ) # Store important information await persistent.store( content="User prefers Python for backend development", metadata={"type": "preference", "category": "development"} ) # Query relevant memories memories = await persistent.query( "What are the user's coding preferences?", top_k=5 ) ``` ### Skill-Level Memory Memory specific to each skill: ```python from hermes.skills import Skill class ProjectManagementSkill(Skill): def __init__(self): super().__init__(name="project_management") self.memory = self.get_skill_memory() async def track_project(self, project_name: str, status: str): await self.memory.store({ "project": project_name, "status": status, "timestamp": datetime.now() }) async def get_active_projects(self): return await self.memory.query( "status:active", filter_type="metadata" ) ``` ## Skills System ### Using Built-in Skills ```python from hermes.skills import SkillRegistry registry = SkillRegistry() # Load specific skills web_skill = registry.get("web_automation") data_skill = registry.get("data_analysis") # Load all skills from category dev_skills = registry.get_category("development") # Attach to agent agent.add_skills([web_skill, data_skill]) ``` ### Creating Custom Skills ```python from hermes.skills import Skill, skill_action class CustomResearchSkill(Skill): """Advanced research skill with citation tracking""" name = "advanced_research" description = "Perform deep research with source tracking" def __init__(self): super().__init__() self.sources = [] @skill_action( description="Search and summarize academic papers", parameters={ "query": {"type": "string", "required": True}, "max_results": {"type": "integer", "default": 10} } ) async def search_papers(self, query: str, max_results: int = 10): # Implementation results = await self.tools.web_search( f"{query} site:arxiv.org OR site:scholar.google.com", max_results=max_results ) # Track sources for result in results: self.sources.append({ "title": result.title, "url": result.url, "timestamp": datetime.now() }) summary = await self.summarize(results) return { "summary": summary, "sources": self.sources } @skill_action(description="Generate bibliography from tracked sources") async def generate_bibliography(self): return "\n".join([ f"- {s['title']}: {s['url']}" for s in self.sources ]) # Register and use registry.register(CustomResearchSkill()) ``` ### Skills Hub Integration ```python from hermes.skills import SkillsHub hub = SkillsHub(api_key=os.getenv("SKILLS_HUB_API_KEY")) # Search for skills results = hub.search("data visualization") # Install skill skill = hub.install("community/advanced-charts") # Add to agent agent.add_skill(skill) ``` ## Tool Categories ### 1. Web & Network Tools ```python from hermes.tools import WebSearchTool, WebScrapingTool, APIRequestTool # Web search search = WebSearchTool(provider="serper", api_key=os.getenv("SERPER_API_KEY")) results = await search.search("latest AI news") # Web scraping scraper = WebScrapingTool(user_agent="Hermes-Agent/1.0") content = await scraper.scrape("https://example.com") # API requests api = APIRequestTool() response = await api.request( method="POST", url="https://api.example.com/data", headers={"Authorization": f"Bearer {os.getenv('API_TOKEN')}"}, json={"query": "data"} ) ``` ### 2. File System Tools ```python from hermes.tools import FileSystemTool fs = FileSystemTool( base_path="/workspace", allowed_operations=["read", "write", "list"] ) # Read file content = await fs.read_file("project/README.md") # Write file await fs.write_file("output/report.txt", "Report content") # List directory files = await fs.list_directory("project/src") ``` ### 3. Code Execution Tools ```python from hermes.tools import CodeExecutionTool executor = CodeExecutionTool( sandbox_mode=True, timeout=30, allowed_imports=["requests", "pandas", "numpy"] ) # Execute Python code result = await executor.execute_python(""" import pandas as pd data = pd.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]}) print(data.describe()) """) print(result.stdout) print(result.return_value) ``` ### 4. Database Tools ```python from hermes.tools import DatabaseTool db = DatabaseTool( connection_string=os.getenv("DATABASE_URL"), read_only=False ) # Query results = await db.query("SELECT * FROM users WHERE active = true") # Execute with parameters await db.execute( "INSERT INTO logs (message, level) VALUES ($1, $2)", ["Operation completed", "INFO"] ) ``` ### 5. Version Control Tools ```python from hermes.tools import GitHubTool github = GitHubTool(token=os.getenv("GITHUB_TOKEN")) # Create issue issue = await github.create_issue( repo="owner/repo", title="Bug: Memory leak in agent loop", body="Detailed description...", labels=["bug", "priority-high"] ) # Create pull request pr = await github.create_pull_request( repo="owner/repo", title="Fix memory leak", head="feature-branch", base="main", body="This PR fixes the memory leak issue" ) ``` ### 6. Communication Tools