📄 user-guide/features/overview.md

title: "Features Overview" sidebar_label: "Overview" sidebar_position: 1

ภาพรวมคุณสมบัติ (Features Overview)

Hermes Agent มีชุดความสามารถที่หลากหลาย ซึ่งขยายขอบเขตไปไกลกว่าการแชทพื้นฐาน ตั้งแต่หน่วยความจำถาวร (persistent memory) และบริบทที่รับรู้ไฟล์ ไปจนถึงการทำงานอัตโนมัติของเบราว์เซอร์ (browser automation) และการสนทนาด้วยเสียง คุณสมบัติเหล่านี้ทำงานร่วมกันเพื่อทำให้ Hermes เป็นผู้ช่วยอัตโนมัติที่มีประสิทธิภาพสูง

Core (แกนหลัก)

• Tools & Toolsets - Tools คือฟังก์ชันที่ขยายขีดความสามารถของ agent โดยถูกจัดระเบียบเป็น toolsets ทางตรรกะที่สามารถเปิดหรือปิดได้ตามแพลตฟอร์มต่างๆ ครอบคลุมการค้นหาเว็บ การรัน terminal การแก้ไขไฟล์ หน่วยความจำ การมอบหมายงาน และอื่นๆ
• Skills System - คือเอกสารความรู้ที่ agent สามารถโหลดได้ตามความต้องการ Skills จะใช้รูปแบบการเปิดเผยความรู้แบบค่อยเป็นค่อยไป (progressive disclosure) เพื่อลดการใช้ token และเข้ากันได้กับมาตรฐาน open standard ของ agentskills.io
• Persistent Memory - หน่วยความจำที่ถูกจำกัดและคัดสรรมาอย่างดี ซึ่งคงอยู่ข้ามเซสชัน Hermes จะจดจำความชอบ โครงการ สภาพแวดล้อม และสิ่งที่เรียนรู้ผ่าน MEMORY.md และ USER.md
• Context Files - Hermes จะค้นพบและโหลด context files ของโปรเจกต์โดยอัตโนมัติ (เช่น .hermes.md, AGENTS.md, CLAUDE.md, SOUL.md, .cursorrules) ซึ่งเป็นตัวกำหนดพฤติกรรมของ agent ในโปรเจกต์ของคุณ
• Context References - ใช้เครื่องหมาย @ ตามด้วยการอ้างอิงเพื่อแทรกไฟล์ โฟลเดอร์ git diffs และ URL เข้าไปในข้อความของคุณโดยตรง Hermes จะขยายการอ้างอิงนั้นในบรรทัดเดียวกันและแนบเนื้อหาให้โดยอัตโนมัติ
• Checkpoints - Hermes จะถ่ายภาพ (snapshot) working directory ของคุณโดยอัตโนมัติก่อนทำการเปลี่ยนแปลงไฟล์ ทำให้คุณมีตาข่ายนิรภัยในการย้อนกลับ (roll back) ด้วยคำสั่ง /rollback หากมีสิ่งผิดพลาดเกิดขึ้น

Automation (ระบบอัตโนมัติ)

• Scheduled Tasks (Cron) - กำหนดตารางงานให้รันโดยอัตโนมัติด้วยภาษาธรรมชาติ (natural language) หรือ cron expressions งานเหล่านี้สามารถแนบ skills, ส่งผลลัพธ์ไปยังแพลตฟอร์มใดก็ได้ และรองรับการทำงาน pause/resume/edit
• Subagent Delegation - tool delegate_task จะสร้าง instance ของ agent ลูกที่มี context แยกส่วน, toolsets ที่จำกัด, และ terminal sessions ของตัวเอง โดยค่าเริ่มต้นจะรัน subagents พร้อมกัน 3 ตัว (สามารถตั้งค่าได้) สำหรับกระบวนการทำงานแบบขนาน
• Code Execution - tool execute_code ช่วยให้ agent เขียนสคริปต์ Python ที่เรียกใช้ tools ของ Hermes ในรูปแบบโปรแกรม (programmatically) ซึ่งเป็นการรวมขั้นตอนการทำงานหลายขั้นตอนให้เป็น LLM turn เดียวผ่านการรัน RPC แบบ sandboxed
• Event Hooks - รันโค้ดที่กำหนดเอง ณ จุดสำคัญของ lifecycle Gateway hooks จัดการ logging, alerts, และ webhooks ส่วน plugin hooks จัดการ tool interception, metrics, และ guardrails
• Batch Processing - รัน Hermes agent ข้าม prompt จำนวนหลายร้อยหรือหลายพันรายการแบบขนาน เพื่อสร้างข้อมูล trajectory ที่มีโครงสร้างในรูปแบบ ShareGPT สำหรับการสร้างข้อมูลฝึกฝนหรือการประเมินผล

Media & Web (สื่อและเว็บ)

• Voice Mode - การโต้ตอบด้วยเสียงเต็มรูปแบบทั้งบน CLI และแพลตฟอร์ม messaging คุณสามารถพูดคุยกับ agent ผ่านไมโครโฟน ฟังการตอบกลับด้วยเสียง และสนทนาด้วยเสียงแบบสดในช่องเสียง Discord
• Browser Automation - การทำงานอัตโนมัติของเบราว์เซอร์เต็มรูปแบบด้วย backend หลายตัว: Browserbase cloud, Browser Use cloud, local Chrome ผ่าน CDP, หรือ local Chromium ใช้สำหรับนำทางเว็บไซต์ กรอกฟอร์ม และดึงข้อมูล
• Vision & Image Paste - รองรับ vision แบบ multimodal คุณสามารถวางรูปภาพจาก clipboard เข้าสู่ CLI และขอให้ agent วิเคราะห์ อธิบาย หรือทำงานกับรูปภาพเหล่านั้นโดยใช้ vision-capable model ใดก็ได้
• Image Generation - สร้างรูปภาพจาก text prompts โดยใช้ FAL.ai รองรับ 8 models (FLUX 2 Klein/Pro, GPT-Image 1.5, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo); เลือกใช้ตัวใดตัวหนึ่งผ่าน hermes tools
• Voice & TTS - การส่งออกข้อความให้เป็นเสียงพูด (Text-to-speech) และการถอดเสียงข้อความเสียงในทุกแพลตฟอร์ม messaging โดยมีตัวเลือกผู้ให้บริการ 5 ราย: Edge TTS (ฟรี), ElevenLabs, OpenAI TTS, MiniMax, และ NeuTTS

Integrations (การเชื่อมต่อ)

• MCP Integration - เชื่อมต่อกับ MCP server ใดก็ได้ผ่าน stdio หรือ HTTP transport สามารถเข้าถึงเครื่องมือภายนอกจาก GitHub, ฐานข้อมูล, file systems, และ internal APIs โดยไม่ต้องเขียน tools ของ Hermes เอง มีการรองรับการกรอง tool และการสุ่มตัวอย่างต่อ server
• Provider Routing - ควบคุมอย่างละเอียดว่า AI provider ใดที่จะจัดการคำขอของคุณ ปรับให้เหมาะสมสำหรับต้นทุน ความเร็ว หรือคุณภาพด้วยการจัดเรียง (sorting), whitelists, blacklists, และการกำหนดลำดับความสำคัญ
• Fallback Providers - การสลับไปใช้ LLM providers สำรองโดยอัตโนมัติ เมื่อ model หลักของคุณพบข้อผิดพลาด รวมถึงการสำรองสำหรับงานเสริม เช่น vision และ compression
• Credential Pools - กระจายการเรียกใช้ API ข้ามหลาย keys สำหรับ provider เดียวกัน มีการหมุนเวียนอัตโนมัติเมื่อเกิด rate limits หรือความล้มเหลว
• Memory Providers - เสียบปลั๊ก backend หน่วยความจำภายนอก (Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover) สำหรับการสร้างแบบจำลองผู้ใช้ข้ามเซสชันและการปรับให้เป็นส่วนตัวที่เหนือกว่าระบบหน่วยความจำที่ติดตั้งมาให้
• API Server - เปิดเผย Hermes เป็น HTTP endpoint ที่เข้ากันได้กับ OpenAI สามารถเชื่อมต่อ frontend ใดๆ ที่ใช้รูปแบบ OpenAI ได้ เช่น Open WebUI, LobeChat, LibreChat, และอื่นๆ
• IDE Integration (ACP) - ใช้ Hermes ภายใน editor ที่รองรับ ACP เช่น VS Code, Zed, และ JetBrains สามารถแชท, กิจกรรม tool, file diffs, และคำสั่ง terminal แสดงผลภายใน editor ของคุณ
• RL Training - สร้างข้อมูล trajectory จากเซสชันของ agent สำหรับการเรียนรู้แบบเสริมกำลัง (reinforcement learning) และการ fine-tuning model

Customization (การปรับแต่ง)

• Personality & SOUL.md - บุคลิกภาพของ agent ที่ปรับแต่งได้อย่างสมบูรณ์แบบ SOUL.md คือไฟล์ identity หลัก ซึ่งเป็นสิ่งแรกใน system prompt และคุณสามารถสลับใช้ presets /personality ที่ติดตั้งมาหรือที่กำหนดเองได้ในแต่ละเซสชัน
• Skins & Themes - ปรับแต่งการแสดงผลทางภาพของ CLI: สี banner, spinner faces และ verbs, ป้ายกำกับ response-box, branding text, และ prefix ของ tool activity
• Plugins - เพิ่ม tools, hooks, และ integrations ที่กำหนดเองโดยไม่ต้องแก้ไข core code มี plugin 3 ประเภท: general plugins (tools/hooks), memory providers (ความรู้ข้ามเซสชัน), และ context engines (การจัดการ context ทางเลือก) จัดการผ่าน UI แบบโต้ตอบ hermes plugins ที่รวมศูนย์

📄 user-guide/features/acp.md

sidebar_position: 11 title: "ACP Editor Integration" description: "Use Hermes Agent inside ACP-compatible editors such as VS Code, Zed, and JetBrains"

การผสานรวม ACP Editor

Hermes Agent สามารถทำงานเป็น ACP server ทำให้ editor ที่รองรับ ACP สามารถสื่อสารกับ Hermes ผ่าน stdio และแสดงผล:

• chat messages
• tool activity
• file diffs
• terminal commands
• approval prompts
• streamed thinking / response chunks

ACP เหมาะอย่างยิ่งเมื่อคุณต้องการให้ Hermes ทำงานเหมือน coding agent ที่เป็น native ของ editor แทนที่จะเป็น CLI หรือ messaging bot แบบ standalone

สิ่งที่ Hermes เปิดเผยในโหมด ACP

Hermes ทำงานด้วยชุดเครื่องมือ hermes-acp ที่คัดสรรมาสำหรับ editor workflows โดยประกอบด้วย:

• file tools: read_file, write_file, patch, search_files
• terminal tools: terminal, process
• web/browser tools
• memory, todo, session search
• skills
• execute_code and delegate_task
• vision

โดยเจตนาได้ยกเว้นสิ่งที่ไม่ได้เข้ากับ typical editor UX เช่น การส่งข้อความ (messaging delivery) และการจัดการ cronjob

การติดตั้ง

ติดตั้ง Hermes ตามปกติ จากนั้นเพิ่มส่วนขยาย ACP:

pip install -e '.[acp]'

สิ่งนี้จะติดตั้ง dependency agent-client-protocol และเปิดใช้งาน:

• hermes acp
• hermes-acp
• python -m acp_adapter

การเปิดใช้งาน ACP server

คำสั่งใดคำสั่งหนึ่งต่อไปนี้จะเริ่ม Hermes ในโหมด ACP:

hermes acp

hermes-acp

python -m acp_adapter

Hermes จะบันทึก log ไปที่ stderr เพื่อให้ stdout สงวนไว้สำหรับ traffic ของ ACP JSON-RPC

การตั้งค่า Editor

VS Code

ติดตั้ง ACP client extension จากนั้นชี้ไปยัง directory acp_registry/ ของ repo

ตัวอย่าง settings snippet:

{
  "acpClient.agents": [
    {
      "name": "hermes-agent",
      "registryDir": "/path/to/hermes-agent/acp_registry"
    }
  ]
}

Zed

ตัวอย่าง settings snippet:

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"],
    },
  },
}

JetBrains

ใช้ plugin ที่รองรับ ACP และชี้ไปยัง:

/path/to/hermes-agent/acp_registry

Registry manifest

ACP registry manifest อยู่ที่:

acp_registry/agent.json

มันจะประกาศ agent ที่ทำงานด้วยคำสั่ง (command-based agent) โดยมีคำสั่ง launch คือ:

hermes acp

Configuration and credentials

โหมด ACP ใช้การตั้งค่า Hermes เดียวกันกับ CLI:

• ~/.hermes/.env
• ~/.hermes/config.yaml
• ~/.hermes/skills/
• ~/.hermes/state.db

Provider resolution ใช้ runtime resolver ปกติของ Hermes ดังนั้น ACP จึงสืบทอด provider และ credentials ที่กำหนดค่าไว้ในปัจจุบัน

Session behavior

ACP sessions จะถูกติดตามโดย in-memory session manager ของ ACP adapter ในขณะที่ server กำลังทำงาน

แต่ละ session จะเก็บ:

• session ID
• working directory
• selected model
• ประวัติการสนทนาปัจจุบัน
• cancel event

AIAgent ที่อยู่เบื้องหลังยังคงใช้ paths สำหรับ persistence/logging ปกติของ Hermes แต่คำสั่ง ACP list/load/resume/fork จะถูกจำกัดขอบเขต (scoped) ให้กับกระบวนการ ACP server ที่กำลังทำงานอยู่

Working directory behavior

ACP sessions จะผูก cwd (current working directory) ของ editor เข้ากับ Hermes task ID เพื่อให้ file และ terminal tools ทำงานโดยอ้างอิงจาก editor workspace ไม่ใช่ cwd ของ server process

Approvals

คำสั่ง terminal ที่อันตรายสามารถถูกส่งกลับไปยัง editor ในรูปแบบ prompts การอนุมัติ ตัวเลือกการอนุมัติของ ACP นั้นง่ายกว่า flow ของ CLI:

• allow once
• allow always
• deny

เมื่อหมดเวลา (timeout) หรือเกิดข้อผิดพลาด (error) approval bridge จะปฏิเสธคำขอ

การแก้ไขปัญหา (Troubleshooting)

ACP agent ไม่ปรากฏใน editor

ตรวจสอบ:

• editor ชี้ไปยัง path acp_registry/ ที่ถูกต้อง
• Hermes ได้รับการติดตั้งและอยู่ใน PATH ของคุณ
• ได้ติดตั้งส่วนขยาย ACP แล้ว (pip install -e '.[acp]')

ACP เริ่มต้นแต่เกิดข้อผิดพลาดทันที

ลองตรวจสอบด้วยคำสั่งเหล่านี้:

hermes doctor
hermes status
hermes acp

ขาด credentials

โหมด ACP ไม่มี flow การ login ของตัวเอง มันใช้ provider setup ที่มีอยู่ของ Hermes กำหนดค่า credentials ด้วย:

hermes model

หรือโดยการแก้ไข ~/.hermes/.env

ดูเพิ่มเติม

• ACP Internals
• Provider Runtime Resolution
• Tools Runtime

📄 user-guide/features/api-server.md

sidebar_position: 14 title: "API Server" description: "Expose hermes-agent as an OpenAI-compatible API for any frontend"

API Server

API server ให้บริการ hermes-agent ในรูปแบบ HTTP endpoint ที่เข้ากันได้กับ OpenAI. Frontend ใดๆ ที่รองรับรูปแบบ OpenAI - เช่น Open WebUI, LobeChat, LibreChat, NextChat, ChatBox และอีกหลายร้อยตัว - สามารถเชื่อมต่อกับ hermes-agent และใช้มันเป็น backend ได้

Agent ของคุณจะจัดการคำขอด้วยชุดเครื่องมือทั้งหมด (terminal, file operations, web search, memory, skills) และส่งคืนการตอบกลับสุดท้าย เมื่อมีการสตรีม (streaming) ตัวบ่งชี้ความคืบหน้าของเครื่องมือจะปรากฏแบบ inline เพื่อให้ frontend สามารถแสดงให้เห็นว่า agent กำลังทำอะไรอยู่

Quick Start

1. Enable the API server

Add to ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Optional: only if a browser must call Hermes directly
# API_SERVER_CORS_ORIGINS=http://localhost:3000

2. Start the gateway

hermes gateway

คุณจะเห็นข้อความ:

[API Server] API server listening on http://127.0.0.1:8642

3. Connect a frontend

ชี้ client ที่เข้ากันได้กับ OpenAI ไปที่ http://localhost:8642/v1:

# Test with curl
curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

หรือเชื่อมต่อ Open WebUI, LobeChat, หรือ frontend อื่นๆ - ดู Open WebUI integration guide สำหรับคำแนะนำแบบทีละขั้นตอน

Endpoints

POST /v1/chat/completions

รูปแบบ Chat Completions ของ OpenAI มาตรฐาน ไม่มีสถานะ (Stateless) - บทสนทนาทั้งหมดจะถูกรวมอยู่ในแต่ละคำขอผ่าน array messages.

Request:

{
  "model": "hermes-agent",
  "messages": [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "Write a fibonacci function"}
  ],
  "stream": false
}

Response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "hermes-agent",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Here's a fibonacci function..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

Inline image input: ข้อความจากผู้ใช้ (user messages) อาจส่ง content เป็น array ของส่วน text และ image_url รองรับทั้ง URL แบบ remote http(s) และ URL แบบ data:image/...:

{
  "model": "hermes-agent",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
      ]
    }
  ]
}

ไฟล์ที่อัปโหลด (file / input_file / file_id) และ URL data: ที่ไม่ใช่รูปภาพ จะส่งคืน 400 unsupported_content_type.

Streaming ("stream": true): ส่งคืน Server-Sent Events (SSE) พร้อมส่วนของคำตอบแบบ token-by-token สำหรับ Chat Completions การสตรีมจะใช้ event มาตรฐาน chat.completion.chunk บวกกับ event hermes.tool.progress ของ Hermes สำหรับ UX การเริ่มใช้เครื่องมือ สำหรับ Responses การสตรีมจะใช้ประเภท event ของ OpenAI Responses เช่น response.created, response.output_text.delta, response.output_item.added, response.output_item.done, และ response.completed.

Tool progress in streams:

• Chat Completions: Hermes จะปล่อย event: hermes.tool.progress สำหรับการมองเห็นการเริ่มใช้เครื่องมือโดยไม่ทำให้ข้อความผู้ช่วยที่บันทึกไว้เสียหาย
• Responses: Hermes จะปล่อย function_call และ function_call_output output items ที่เป็น spec-native ระหว่าง SSE stream ทำให้ client สามารถแสดง UI เครื่องมือแบบ structured ได้แบบเรียลไทม์

POST /v1/responses

รูปแบบ OpenAI Responses API รองรับสถานะการสนทนาฝั่งเซิร์ฟเวอร์ผ่าน previous_response_id - เซิร์ฟเวอร์จะจัดเก็บประวัติการสนทนาทั้งหมด (รวมถึง tool calls และผลลัพธ์) เพื่อให้บริบทแบบ multi-turn ถูกรักษาไว้โดยที่ client ไม่ต้องจัดการ

Request:

{
  "model": "hermes-agent",
  "input": "What files are in my project?",
  "instructions": "You are a helpful coding assistant.",
  "store": true
}

Response:

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "hermes-agent",
  "output": [
    {"type": "function_call", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"},
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
  ],
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

Inline image input: input[].content สามารถมีส่วน input_text และ input_image รองรับทั้ง URL แบบ remote และ data:image/... URL:

{
  "model": "hermes-agent",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Describe this screenshot."},
        {"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."}
      ]
    }
  ]
}

ไฟล์ที่อัปโหลด (input_file / file_id) และ URL data: ที่ไม่ใช่รูปภาพ จะส่งคืน 400 unsupported_content_type.

Multi-turn with previous_response_id

เชื่อมโยงการตอบกลับเพื่อรักษาบริบททั้งหมด (รวมถึง tool calls) ข้ามรอบ:

{
  "input": "Now show me the README",
  "previous_response_id": "resp_abc123"
}

เซิร์ฟเวอร์จะสร้างบทสนทนาทั้งหมดขึ้นมาใหม่จาก response chain ที่จัดเก็บไว้ - tool calls และผลลัพธ์ก่อนหน้าทั้งหมดจะถูกรักษาไว้ คำขอแบบ chained ยังแชร์ session เดียวกัน ดังนั้นบทสนทนาแบบ multi-turn จะปรากฏเป็นรายการเดียวใน dashboard และ session history

Named conversations

ใช้พารามิเตอร์ conversation แทนการติดตาม response IDs:

{"input": "Hello", "conversation": "my-project"}
{"input": "What's in src/?", "conversation": "my-project"}
{"input": "Run the tests", "conversation": "my-project"}

เซิร์ฟเวอร์จะทำการเชื่อมโยงอัตโนมัติไปยัง response ล่าสุดใน conversation นั้น เหมือนกับคำสั่ง /title สำหรับ gateway sessions

GET /v1/responses/{id}

ดึง response ที่จัดเก็บไว้ก่อนหน้าด้วย ID

DELETE /v1/responses/{id}

ลบ response ที่จัดเก็บไว้

GET /v1/models

แสดงรายการ agent ในฐานะ model ที่พร้อมใช้งาน ชื่อ model ที่โฆษณาจะค่าเริ่มต้นเป็นชื่อ profile (หรือ hermes-agent สำหรับ default profile) จำเป็นสำหรับ frontend ส่วนใหญ่สำหรับการค้นพบ model

GET /health

Health check. ส่งคืน {"status": "ok"} นอกจากนี้ยังสามารถใช้ได้ที่ GET /v1/health สำหรับ client ที่เข้ากันได้กับ OpenAI ที่คาดหวัง prefix /v1/.

GET /health/detailed

Health check แบบขยายที่รายงาน session ที่ใช้งานอยู่, agent ที่กำลังทำงาน, และการใช้ทรัพยากร มีประโยชน์สำหรับเครื่องมือ monitoring/observability

Runs API (streaming-friendly alternative)

นอกจาก /v1/chat/completions และ /v1/responses แล้ว เซิร์ฟเวอร์ยังเปิดเผย runs API สำหรับ session แบบ long-form ที่ client ต้องการสมัครรับ progress events แทนการจัดการ streaming ด้วยตัวเอง

POST /v1/runs

สร้าง agent run ใหม่ ส่งคืน run_id ที่สามารถใช้สมัครรับ progress events ได้

GET /v1/runs/{run_id}/events

Server-Sent Events stream ของ progress tool-call, token deltas, และ lifecycle events ของ run ออกแบบมาสำหรับ dashboard และ thick clients ที่ต้องการแนบ/ถอดการเชื่อมต่อโดยไม่สูญเสีย state

Jobs API (background scheduled work)

เซิร์ฟเวอร์เปิดเผย jobs CRUD surface ที่มีน้ำหนักเบาสำหรับการจัดการ agent runs แบบกำหนดเวลา/background จาก client ระยะไกล ทุก endpoint ถูกป้องกันด้วย bearer auth เดียวกัน

GET /api/jobs

แสดงรายการ jobs ที่กำหนดเวลาทั้งหมด

POST /api/jobs

สร้าง scheduled job ใหม่ Body รับรูปร่างเดียวกับ hermes cron - prompt, schedule, skills, provider override, delivery target

GET /api/jobs/{job_id}

ดึงคำจำกัดความของ job และสถานะการทำงานครั้งล่าสุด

PATCH /api/jobs/{job_id}

อัปเดต fields บน job ที่มีอยู่ (prompt, schedule, etc.). การอัปเดตบางส่วนจะถูกรวมเข้าด้วยกัน

DELETE /api/jobs/{job_id}

ลบ job และยกเลิก run ที่กำลังดำเนินการอยู่ด้วย

POST /api/jobs/{job_id}/pause

หยุด job โดยไม่ลบ Next-scheduled-run timestamps จะถูกระงับจนกว่าจะถูก resume

POST /api/jobs/{job_id}/resume

ดำเนินการต่อสำหรับ job ที่เคยหยุดชั่วคราว

POST /api/jobs/{job_id}/run

กระตุ้นให้ job ทำงานทันที โดยไม่รอตามกำหนดเวลา

System Prompt Handling

เมื่อ frontend ส่งข้อความ system (Chat Completions) หรือ field instructions (Responses API), hermes-agent จะ เพิ่มทับ (layers on top) system prompt หลักของมัน Agent ของคุณจะยังคงมีเครื่องมือ, memory, และ skills ทั้งหมด - system prompt ของ frontend จะเพิ่มคำแนะนำพิเศษ

นั่นหมายความว่าคุณสามารถปรับแต่งพฤติกรรมตาม frontend โดยไม่สูญเสียความสามารถ:

• Open WebUI system prompt: "You are a Python expert. Always include type hints."
• Agent ยังคงมี terminal, file tools, web search, memory, etc.

Authentication

Bearer token auth ผ่าน header Authorization:

Authorization: Bearer ***

กำหนด key ผ่าน env var API_SERVER_KEY. หากคุณต้องการให้ browser เรียก Hermes โดยตรง ให้ตั้งค่า API_SERVER_CORS_ORIGINS เป็น allowlist ที่ชัดเจนด้วย

:::warning Security API server ให้สิทธิ์การเข้าถึง toolset ทั้งหมดของ hermes-agent รวมถึงคำสั่ง terminal. เมื่อ bind ไปยัง address ที่ไม่ใช่ loopback เช่น 0.0.0.0, API_SERVER_KEY จำเป็น. นอกจากนี้ควรจำกัด API_SERVER_CORS_ORIGINS ให้แคบเพื่อควบคุมการเข้าถึงจาก browser

default bind address (127.0.0.1) สำหรับการใช้งานภายในเครื่องเท่านั้น การเข้าถึงจาก browser ถูกปิดใช้งานโดยค่าเริ่มต้น; เปิดใช้งานเฉพาะสำหรับ origins ที่เชื่อถือได้อย่างชัดเจนเท่านั้น :::

Configuration

Environment Variables

config.yaml

# Not yet supported — use environment variables.
# config.yaml support coming in a future release.

Security Headers

การตอบกลับทั้งหมดรวมถึง security headers:

• X-Content-Type-Options: nosniff - ป้องกัน MIME type sniffing
• Referrer-Policy: no-referrer - ป้องกัน referrer leakage

CORS

API server ไม่ได้ เปิดใช้งาน browser CORS โดยค่าเริ่มต้น

สำหรับการเข้าถึงจาก browser โดยตรง ให้ตั้งค่า allowlist ที่ชัดเจน:

API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

เมื่อเปิดใช้งาน CORS:

• Preflight responses จะรวม Access-Control-Max-Age: 600 (แคช 10 นาที)
• SSE streaming responses จะรวม CORS headers เพื่อให้ client EventSource ของ browser ทำงานได้อย่างถูกต้อง
• Idempotency-Key เป็น allowed request header - client สามารถส่งมันเพื่อการ deduplication (responses จะถูกแคชด้วย key เป็นเวลา 5 นาที)

frontend ส่วนใหญ่ที่ได้รับการจัดทำเอกสาร เช่น Open WebUI เชื่อมต่อแบบ server-to-server และไม่จำเป็นต้องใช้ CORS เลย

Compatible Frontends

frontend ใดๆ ที่รองรับรูปแบบ OpenAI API ก็ใช้งานได้ ทดสอบ/จัดทำเอกสารการรวมระบบ:

Multi-User Setup with Profiles

ในการให้ผู้ใช้หลายคนมี instance ของ Hermes ของตัวเองที่แยกออกจากกัน (config, memory, skills แยกกัน) ให้ใช้ profiles:

# Create a profile per user
hermes profile create alice
hermes profile create bob

# Configure each profile's API server on a different port
hermes -p alice config set API_SERVER_ENABLED true
hermes -p alice config set API_SERVER_PORT 8643
hermes -p alice config set API_SERVER_KEY alice-secret

hermes -p bob config set API_SERVER_ENABLED true
hermes -p bob config set API_SERVER_PORT 8644
hermes -p bob config set API_SERVER_KEY bob-secret

# Start each profile's gateway
hermes -p alice gateway &
hermes -p bob gateway &

API server ของแต่ละ profile จะโฆษณาชื่อ profile เป็น model ID โดยอัตโนมัติ:

• http://localhost:8643/v1/models → model alice
• http://localhost:8644/v1/models → model bob

ใน Open WebUI ให้เพิ่มแต่ละตัวเป็น connection แยกกัน dropdown model จะแสดง alice และ bob เป็น model ที่แตกต่างกัน โดยแต่ละตัวมี instance ของ Hermes ที่แยกออกจากกันโดยสมบูรณ์ ดู Open WebUI guide สำหรับรายละเอียด

Limitations

• Response storage - response ที่จัดเก็บไว้ (สำหรับ previous_response_id) จะถูก persist ใน SQLite และอยู่รอดแม้ gateway จะรีสตาร์ท รองรับสูงสุด 100 response ที่จัดเก็บ (LRU eviction).
• No file upload - รองรับ inline images ทั้งใน /v1/chat/completions และ /v1/responses แต่ไฟล์ที่อัปโหลด (file, input_file, file_id) และ input เอกสารที่ไม่ใช่รูปภาพ ไม่รองรับผ่าน API.
• Model field is cosmetic - field model ใน requests จะถูกยอมรับ แต่ model LLM จริงที่ใช้จะถูกกำหนดค่าฝั่งเซิร์ฟเวอร์ใน config.yaml.

Proxy Mode

API server ยังทำหน้าที่เป็น backend สำหรับ gateway proxy mode ด้วย เมื่อ instance ของ Hermes gateway อื่นถูกกำหนดค่าด้วย GATEWAY_PROXY_URL ชี้มาที่ API server นี้ มันจะส่งต่อข้อความทั้งหมดมาที่นี่แทนการรัน agent ของตัวเอง วิธีนี้ช่วยให้สามารถ deploy แบบแยกส่วนได้ - ตัวอย่างเช่น Docker container ที่จัดการ Matrix E2EE ที่ส่งต่อ (relays) ไปยัง agent ฝั่ง host

ดู Matrix Proxy Mode สำหรับคู่มือการตั้งค่าทั้งหมด

Jobs API (background scheduled work)

เซิร์ฟเวอร์เปิดเผย jobs CRUD surface ที่มีน้ำหนักเบาสำหรับการจัดการ agent runs แบบกำหนดเวลา/background จาก client ระยะไกล ทุก endpoint ถูกป้องกันด้วย bearer auth เดียวกัน

GET /api/jobs

แสดงรายการ jobs ที่กำหนดเวลาทั้งหมด

POST /api/jobs

สร้าง scheduled job ใหม่ Body รับรูปร่างเดียวกับ hermes cron - prompt, schedule, skills, provider override, delivery target

GET /api/jobs/{job_id}

ดึงคำจำกัดความของ job และสถานะการทำงานครั้งล่าสุด

PATCH /api/jobs/{job_id}

อัปเดต fields บน job ที่มีอยู่ (prompt, schedule, etc.). การอัปเดตบางส่วนจะถูกรวมเข้าด้วยกัน

DELETE /api/jobs/{job_id}

ลบ job และยกเลิก run ที่กำลังดำเนินการอยู่ด้วย

POST /api/jobs/{job_id}/pause

หยุด job โดยไม่ลบ Next-scheduled-run timestamps จะถูกระงับจนกว่าจะถูก resume

POST /api/jobs/{job_id}/resume

ดำเนินการต่อสำหรับ job ที่เคยหยุดชั่วคราว

POST /api/jobs/{job_id}/run

กระตุ้นให้ job ทำงานทันที โดยไม่รอตามกำหนดเวลา

System Prompt Handling

เมื่อ frontend ส่งข้อความ system (Chat Completions) หรือ field instructions (Responses API), hermes-agent จะ เพิ่มทับ (layers on top) system prompt หลักของมัน Agent ของคุณจะยังคงมีเครื่องมือ, memory, และ skills ทั้งหมด - system prompt ของ frontend จะเพิ่มคำแนะนำพิเศษ

นั่นหมายความว่าคุณสามารถปรับแต่งพฤติกรรมตาม frontend โดยไม่สูญเสียความสามารถ:

• Open WebUI system prompt: "You are a Python expert. Always include type hints."
• Agent ยังคงมี terminal, file tools, web search, memory, etc.

Authentication

Bearer token auth ผ่าน header Authorization:

Authorization: Bearer ***

กำหนด key ผ่าน env var API_SERVER_KEY. หากคุณต้องการให้ browser เรียก Hermes โดยตรง ให้ตั้งค่า API_SERVER_CORS_ORIGINS เป็น allowlist ที่ชัดเจนด้วย

:::warning Security API server ให้สิทธิ์การเข้าถึง toolset ทั้งหมดของ hermes-agent, รวมถึงคำสั่ง terminal. เมื่อ bind ไปยัง address ที่ไม่ใช่ loopback เช่น 0.0.0.0, API_SERVER_KEY จำเป็น. นอกจากนี้ควรจำกัด API_SERVER_CORS_ORIGINS ให้แคบเพื่อควบคุมการเข้าถึงจาก browser

default bind address (127.0.0.1) สำหรับการใช้งานภายในเครื่องเท่านั้น การเข้าถึงจาก browser ถูกปิดใช้งานโดยค่าเริ่มต้น; เปิดใช้งานเฉพาะสำหรับ origins ที่เชื่อถือได้อย่างชัดเจนเท่านั้น :::

Configuration

Environment Variables

config.yaml

# Not yet supported — use environment variables.
# config.yaml support coming in a future release.

Security Headers

การตอบกลับทั้งหมดรวมถึง security headers:

• X-Content-Type-Options: nosniff - ป้องกัน MIME type sniffing
• Referrer-Policy: no-referrer - ป้องกัน referrer leakage

CORS

API server ไม่ได้ เปิดใช้งาน browser CORS โดยค่าเริ่มต้น

สำหรับการเข้าถึงจาก browser โดยตรง ให้ตั้งค่า allowlist ที่ชัดเจน:

API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

เมื่อเปิดใช้งาน CORS:

• Preflight responses จะรวม Access-Control-Max-Age: 600 (แคช 10 นาที)
• SSE streaming responses จะรวม CORS headers เพื่อให้ client EventSource ของ browser ทำงานได้อย่างถูกต้อง
• Idempotency-Key เป็น allowed request header - client สามารถส่งมันเพื่อการ deduplication (responses จะถูกแคชด้วย key เป็นเวลา 5 นาที)

frontend ส่วนใหญ่ที่ได้รับการจัดทำเอกสาร เช่น Open WebUI เชื่อมต่อแบบ server-to-server และไม่จำเป็นต้องใช้ CORS เลย

Compatible Frontends

frontend ใดๆ ที่รองรับรูปแบบ OpenAI API ก็ใช้งานได้ ทดสอบ/จัดทำเอกสารการรวมระบบ:

Multi-User Setup with Profiles

ในการให้ผู้ใช้หลายคนมี instance ของ Hermes ของตัวเองที่แยกออกจากกัน (config, memory, skills แยกกัน) ให้ใช้ profiles:

# Create a profile per user
hermes profile create alice
hermes profile create bob

# Configure each profile's API server on a different port
hermes -p alice config set API_SERVER_ENABLED true
hermes -p alice config set API_SERVER_PORT 8643
hermes -p alice config set API_SERVER_KEY alice-secret

hermes -p bob config set API_SERVER_ENABLED true
hermes -p bob config set API_SERVER_PORT 8644
hermes -p bob config set API_SERVER_KEY bob-secret

# Start each profile's gateway
hermes -p alice gateway &
hermes -p bob gateway &

API server ของแต่ละ profile จะโฆษณาชื่อ profile เป็น model ID โดยอัตโนมัติ:

• http://localhost:8643/v1/models → model alice
• http://localhost:8644/v1/models → model bob

ใน Open WebUI ให้เพิ่มแต่ละตัวเป็น connection แยกกัน dropdown model จะแสดง alice และ bob เป็น model ที่แตกต่างกัน โดยแต่ละตัวมี instance ของ Hermes ที่แยกออกจากกันโดยสมบูรณ์ ดู Open WebUI guide สำหรับรายละเอียด

Limitations

• Response storage - response ที่จัดเก็บไว้ (สำหรับ previous_response_id) จะถูก persist ใน SQLite และอยู่รอดแม้ gateway จะรีสตาร์ท รองรับสูงสุด 100 response ที่จัดเก็บ (LRU eviction).
• No file upload - รองรับ inline images ทั้งใน /v1/chat/completions และ /v1/responses แต่ไฟล์ที่อัปโหลด (file, input_file, file_id) และ input เอกสารที่ไม่ใช่รูปภาพ ไม่รองรับผ่าน API.
• Model field is cosmetic - field model ใน requests จะถูกยอมรับ แต่ model LLM จริงที่ใช้จะถูกกำหนดค่าฝั่งเซิร์ฟเวอร์ใน config.yaml.

Proxy Mode

API server ยังทำหน้าที่เป็น backend สำหรับ gateway proxy mode ด้วย เมื่อ instance ของ Hermes gateway อื่นถูกกำหนดค่าด้วย GATEWAY_PROXY_URL ชี้มาที่ API server นี้ มันจะส่งต่อข้อความทั้งหมดมาที่นี่แทนการรัน agent ของตัวเอง วิธีนี้ช่วยให้สามารถ deploy แบบแยกส่วนได้ - ตัวอย่างเช่น Docker container ที่จัดการ Matrix E2EE ที่ส่งต่อ (relays) ไปยัง agent ฝั่ง host

ดู Matrix Proxy Mode สำหรับคู่มือการตั้งค่าทั้งหมด

📄 user-guide/features/batch-processing.md

sidebar_position: 12 title: "Batch Processing" description: "Generate agent trajectories at scale - parallel processing, checkpointing, and toolset distributions"

Batch Processing

Batch processing ช่วยให้คุณสามารถรัน agent Hermes ผ่าน prompt หลายร้อยหรือหลายพันรายการแบบขนาน (parallel) เพื่อสร้างข้อมูล trajectory ที่มีโครงสร้าง ข้อมูลนี้ใช้หลักๆ สำหรับ การสร้างข้อมูลสำหรับฝึกฝน (training data generation) - เพื่อสร้าง trajectory ในรูปแบบ ShareGPT พร้อมสถิติการใช้เครื่องมือ (tool usage statistics) ซึ่งสามารถนำไปใช้สำหรับการ fine-tuning หรือการประเมินผลได้

Overview

batch runner (batch_runner.py) จะประมวลผลชุดข้อมูล prompt ในรูปแบบ JSONL โดยรันแต่ละ prompt ผ่าน agent session แบบเต็มรูปแบบพร้อมการเข้าถึง tool แต่ละ prompt จะได้รับ environment ที่แยกออกมาโดยเฉพาะ ผลลัพธ์ที่ได้คือข้อมูล trajectory ที่มีโครงสร้าง ซึ่งประกอบด้วยประวัติการสนทนาทั้งหมด, สถิติการเรียกใช้ tool, และ metrics การครอบคลุมการให้เหตุผล (reasoning coverage metrics)

Quick Start

# Basic batch run
python batch_runner.py \
    --dataset_file=data/prompts.jsonl \
    --batch_size=10 \
    --run_name=my_first_run \
    --model=anthropic/claude-sonnet-4.6 \
    --num_workers=4

# Resume an interrupted run
python batch_runner.py \
    --dataset_file=data/prompts.jsonl \
    --batch_size=10 \
    --run_name=my_first_run \
    --resume

# List available toolset distributions
python batch_runner.py --list_distributions

Dataset Format

ชุดข้อมูลอินพุตคือไฟล์ JSONL (หนึ่ง JSON object ต่อหนึ่งบรรทัด) แต่ละรายการต้องมี field ชื่อ prompt:

{"prompt": "Write a Python function that finds the longest palindromic substring"}
{"prompt": "Create a REST API endpoint for user authentication using Flask"}
{"prompt": "Debug this error: TypeError: cannot unpack non-iterable NoneType object"}

รายการสามารถรวมข้อมูลเพิ่มเติมได้ดังนี้:

• image หรือ docker_image: Container image ที่ใช้สำหรับ sandbox ของ prompt นี้ (ใช้งานได้กับ Docker, Modal, และ Singularity backends)
• cwd: การกำหนดค่า Working directory สำหรับ session terminal ของ task

Configuration Options

Provider Routing (OpenRouter)

Reasoning Control

Advanced Options

Toolset Distributions

แต่ละ prompt จะได้รับชุด toolset ที่สุ่มตัวอย่างมาจาก distribution ซึ่งช่วยให้มั่นใจได้ว่าข้อมูลสำหรับฝึกฝนจะครอบคลุมการผสมผสานของ tool ที่หลากหลาย ใช้ --list_distributions เพื่อดู distribution ทั้งหมดที่มีให้

ในการใช้งานปัจจุบัน, distributions จะกำหนดความน่าจะเป็นให้กับ toolset แต่ละตัว ตัว sampler จะสุ่ม toolset แต่ละตัวอย่างอิสระ จากนั้นจึงรับประกันว่าจะมี toolset อย่างน้อยหนึ่งตัวที่ถูกเปิดใช้งาน นี่แตกต่างจากการสร้างตารางการผสมผสานล่วงหน้าด้วยมือ

Output Format

ผลลัพธ์ทั้งหมดจะถูกบันทึกที่ data/<run_name>/:

data/my_run/
├── trajectories.jsonl    # ผลลัพธ์สุดท้ายที่รวมกัน (รวมทุก batch)
├── batch_0.jsonl         # ผลลัพธ์ของ batch แต่ละรายการ
├── batch_1.jsonl
├── ...
├── checkpoint.json       # Checkpoint สำหรับการ Resume
└── statistics.json       # สถิติการใช้ tool แบบรวม

Trajectory Format

แต่ละบรรทัดใน trajectories.jsonl คือ JSON object:

{
  "prompt_index": 42,
  "conversations": [
    {"from": "human", "value": "Write a function..."},
    {"from": "gpt", "value": "I'll create that function...",
     "tool_calls": [...]},
    {"from": "tool", "value": "..."},
    {"from": "gpt", "value": "Here's the completed function..."}
  ],
  "metadata": {
    "batch_num": 2,
    "timestamp": "2026-01-15T10:30:00",
    "model": "anthropic/claude-sonnet-4.6"
  },
  "completed": true,
  "partial": false,
  "api_calls": 3,
  "toolsets_used": ["terminal", "file"],
  "tool_stats": {
    "terminal": {"count": 2, "success": 2, "failure": 0},
    "read_file": {"count": 1, "success": 1, "failure": 0}
  },
  "tool_error_counts": {
    "terminal": 0,
    "read_file": 0
  }
}

field conversations ใช้รูปแบบคล้าย ShareGPT โดยมี field from และ value สำหรับสถิติ tool จะถูกทำให้เป็นมาตรฐาน (normalized) เพื่อรวม tool ที่เป็นไปได้ทั้งหมดพร้อมค่าเริ่มต้นเป็นศูนย์ ซึ่งช่วยให้มั่นใจได้ว่า schema จะสอดคล้องกันในทุกรายการสำหรับการเข้ากันได้กับ HuggingFace datasets

Checkpointing

batch runner มีระบบ checkpointing ที่แข็งแกร่งสำหรับการทนต่อความผิดพลาด (fault tolerance):

• Checkpoint file: ถูกบันทึกหลังจากแต่ละ batch เสร็จสมบูรณ์ โดยติดตามว่า prompt index ใดเสร็จแล้ว
• Content-based resume: เมื่อใช้ --resume, runner จะสแกนไฟล์ batch ที่มีอยู่และจับคู่ prompt ที่เสร็จสมบูรณ์โดยเนื้อหาข้อความจริง (ไม่ใช่แค่ index) ทำให้สามารถกู้คืนได้แม้ว่าลำดับของ dataset จะมีการเปลี่ยนแปลง
• Failed prompts: จะมีการทำเครื่องหมายเฉพาะ prompt ที่เสร็จสมบูรณ์เท่านั้น - prompt ที่ล้มเหลวจะถูกลองใหม่เมื่อทำการ resume
• Batch merging: เมื่อเสร็จสมบูรณ์, ไฟล์ batch ทั้งหมด (รวมถึงจาก run ก่อนหน้า) จะถูกรวมเข้าเป็น trajectories.jsonl ไฟล์เดียว

วิธีการทำงานของ Resume

1. สแกนไฟล์ batch_*.jsonl ทั้งหมดเพื่อหา prompt ที่เสร็จสมบูรณ์ (โดยการจับคู่เนื้อหา)
2. กรอง dataset เพื่อยกเว้น prompt ที่เสร็จสมบูรณ์แล้ว
3. จัดกลุ่ม prompt ที่เหลือใหม่ (Re-batch)
4. ประมวลผลเฉพาะ prompt ที่เหลือ
5. รวมไฟล์ batch ทั้งหมด (เก่า + ใหม่) เข้าเป็น output สุดท้าย

Quality Filtering

batch runner ใช้การกรองคุณภาพอัตโนมัติ:

• No-reasoning filter: ตัวอย่างที่ไม่มี assistant turns ที่มีการให้เหตุผล (ไม่มี <REASONING_SCRATCHPAD> หรือ thinking tokens แบบ native) จะถูกทิ้ง
• Corrupted entry filter: รายการที่มีชื่อ tool ที่สร้างขึ้นมาเอง (ไม่ได้อยู่ในรายการ tool ที่ถูกต้อง) จะถูกกรองออกระหว่างการรวมครั้งสุดท้าย
• Reasoning statistics: ติดตามเปอร์เซ็นต์ของ turns ที่มีการ/ไม่มีการให้เหตุผลตลอดการรัน

Statistics

หลังจากเสร็จสิ้น, runner จะแสดงสถิติที่ครอบคลุม:

• Tool usage: จำนวนครั้งที่เรียกใช้, อัตราความสำเร็จ/ความล้มเหลวต่อ tool
• Reasoning coverage: เปอร์เซ็นต์ของ assistant turns ที่มีการให้เหตุผล
• Samples discarded: จำนวนตัวอย่างที่ถูกกรองออกเนื่องจากขาดการให้เหตุผล
• Duration: เวลาประมวลผลทั้งหมด

สถิติยังถูกบันทึกใน statistics.json สำหรับการวิเคราะห์เชิงโปรแกรม (programmatic analysis)

Use Cases

Training Data Generation

สร้าง trajectories การใช้ tool ที่หลากหลายสำหรับการ fine-tuning:

python batch_runner.py \
    --dataset_file=data/coding_prompts.jsonl \
    --batch_size=20 \
    --run_name=coding_v1 \
    --model=anthropic/claude-sonnet-4.6 \
    --num_workers=8 \
    --distribution=default \
    --max_turns=15

Model Evaluation

ประเมินว่า model ใช้ tool ได้ดีเพียงใดกับ prompts มาตรฐาน:

python batch_runner.py \
    --dataset_file=data/eval_suite.jsonl \
    --batch_size=10 \
    --run_name=eval_gpt4 \
    --model=openai/gpt-4o \
    --num_workers=4 \
    --max_turns=10

Per-Prompt Container Images

สำหรับ benchmarks ที่ต้องการ environment เฉพาะ, แต่ละ prompt สามารถระบุ container image ของตัวเองได้:

{"prompt": "Install numpy and compute eigenvalues of a 3x3 matrix", "image": "python:3.11-slim"}
{"prompt": "Compile this Rust program and run it", "image": "rust:1.75"}
{"prompt": "Set up a Node.js Express server", "image": "node:20-alpine", "cwd": "/app"}

batch runner จะตรวจสอบว่า Docker images สามารถเข้าถึงได้ก่อนที่จะรันแต่ละ prompt

📄 user-guide/features/browser.md

title: Browser Automation description: Control browsers with multiple providers, local Chrome via CDP, or cloud browsers for web interaction, form filling, scraping, and more. sidebar_label: Browser sidebar_position: 5

Browser Automation

Hermes Agent มีชุดเครื่องมือสำหรับทำ browser automation อย่างครบถ้วน พร้อมตัวเลือก backend หลายรูปแบบ:

• Browserbase cloud mode ผ่าน Browserbase สำหรับ cloud browsers ที่มีการจัดการและเครื่องมือ anti-bot
• Browser Use cloud mode ผ่าน Browser Use เป็นทางเลือกของ cloud browser provider
• Firecrawl cloud mode ผ่าน Firecrawl สำหรับ cloud browsers ที่มีฟังก์ชัน scraping ในตัว
• Camofox local mode ผ่าน Camofox สำหรับการท่องเว็บแบบ anti-detection ในเครื่อง (Firefox-based fingerprint spoofing)
• Local Chrome via CDP - เชื่อมต่อเครื่องมือ browser เข้ากับ instance Chrome ของคุณโดยใช้ /browser connect
• Local browser mode ผ่าน agent-browser CLI และการติดตั้ง Chromium ในเครื่อง

ในทุกโหมด agent สามารถนำทางเว็บไซต์, โต้ตอบกับองค์ประกอบของหน้า (page elements), กรอกแบบฟอร์ม, และดึงข้อมูลได้

Overview

หน้าเว็บจะถูกแทนด้วย accessibility trees (ภาพรวมแบบ text-based) ทำให้เหมาะอย่างยิ่งสำหรับ LLM agents องค์ประกอบแบบโต้ตอบจะได้รับ ref IDs (เช่น @e1, @e2) ซึ่ง agent ใช้สำหรับการคลิกและพิมพ์

ความสามารถหลัก:

• Multi-provider cloud execution - Browserbase, Browser Use, หรือ Firecrawl - ไม่จำเป็นต้องมี local browser
• Local Chrome integration - เชื่อมต่อกับ Chrome ที่กำลังทำงานอยู่ของคุณผ่าน CDP สำหรับการท่องเว็บแบบ hands-on
• Built-in stealth - random fingerprints, CAPTCHA solving, residential proxies (Browserbase)
• Session isolation - แต่ละ task จะได้รับ browser session ของตัวเอง
• Automatic cleanup - session ที่ไม่ใช้งานจะถูกปิดหลังจากหมดเวลา
• Vision analysis - screenshot + AI analysis สำหรับความเข้าใจเชิงภาพ

Setup

:::tip Nous Subscribers หากคุณมีการสมัครสมาชิก Nous Portal แบบเสียเงิน คุณสามารถใช้ browser automation ผ่าน Tool Gateway ได้โดยไม่ต้องใช้ API keys แยกต่างหาก ให้รัน hermes model หรือ hermes tools เพื่อเปิดใช้งาน :::

Browserbase cloud mode

ในการใช้ cloud browsers ที่จัดการโดย Browserbase ให้เพิ่ม:

# Add to ~/.hermes/.env
BROWSERBASE_API_KEY=***
BROWSERBASE_PROJECT_ID=your-project-id-here

รับ credentials ของคุณได้ที่ browserbase.com.

Browser Use cloud mode

ในการใช้ Browser Use เป็น cloud browser provider ของคุณ ให้เพิ่ม:

# Add to ~/.hermes/.env
BROWSER_USE_API_KEY=***

รับ API key ของคุณได้ที่ browser-use.com. Browser Use ให้บริการ cloud browser ผ่าน REST API หากตั้งค่า credentials ทั้ง Browserbase และ Browser Use ไว้ Browserbase จะมีลำดับความสำคัญ

Firecrawl cloud mode

ในการใช้ Firecrawl เป็น cloud browser provider ของคุณ ให้เพิ่ม:

# Add to ~/.hermes/.env
FIRECRAWL_API_KEY=fc-***

รับ API key ของคุณได้ที่ firecrawl.dev. จากนั้นเลือก Firecrawl เป็น browser provider ของคุณ:

hermes setup tools
# → Browser Automation → Firecrawl

การตั้งค่าทางเลือก:

# Self-hosted Firecrawl instance (default: https://api.firecrawl.dev)
FIRECRAWL_API_URL=http://localhost:3002

# Session TTL in seconds (default: 300)
FIRECRAWL_BROWSER_TTL=600

Camofox local mode

Camofox คือ self-hosted Node.js server ที่ห่อหุ้ม Camoufox (fork ของ Firefox ที่มีการ spoofing fingerprint ด้วย C++) มันให้การท่องเว็บแบบ anti-detection ในเครื่องโดยไม่ต้องพึ่งพา cloud dependencies

# Install and run
git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install && npm start   # downloads Camoufox (~300MB) on first run

# Or via Docker
docker run -d --network host -e CAMOFOX_PORT=9377 jo-inc/camofox-browser

จากนั้นตั้งค่าใน ~/.hermes/.env:

CAMOFOX_URL=http://localhost:9377

หรือกำหนดค่าผ่าน hermes tools → Browser Automation → Camofox

เมื่อตั้งค่า CAMOFOX_URL แล้ว เครื่องมือ browser ทั้งหมดจะถูกส่งผ่าน Camofox โดยอัตโนมัติแทน Browserbase หรือ agent-browser

Persistent browser sessions

โดยค่าเริ่มต้น แต่ละ session ของ Camofox จะได้รับ identity แบบสุ่ม - cookies และ logins จะไม่คงอยู่ข้ามการ restart agent หากต้องการเปิดใช้งาน session browser แบบ persistent ให้เพิ่มสิ่งต่อไปนี้ใน ~/.hermes/config.yaml:

browser:
  camofox:
    managed_persistence: true

จากนั้นให้รีสตาร์ท Hermes อย่างสมบูรณ์เพื่อให้ config ใหม่ถูกนำไปใช้

:::warning Nested path matters Hermes จะอ่าน browser.camofox.managed_persistence ไม่ใช่ managed_persistence ระดับบนสุด ข้อผิดพลาดทั่วไปคือการเขียน:

# ❌ Wrong — Hermes ignores this
managed_persistence: true

หาก flag ถูกวางที่ path ผิด Hermes จะ fallback ไปใช้ userId แบบ ephemeral ที่สุ่มโดยอัตโนมัติ และสถานะการ login ของคุณจะหายไปในทุก session :::

What Hermes does

• ส่ง userId ที่กำหนดค่าได้ตาม profile ไปยัง Camofox เพื่อให้เซิร์ฟเวอร์สามารถใช้ profile ของ Firefox เดิมข้าม session ได้
• ข้ามการทำ context destruction ที่ฝั่งเซิร์ฟเวอร์เมื่อมีการ cleanup ทำให้ cookies และ logins คงอยู่ระหว่าง task ของ agent
• กำหนดขอบเขตของ userId ให้กับ Hermes profile ที่ใช้งานอยู่ เพื่อให้ Hermes profile ต่างกันได้รับ browser profile ที่แตกต่างกัน (profile isolation)

What Hermes does not do

• มันไม่ได้บังคับให้เกิด persistence บน Camofox server Hermes เพียงแค่ส่ง userId ที่เสถียร; เซิร์ฟเวอร์ต้องเคารพสิ่งนี้โดยการแมป userId นั้นไปยัง directory ของ Firefox profile ที่ persistent
• หาก build ของ Camofox server ของคุณถือว่าทุก request เป็น ephemeral (เช่น เรียก browser.newContext() เสมอโดยไม่โหลด profile ที่เก็บไว้) Hermes จะไม่สามารถทำให้ session เหล่านั้นคงอยู่ได้ โปรดตรวจสอบให้แน่ใจว่าคุณกำลังรัน Camofox build ที่ใช้การทำ profile persistence ตาม userId

Verify it's working

1. Start Hermes และ Camofox server ของคุณ
2. เปิด Google (หรือเว็บไซต์ที่ต้อง login ใดๆ) ใน task browser และ sign in ด้วยตนเอง
3. จบ task browser ตามปกติ
4. เริ่ม task browser ใหม่
5. เปิดเว็บไซต์เดิมอีกครั้ง - คุณควรจะยังคง sign in อยู่

หากขั้นตอนที่ 5 ทำให้คุณ log out แสดงว่า Camofox server ไม่ได้เคารพ userId ที่เสถียร ตรวจสอบ path config ของคุณอีกครั้ง ยืนยันว่าคุณรีสตาร์ท Hermes อย่างสมบูรณ์หลังจากแก้ไข config.yaml และตรวจสอบว่า Camofox server version ของคุณรองรับ persistent per-user profiles

Where state lives

Hermes ได้รับ userId ที่เสถียรจาก directory ~/.hermes/browser_auth/camofox/ ที่ scope ตาม profile (หรือเทียบเท่าภายใต้ $HERMES_HOME สำหรับ profile ที่ไม่ใช่ค่าเริ่มต้น) ข้อมูล profile browser จริงจะอยู่บน Camofox server โดยมี key คือ userId นั้น หากต้องการรีเซ็ต profile ที่ persistent อย่างสมบูรณ์ ให้ล้างข้อมูลบน Camofox server และลบ state directory ของ Hermes profile ที่เกี่ยวข้อง

VNC live view

เมื่อ Camofox ทำงานใน headed mode (พร้อมหน้าต่าง browser ที่มองเห็นได้) มันจะเปิด VNC port ใน health check response ของมัน Hermes จะค้นพบสิ่งนี้โดยอัตโนมัติและรวม VNC URL ไว้ใน navigation responses เพื่อให้ agent สามารถแชร์ลิงก์ให้คุณดู browser แบบ live ได้

Local Chrome via CDP (/browser connect)

แทนที่จะใช้ cloud provider คุณสามารถเชื่อมต่อเครื่องมือ browser ของ Hermes เข้ากับ instance Chrome ที่กำลังทำงานอยู่ของคุณผ่าน Chrome DevTools Protocol (CDP) สิ่งนี้มีประโยชน์เมื่อคุณต้องการดูว่า agent กำลังทำอะไรแบบ real-time, โต้ตอบกับหน้าเว็บที่ต้องใช้ cookies/sessions ของคุณเอง, หรือหลีกเลี่ยงค่าใช้จ่ายของ cloud browser

:::note /browser connect เป็น interactive-CLI slash command - มันไม่ได้ถูกส่งผ่าน gateway หากคุณพยายามรันมันภายใน WebUI, Telegram, Discord, หรือ gateway chat อื่นๆ ข้อความจะถูกส่งไปยัง agent เป็น plain text และคำสั่งจะไม่ทำงาน ให้เริ่ม Hermes จาก terminal (hermes หรือ hermes chat) และใช้ /browser connect ที่นั่น :::

ใน CLI ให้ใช้:

/browser connect              # Connect to Chrome at ws://localhost:9222
/browser connect ws://host:port  # Connect to a specific CDP endpoint
/browser status               # Check current connection
/browser disconnect            # Detach and return to cloud/local mode

หาก Chrome ยังไม่ได้รันพร้อม remote debugging, Hermes จะพยายาม auto-launch มันด้วย --remote-debugging-port=9222

:::tip ในการเริ่ม Chrome ด้วยตนเองพร้อมเปิดใช้งาน CDP ให้ใช้ user-data-dir เฉพาะ เพื่อให้ debug port ทำงานได้แม้ว่า Chrome จะกำลังรันด้วย profile ปกติของคุณอยู่แล้ว:

# Linux
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=$HOME/.hermes/chrome-debug \
  --no-first-run \
  --no-default-browser-check &

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.hermes/chrome-debug" \
  --no-first-run \
  --no-default-browser-check &

จากนั้นเปิด Hermes CLI และรัน /browser connect

Why --user-data-dir? หากไม่มีสิ่งนี้ การเปิด Chrome ในขณะที่ Chrome instance ปกติกำลังทำงานอยู่ มักจะเปิดหน้าต่างใหม่บน process ที่มีอยู่ - และ process ที่มีอยู่ไม่ได้เริ่มต้นด้วย --remote-debugging-port ดังนั้น port 9222 จึงไม่เปิด user-data-dir เฉพาะจะบังคับให้เกิด Chrome process ใหม่ที่ debug port สามารถรับฟังได้ --no-first-run --no-default-browser-check จะข้าม wizard การเปิดครั้งแรกสำหรับ profile ใหม่ :::

เมื่อเชื่อมต่อผ่าน CDP, เครื่องมือ browser ทั้งหมด (browser_navigate, browser_click, ฯลฯ) จะทำงานบน live Chrome instance ของคุณแทนการสร้าง cloud session

Local browser mode

หากคุณไม่ได้ตั้งค่า cloud credentials ใดๆ และไม่ได้ใช้ /browser connect, Hermes ยังสามารถใช้ browser tools ผ่านการติดตั้ง Chromium ในเครื่องที่ขับเคลื่อนโดย agent-browser

Optional Environment Variables

# Residential proxies for better CAPTCHA solving (default: "true")
BROWSERBASE_PROXIES=true

# Advanced stealth with custom Chromium — requires Scale Plan (default: "false")
BROWSERBASE_ADVANCED_STEALTH=false

# Session reconnection after disconnects — requires paid plan (default: "true")
BROWSERBASE_KEEP_ALIVE=true

# Custom session timeout in milliseconds (default: project default)
# Examples: 600000 (10min), 1800000 (30min)
BROWSERBASE_SESSION_TIMEOUT=600000

# Inactivity timeout before auto-cleanup in seconds (default: 120)
BROWSER_INACTIVITY_TIMEOUT=120

Install agent-browser CLI

npm install -g agent-browser
# Or install locally in the repo:
npm install

:::info เครื่องมือ browser ต้องถูกรวมอยู่ในรายการ toolsets ของ config หรือเปิดใช้งานผ่าน hermes config set toolsets '["hermes-cli", "browser"]' :::

Available Tools

browser_navigate

นำทางไปยัง URL ต้องเรียกใช้ก่อนเครื่องมือ browser อื่นๆ ทั้งหมด เป็นการเริ่มต้น session ของ Browserbase

Navigate to https://github.com/NousResearch

:::tip สำหรับการดึงข้อมูลแบบง่าย ให้ใช้ web_search หรือ web_extract - พวกมันเร็วกว่าและถูกกว่า ใช้เครื่องมือ browser เมื่อคุณต้องการ โต้ตอบ กับหน้าเว็บ (คลิกปุ่ม, กรอกแบบฟอร์ม, จัดการเนื้อหาแบบ dynamic) :::

browser_snapshot

รับ snapshot แบบ text-based ของ accessibility tree ของหน้าปัจจุบัน คืนค่าองค์ประกอบแบบโต้ตอบพร้อม ref IDs เช่น @e1, @e2 สำหรับใช้กับ browser_click และ browser_type

• full=false (default): มุมมองแบบกระชับที่แสดงเฉพาะองค์ประกอบแบบโต้ตอบ
• full=true: เนื้อหาหน้าเว็บที่สมบูรณ์

Snapshot ที่มีขนาดเกิน 8000 characters จะถูก LLM สรุปโดยอัตโนมัติ

browser_click

คลิกองค์ประกอบที่ระบุด้วย ref ID จาก snapshot

Click @e5 to press the "Sign In" button

browser_type

พิมพ์ข้อความลงในช่อง input field ล้างช่องก่อน จากนั้นจึงพิมพ์ข้อความใหม่

Type "hermes agent" into the search field @e3

browser_scroll

เลื่อนหน้าขึ้นหรือลงเพื่อเปิดเผยเนื้อหาเพิ่มเติม

Scroll down to see more results

browser_press

กดปุ่มคีย์บอร์ด มีประโยชน์สำหรับการส่งแบบฟอร์มหรือการนำทาง

Press Enter to submit the form

คีย์ที่รองรับ: Enter, Tab, Escape, ArrowDown, ArrowUp, และอื่นๆ

browser_back

นำทางกลับไปยังหน้าก่อนหน้าใน browser history

browser_get_images

แสดงรายการรูปภาพทั้งหมดบนหน้าปัจจุบันพร้อม URL และ alt text มีประโยชน์สำหรับการค้นหารูปภาพเพื่อวิเคราะห์

browser_vision

ถ่าย screenshot และวิเคราะห์ด้วย vision AI ใช้สิ่งนี้เมื่อ text snapshots ไม่สามารถจับภาพข้อมูลภาพที่สำคัญได้ - มีประโยชน์อย่างยิ่งสำหรับ CAPTCHAs, layout ที่ซับซ้อน, หรือการตรวจสอบด้วยภาพ

Screenshot จะถูกบันทึกอย่างถาวรและคืนค่า file path พร้อมกับการวิเคราะห์ AI บน messaging platforms (Telegram, Discord, Slack, WhatsApp) คุณสามารถขอให้ agent แชร์ screenshot ได้ - มันจะถูกส่งเป็น native photo attachment ผ่านกลไก MEDIA:

What does the chart on this page show?

Screenshots ถูกจัดเก็บใน ~/.hermes/cache/screenshots/ และถูกล้างโดยอัตโนมัติหลังจาก 24 ชั่วโมง

browser_console

รับ output ของ browser console (log/warn/error messages) และ uncaught JavaScript exceptions จากหน้าปัจจุบัน จำเป็นสำหรับการตรวจจับ JS errors แบบเงียบๆ ที่ไม่ปรากฏใน accessibility tree

Check the browser console for any JavaScript errors

ใช้ clear=True เพื่อล้าง console หลังจากอ่าน เพื่อให้การเรียกใช้ครั้งต่อไปแสดงเฉพาะข้อความใหม่

browser_cdp

Raw Chrome DevTools Protocol passthrough - ช่องทางหลบหนีสำหรับ operations browser ที่ไม่ได้ครอบคลุมโดยเครื่องมืออื่น ใช้สำหรับการจัดการ native dialog, iframe-scoped evaluation, cookie/network control, หรือ CDP verb ใดๆ ที่ agent ต้องการ

มีให้ใช้เฉพาะเมื่อ CDP endpoint สามารถเข้าถึงได้เมื่อเริ่ม session - หมายความว่า /browser connect ได้เชื่อมต่อกับ Chrome ที่กำลังทำงานอยู่ หรือ browser.cdp_url ถูกตั้งค่าใน config.yaml โดยค่าเริ่มต้นของ local agent-browser mode, Camofox, และ cloud providers (Browserbase, Browser Use, Firecrawl) ยังไม่ได้เปิดเผย CDP ให้กับเครื่องมือนี้ - cloud providers มี CDP URLs ต่อ session แต่ live-session routing เป็นสิ่งที่ต้องทำต่อไป

CDP method reference: https://chromedevtools.github.io/devtools-protocol/ - agent สามารถ web_extract หน้าของ method เฉพาะเพื่อค้นหา parameters และ return shape

รูปแบบทั่วไป:

# List tabs (browser-level, no target_id)
browser_cdp(method="Target.getTargets")

# Handle a native JS dialog on a tab
browser_cdp(method="Page.handleJavaScriptDialog",
            params={"accept": true, "promptText": ""},
            target_id="<tabId>")

# Evaluate JS in a specific tab
browser_cdp(method="Runtime.evaluate",
            params={"expression": "document.title", "returnByValue": true},
            target_id="<tabId>")

# Get all cookies
browser_cdp(method="Network.getAllCookies")

Browser-level methods (Target.*, Browser.*, Storage.*) จะไม่มี target_id methods ระดับหน้า (Page.*, Runtime.*, DOM.*, Emulation.*) ต้องการ target_id จาก Target.getTargets แต่ละการเรียกใช้เป็นอิสระ - session จะไม่คงอยู่ระหว่างการเรียกใช้

Practical Examples

Filling Out a Web Form

User: Sign up for an account on example.com with my email [email protected]

Agent workflow:
1. browser_navigate("https://example.com/signup")
2. browser_snapshot()  → sees form fields with refs
3. browser_type(ref="@e3", text="[email protected]")
4. browser_type(ref="@e5", text="SecurePass123")
5. browser_click(ref="@e8")  → clicks "Create Account"
6. browser_snapshot()  → confirms success

Researching Dynamic Content

User: What are the top trending repos on GitHub right now?

Agent workflow:
1. browser_navigate("https://github.com/trending")
2. browser_snapshot(full=true)  → reads trending repo list
3. Returns formatted results

Session Recording

บันทึก session browser โดยอัตโนมัติเป็นไฟล์วิดีโอ WebM:

browser:
  record_sessions: true  # default: false

เมื่อเปิดใช้งาน การบันทึกจะเริ่มโดยอัตโนมัติในการเรียกใช้ browser_navigate ครั้งแรก และบันทึกไปยัง ~/.hermes/browser_recordings/ เมื่อ session ปิด ทำงานได้ทั้งในโหมด local และ cloud (Browserbase) การบันทึกที่เก่ากว่า 72 ชั่วโมงจะถูกล้างโดยอัตโนมัติ

Stealth Features

Browserbase ให้ความสามารถ stealth โดยอัตโนมัติ:

:::note หากคุณไม่มีฟีเจอร์แบบเสียเงินในแผนของคุณ Hermes จะ fallback โดยอัตโนมัติ - โดยการปิด keepAlive ก่อน จากนั้น proxies - เพื่อให้การท่องเว็บยังคงใช้งานได้ในแผนฟรี :::

Session Management

• แต่ละ task จะได้รับ browser session ที่ถูกแยกออกโดย Browserbase
• Session จะถูกล้างโดยอัตโนมัติหลังจากไม่มีกิจกรรม (default: 2 นาที)
• background thread จะตรวจสอบทุก 30 วินาทีสำหรับ session ที่ล้าสมัย
• การ cleanup ฉุกเฉินจะทำงานเมื่อ process ออก เพื่อป้องกัน session ที่ถูกทิ้งไว้
• Session จะถูกปล่อยผ่าน Browserbase API (REQUEST_RELEASE status)

Limitations

• Text-based interaction - อาศัย accessibility tree ไม่ใช่ pixel coordinates
• Snapshot size - หน้าเว็บขนาดใหญ่อาจถูกตัดทอนหรือถูก LLM สรุปที่ 8000 characters
• Session timeout - cloud sessions หมดอายุตามการตั้งค่าแผนของ provider ของคุณ
• Cost - cloud sessions ใช้ provider credits; session จะถูกล้างโดยอัตโนมัติเมื่อการสนทนาสิ้นสุดหรือหลังจากไม่มีกิจกรรม ใช้ /browser connect สำหรับการท่องเว็บในเครื่องฟรี
• No file downloads - ไม่สามารถดาวน์โหลดไฟล์จาก browser ได้