# Hermes Agent: คู่มือฉบับละเอียด — การใช้งาน สถาปัตยกรรม และการต่อกับ AI CLI หลายตัว > เอกสารนี้สรุปจากเอกสารทางการของ Hermes Agent (Nous Research) ณ เดือนสิงหาคม 2026 > Repo: `github.com/NousResearch/hermes-agent` · Docs: `hermes-agent.nousresearch.com/docs` · License: MIT --- ## สารบัญ 1. [Hermes Agent คืออะไร](#1-hermes-agent-คืออะไร) 2. [ติดตั้งและเริ่มใช้งาน](#2-ติดตั้งและเริ่มใช้งาน) 3. [หลักการทำงาน (Core Concepts)](#3-หลักการทำงาน-core-concepts) 4. [สถาปัตยกรรม](#4-สถาปัตยกรรม) 5. [การนำไปใช้กับ AI CLI หลายตัว](#5-การนำไปใช้กับ-ai-cli-หลายตัว) 6. [Pattern การใช้งานจริง](#6-pattern-การใช้งานจริง) 7. [ความปลอดภัยและข้อควรระวัง](#7-ความปลอดภัยและข้อควรระวัง) 8. [สรุปและอ้างอิง](#8-สรุปและอ้างอิง) --- ## 1. Hermes Agent คืออะไร Hermes Agent คือ **autonomous agent แบบ open-source (MIT)** จาก Nous Research — ทีมเดียวกับที่ทำโมเดลตระกูล Hermes, Nomos และ Psyche เปิดตัวครั้งแรก 25 กุมภาพันธ์ 2026 สิ่งที่มันไม่ใช่: - ไม่ใช่ coding copilot ที่ผูกกับ IDE - ไม่ใช่ wrapper บาง ๆ ของ API โมเดลตัวใดตัวหนึ่ง สิ่งที่มันเป็น: **long-lived process** ที่จัดการ memory ของตัวเอง เขียน skill ของตัวเอง รันเครื่องมือแบบขนาน และ "เก่งขึ้นเรื่อย ๆ ตามอายุการใช้งาน" ### 1.1 จุดขายหลัก — Closed Learning Loop นี่คือสิ่งที่แยก Hermes ออกจาก agent framework อื่น agent ส่วนใหญ่มี memory แต่ไม่มีกลไก **แปลงประสบการณ์เป็นขั้นตอนที่นำกลับมาใช้ซ้ำได้โดยอัตโนมัติ** ```mermaid flowchart TD U["ผู้ใช้สั่งงาน"] --> RUN["Agent ทำงาน
เรียก tools หลายรอบ"] RUN --> DONE["จบ turn"] DONE --> REVIEW["Background Review
ประเมินผลลัพธ์"] REVIEW --> Q{"ได้บทเรียนอะไร?"} Q -->|"ข้อเท็จจริงสั้น ๆ ที่ต้องจำตลอด"| MEM[("MEMORY.md
USER.md")] Q -->|"ขั้นตอนหลายสเต็ปที่ทำซ้ำได้"| SKILL[("SKILL.md
procedural memory")] Q -->|"ไม่มีอะไรใหม่"| SKIP["ข้าม"] MEM --> NEXT["Session ถัดไป
โหลดเข้า system prompt"] SKILL --> NEXT SKIP --> NEXT NEXT --> RUN N>"Review ใช้โมเดลหลักโดย default
สลับไปโมเดลถูกกว่าได้ผ่าน auxiliary.background_review"] REVIEW -.-> N ``` องค์ประกอบของ loop นี้: | องค์ประกอบ | หน้าที่ | |---|---| | **Agent-curated memory** | `MEMORY.md` + `USER.md` ที่ agent เขียนเอง มี character limit บังคับให้กระชับ | | **Autonomous skill creation** | เจอ workflow ที่ไม่ trivial → บันทึกเป็น `SKILL.md` ผ่าน `skill_manage` | | **Skill self-improvement** | ใช้ skill แล้วเจอจุดพลาด → patch ตัว skill ระหว่างใช้งาน | | **FTS5 cross-session recall** | ทุก session เก็บใน SQLite + full-text search ค้นบทสนทนาเก่าได้ | | **Honcho dialectic user modeling** | (optional) สร้างโมเดลผู้ใช้ข้ามเซสชัน | ### 1.2 คุณสมบัติเด่นอื่น ๆ - **รันได้ทุกที่** — terminal backend 6–7 แบบ: local, Docker, SSH, Daytona, Singularity, Modal, Vercel Sandbox โดย Daytona/Modal มี serverless persistence (hibernate ตอน idle แทบไม่เสียเงิน) - **อยู่ทุกที่ที่คุณอยู่** — gateway เดียวรองรับ 20+ แพลตฟอร์ม: CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, LINE, DingTalk, Feishu, WeCom, Teams, Google Chat, Home Assistant ฯลฯ - **Model-agnostic จริง ๆ** — 18+ provider families, ใช้ Nous Portal, OpenRouter, Anthropic native, Codex, Kimi, หรือ endpoint OpenAI-compatible อะไรก็ได้ - **Skills เป็นมาตรฐานเปิด** — compatible กับ `agentskills.io` แชร์และติดตั้งข้ามเครื่องมือได้ - **MCP support** — ต่อ MCP server ใดก็ได้ ทั้ง stdio และ SSE - **Cron ในตัว** — งานตามตารางที่ส่งผลลัพธ์เข้าแพลตฟอร์มไหนก็ได้ - **Research-ready** — batch processing, trajectory export (ShareGPT format), RL training ผ่าน Atropos --- ## 2. ติดตั้งและเริ่มใช้งาน ### 2.1 ติดตั้ง ```bash # Linux / macOS / WSL2 / Android (Termux) — installer ตรวจ Termux อัตโนมัติ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash # reload shell source ~/.bashrc # หรือ ~/.zshrc ``` ```powershell # Windows native (ไม่ต้อง WSL) — ติดตั้ง uv, Python 3.11, Node.js, ripgrep, ffmpeg # และ portable Git Bash (MinGit) ลง %LOCALAPPDATA%\hermes\git โดยไม่ต้องใช้สิทธิ์ admin iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` บน macOS/Windows ถ้าอยากได้ GUI ด้วย ให้โหลด **Hermes Desktop installer** จากเว็บ ซึ่งจะติดตั้งทั้ง CLI และแอป desktop ให้ ถ้าอยากได้ profile ที่ไม่มี bundled skill ติดมาเลย: ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --no-skills ``` ### 2.2 เลือก Provider ขั้นตอนที่สำคัญที่สุด ถ้าตรงนี้ผิด ทุกอย่างหลังจากนี้พังหมด ```bash hermes setup --portal # ทางลัด: OAuth ครั้งเดียวได้ทั้งโมเดล + Tool Gateway hermes model # wizard เต็ม: เพิ่ม provider, OAuth, ใส่ API key, ตั้ง endpoint hermes setup # wizard ครอบคลุมทุกอย่าง ``` `hermes setup` บนเครื่องใหม่มี 3 โหมด: | โหมด | ได้อะไร | |---|---| | **Quick Setup (Nous Portal)** | OAuth ฟรี ไม่ต้องมี API key ได้โมเดล + Tool Gateway (web search, image gen, TTS, browser) | | **Full Setup** | เดินผ่านทุก provider/tool/option เอง (bring your own keys) | | **Blank Slate** | ปิดทุกอย่างเหลือขั้นต่ำ: provider+model, File Operations, Terminal เท่านั้น ไม่มี web/browser/code exec/vision/memory/delegation/cron/skills/plugins/MCP | > **Blank Slate** เขียน `platform_toolsets.cli` + `agent.disabled_toolsets` แบบชัดเจน ดังนั้นของที่ไม่ได้เลือกจะไม่โผล่มาแม้หลัง `hermes update` — เหมาะกับสภาพแวดล้อมที่ต้องคุมพื้นที่โจมตี **ข้อกำหนดสำคัญ: context อย่างน้อย 64,000 tokens** โมเดลที่ context เล็กกว่านี้จะถูกปฏิเสธตั้งแต่ startup เพราะ system prompt + tool schemas อย่างเดียวก็กิน 4k–8k tokens แล้ว ### 2.3 config เก็บที่ไหน Hermes แยก secret ออกจาก config ปกติ: ```mermaid flowchart LR subgraph HOME["$HERMES_HOME เช่น ~/.hermes"] ENV[".env
secrets, tokens, API keys"] CFG["config.yaml
non-secret settings"] AUTH["auth.json
OAuth credentials"] DB[("state.db
SQLite + FTS5")] MEMD["memories/
MEMORY.md, USER.md"] SK["skills/"] BUN["skill-bundles/"] PL["plugins/"] end CLI["hermes CLI"] --> HOME GW["hermes gateway"] --> HOME ACP["hermes acp"] --> HOME CRON["cron scheduler"] --> HOME N>"แต่ละ profile มี HERMES_HOME แยกกันทั้งก้อน
hermes -p research จะไม่ปนกับ default"] HOME -.-> N ``` วิธีที่ปลอดภัยที่สุดคือให้ CLI จัดการเอง มันจะเลือกไฟล์ปลายทางถูกต้องให้: ```bash hermes config set model anthropic/claude-opus-4.6 hermes config set terminal.backend docker hermes config set OPENROUTER_API_KEY sk-or-... ``` ### 2.4 คำสั่งที่ใช้บ่อย | คำสั่ง | หน้าที่ | |---|---| | `hermes` | เริ่มคุย (classic CLI) | | `hermes --tui` | TUI รุ่นใหม่ มี modal overlay, mouse selection, non-blocking input | | `hermes -c` / `--continue` | resume session ล่าสุด | | `hermes model` | wizard เลือก provider/model (นอก session) | | `hermes tools` | เปิด/ปิด toolset ต่อแพลตฟอร์ม | | `hermes skills browse\|search\|install` | จัดการ Skills Hub | | `hermes gateway` | สตาร์ท messaging gateway | | `hermes acp` | รันเป็น ACP server ให้ editor ต่อ | | `hermes doctor` | วินิจฉัยปัญหา config | | `hermes sessions list` | ดู session ย้อนหลัง | | `hermes journey` | timeline ของทุกอย่างที่ agent เรียนรู้ | | `hermes backup` | ย้ายทั้ง setup ไปเครื่องอื่น | | `hermes update` | อัปเดตเวอร์ชัน | Slash command ที่ใช้ในเซสชัน (ใช้ได้ทั้ง CLI และทุกแพลตฟอร์ม gateway): ```text /help /tools /model /save /resume /stop /skills /bundles /learn /plan /journey /memory pending /memory approve /memory reject /skills pending /skills diff /skills approve ``` ### 2.5 Recovery Toolkit เวลารู้สึกว่า "มันแปลก ๆ" ให้ไล่ตามลำดับนี้: ```text 1. hermes doctor 2. hermes model 3. hermes setup 4. hermes sessions list 5. hermes --continue 6. hermes gateway status ``` **กฎเหล็ก:** ถ้า Hermes ยังคุยธรรมดาไม่จบ อย่าเพิ่งเพิ่ม gateway / cron / voice / routing ทำให้ conversation เดียวสะอาดก่อน แล้วค่อยซ้อนชั้น ปัญหาที่กินเวลามากที่สุด: | อาการ | สาเหตุที่น่าจะเป็น | วิธีแก้ | |---|---|---| | เปิดได้แต่ตอบว่าง/พัง | provider auth หรือ model ผิด | `hermes model` ใหม่ | | custom endpoint "ทำงาน" แต่ตอบมั่ว | base URL / model name ผิด หรือไม่ใช่ OpenAI-compatible จริง | ทดสอบ endpoint ด้วย client อื่นก่อน | | tool call โผล่มาเป็นข้อความ ไม่ execute | server ไม่ได้เปิด tool calling | llama.cpp ใส่ `--jinja`, vLLM ใส่ `--enable-auto-tool-choice --tool-call-parser hermes` | | agent ลืม context / ตอบไม่ปะติดปะต่อ | context window เล็กเกิน | ตั้งอย่างน้อย 64k | | gateway สตาร์ทแต่ไม่มีใครส่งข้อความได้ | bot token / allowlist ไม่ครบ | `hermes gateway setup` + `hermes gateway status` | --- ## 3. หลักการทำงาน (Core Concepts) ### 3.1 Turn Lifecycle — วงจรหนึ่งรอบของ agent หัวใจคือคลาส `AIAgent` ใน `run_agent.py` ทุก entry point (CLI, gateway, ACP, batch, API server) วิ่งผ่านคลาสนี้เหมือนกันหมด ```mermaid sequenceDiagram autonumber participant U as User participant A as AIAgent participant PB as prompt_builder participant RP as runtime_provider participant LLM as Provider API participant TR as Tool Registry U->>A: run_conversation A->>A: gen task_id + append user message A->>PB: build_system_prompt PB-->>A: stable + context + volatile tiers A->>A: preflight compression ถ้าเกิน 50% context A->>RP: resolve_runtime_provider RP-->>A: api_mode, base_url, api_key loop จนกว่าจะได้ text response A->>A: แปลง history ตาม api_mode A->>A: inject ephemeral layers + cache markers A->>LLM: interruptible API call LLM-->>A: response alt มี tool_calls A->>TR: dispatch tools Note over TR: 1 tool = main thread
หลาย tool = ThreadPoolExecutor
tool แบบ interactive บังคับ sequential TR-->>A: tool results เรียงตามลำดับเดิม else เป็น text A->>A: persist session + flush memory A-->>U: final response end end ``` จุดสำคัญของ loop นี้: - **Interruptible** — HTTP call วิ่งใน background thread ส่วน main thread รอ 3 อย่างพร้อมกัน: response พร้อม / interrupt event / timeout ถ้าโดน interrupt จะทิ้ง thread นั้นและไม่ยัด partial response เข้า history - **Message alternation เข้มงวด** — `User → Assistant → User → ...` ห้าม assistant ติดกัน ห้าม user ติดกัน มีแต่ role `tool` เท่านั้นที่ติดกันได้ (parallel tool results) - **Iteration budget** — default 500 รอบ (`agent.max_turns`) subagent ได้ budget แยก cap ที่ `delegation.max_iterations` (default 50) - **Agent-level tools** — `todo`, `memory`, `session_search`, `delegate_task` ถูกดักที่ `run_agent.py` ก่อนถึง registry เพราะแก้ state ของ agent โดยตรง ### 3.2 API Modes Hermes รองรับ 3 โหมดการคุยกับ provider แล้ว **converge เข้า internal message format เดียวกัน** (OpenAI-style dict) ทั้งก่อนและหลัง API call | API mode | ใช้กับ | Client | |---|---|---| | `chat_completions` | OpenAI-compatible ทั่วไป (OpenRouter, custom, ส่วนใหญ่) | `openai.OpenAI` | | `codex_responses` | OpenAI Codex / Responses API, xAI Grok | `openai.OpenAI` แบบ Responses format | | `anthropic_messages` | Anthropic Messages API แท้ | `anthropic.Anthropic` ผ่าน adapter | ลำดับการตัดสิน mode: ```mermaid flowchart TD START["เริ่ม resolve"] --> A1{"มี api_mode
ใน constructor?"} A1 -->|"มี"| USE["ใช้ค่านั้น"] A1 -->|"ไม่มี"| A2{"provider บอกได้ไหม?"} A2 -->|"provider = anthropic"| ANT["anthropic_messages"] A2 -->|"provider = openai-codex"| CDX["codex_responses"] A2 -->|"ไม่ชัด"| A3{"base_url บอกได้ไหม?"} A3 -->|"api.anthropic.com"| ANT A3 -->|"ลงท้าย /anthropic"| ANT A3 -->|"ไม่ชัด"| DEF["chat_completions
ค่า default"] ``` ### 3.3 Persistent Memory Memory มี 2 ไฟล์ เก็บที่ `~/.hermes/memories/` และมี **character limit บังคับ** | ไฟล์ | เก็บอะไร | Limit | |---|---|---| | `MEMORY.md` | โน้ตของ agent เอง — environment, convention, บทเรียน | 2,200 chars (~800 tokens) | | `USER.md` | โปรไฟล์ผู้ใช้ — preference, communication style | 1,375 chars (~500 tokens) | **Frozen snapshot pattern** — memory ถูกโหลดเข้า system prompt ครั้งเดียวตอนเริ่ม session แล้วไม่เปลี่ยนอีกจนจบ เพื่อรักษา prefix cache ของ LLM ถ้า agent เขียน memory ระหว่างทาง จะลงดิสก์ทันทีแต่จะเห็นใน system prompt ตอน session ถัดไป (tool response แสดง live state เสมอ) **ไม่มี auto-compact** — เขียนเกิน limit แล้ว tool จะ error กลับมาพร้อมรายการ entry ปัจจุบัน agent ต้องจัดการเองในเทิร์นเดียวกัน: `replace` รวม entry ที่ซ้อนกัน หรือ `remove` ของเก่า แล้วค่อย `add` ใหม่ Action ที่มี: `add`, `replace`, `remove` — ไม่มี `read` เพราะเนื้อหาอยู่ใน system prompt อยู่แล้ว `replace`/`remove` ใช้ substring matching แค่ต้อง unique พอ ตัวอย่าง entry ที่ดี (แน่นข้อมูล ไม่เยิ่นเย้อ): ```text Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions. The staging server 10.0.1.50 needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519. ``` **Security scanning** — ทุก entry ถูกสแกนหา prompt injection, credential exfiltration, SSH backdoor และ invisible Unicode ก่อนรับเข้า เพราะมันจะถูกยัดเข้า system prompt **Write approval gate** — ถ้าไม่ไว้ใจ background review ที่เขียน memory เอง: ```yaml memory: write_approval: true # foreground prompt inline, background/messaging = staged skills: write_approval: true # SKILL.md ใหญ่เกินอ่านในแชท จึง stage เสมอ ``` **คำเตือน:** อย่าชี้ agent สองตัวมาที่ HERMES_HOME เดียวกัน memory write เป็น automatic ทั้งคู่จะทับกันจนกลายเป็น state ที่ไม่มีใครเขียน ให้แยก profile แทน ### 3.4 Skills — Procedural Memory Skill คือ **เอกสารความรู้ที่โหลดตามต้องการ** ใช้ pattern **progressive disclosure** เพื่อประหยัด token ```mermaid flowchart TD L0["Level 0: skills_list()
ชื่อ + description + category
ราว 3k tokens อยู่ใน prompt เสมอ"] L1["Level 1: skill_view(name)
เนื้อหาเต็ม + metadata"] L2["Level 2: skill_view(name, path)
ไฟล์อ้างอิงเฉพาะเรื่อง"] L0 -->|"เมื่อ task ตรงกับ skill"| L1 L1 -->|"เมื่อต้องการรายละเอียดลึก"| L2 N>"Reference file ไม่กินอะไรจนกว่าจะถูกเรียก
ต้นทุน query จึงแปรตามคำตอบ ไม่ใช่ตามขนาดแหล่งข้อมูล"] L2 -.-> N ``` #### รูปแบบ SKILL.md ```markdown --- name: my-skill description: Brief description of what this skill does version: 1.0.0 platforms: [macos, linux] metadata: hermes: tags: [python, automation] category: devops requires_toolsets: [terminal] fallback_for_toolsets: [web] --- # Skill Title ## When to Use Trigger conditions for this skill. ## Procedure 1. Step one 2. Step two ## Pitfalls - Known failure modes and fixes ## Verification How to confirm it worked. ``` #### ลำดับความสำคัญของ skill directory ```mermaid flowchart LR P["project tier
REPO/.hermes/skills/
REPO/.agents/skills/"] -->|"ชนะ"| L["local
~/.hermes/skills/"] L -->|"ชนะ"| E["external_dirs
~/.agents/skills/ ฯลฯ"] subgraph W["การเขียน"] NEW["skill ที่ agent สร้างใหม่
ลง ~/.hermes/skills/ เสมอ"] UPD["skill ที่มีอยู่
แก้ที่ตำแหน่งเดิมที่เจอ"] end N>"project skill ถูก scan ด้วย security scanner ทุกครั้ง
verdict dangerous = quarantine ไม่เข้า index"] P -.-> N ``` การ share skill ข้ามเครื่องมือ AI หลายตัว — ตั้ง `external_dirs` ชี้ไปโฟลเดอร์กลาง: ```yaml skills: external_dirs: - ~/.agents/skills - /home/shared/team-skills - ${SKILLS_REPO}/skills ``` Repo ที่มี project skill ต้อง trust ก่อนใช้: ```bash hermes skills trust # trust repo ปัจจุบัน hermes skills untrust # ถอน ``` #### `/learn` — สร้าง skill จากแหล่งอะไรก็ได้ ```bash /learn the REST client in ~/projects/acme-sdk, focus on auth + pagination /learn https://docs.example.com/api/quickstart /learn how I just deployed the staging server /learn ~/books/designing-data-intensive-applications.pdf ``` ถ้าแหล่งข้อมูลใหญ่ (หนังสือ, spec, docs ทั้งโฟลเดอร์) agent จะสร้าง **knowledge-base skill**: `SKILL.md` บาง ๆ ที่มี mental model หลัก + index แล้วแยกไฟล์ย่อยหนึ่งไฟล์ต่อบท/หัวข้อ ไว้ใต้ `references/` การรัน `/learn` ซ้ำเรื่องเดิมจะพับรวมเข้า skill เดิม ไม่สร้างซ้ำ #### Skill Bundles รวมหลาย skill ไว้ใต้คำสั่งเดียว เก็บที่ `~/.hermes/skill-bundles/.yaml` ```yaml name: backend-dev description: Backend feature work — review, test, PR workflow. skills: - github-code-review - test-driven-development - github-pr-workflow instruction: | Always start by writing failing tests, then implement. Open the PR through the standard workflow with co-author tags. ``` เรียกด้วย `/backend-dev refactor the auth middleware` #### Skills Hub ```bash hermes skills browse --source official hermes skills search kubernetes hermes skills inspect openai/skills/k8s hermes skills install openai/skills/k8s hermes skills tap add myorg/skills-repo hermes skills check && hermes skills update ``` แหล่งที่รองรับ: `official`, `skills-sh` (Vercel), `well-known` (`/.well-known/skills/index.json`), `github` (default taps: openai, anthropics, huggingface, NVIDIA, garrytan/gstack), `clawhub`, `lobehub`, `browse-sh` (200+ site-specific browser automation), และ direct URL Trust level: `builtin` → `official` → `trusted` → `community` ทุกอันผ่าน security scanner โดย `--force` override ได้เฉพาะ finding ระดับ caution/warn แต่ **override verdict `dangerous` ไม่ได้** ### 3.5 Session Storage & Search ทุก session (CLI + messaging) เก็บใน SQLite ที่ `~/.hermes/state.db` พร้อม FTS5 full-text search | | Persistent Memory | Session Search | |---|---|---| | ความจุ | ~1,300 tokens รวม | ไม่จำกัด | | ความเร็ว | ทันที (อยู่ใน prompt) | ~20ms FTS5 query, ~1ms scroll | | ต้นทุน | token ทุก prompt | ฟรี ไม่เรียก LLM | | ใช้เมื่อ | ข้อเท็จจริงที่ต้องอยู่ใน context เสมอ | "อาทิตย์ที่แล้วเราคุยเรื่อง X ไหม" | ### 3.6 Context Compression ```mermaid flowchart TD CHK{"ตรวจขนาด conversation"} CHK -->|"เกิน 50% context
ก่อนเรียก API"| PRE["Preflight compression"] CHK -->|"เกิน 85%
ระหว่างเทิร์น gateway"| AGG["Gateway auto-compression"] CHK -->|"ยังพอ"| OK["ทำงานต่อ"] PRE --> STEP AGG --> STEP subgraph STEP["ขั้นตอนการบีบ"] direction TB S1["1. flush memory ลงดิสก์ก่อน
กันข้อมูลหาย"] S2["2. สรุปเทิร์นตรงกลางเป็น summary"] S3["3. เก็บ N ข้อความล่าสุดไว้เต็ม
compression.protect_last_n default 20"] S4["4. คู่ tool_call กับ tool_result
ไม่แยกจากกันเด็ดขาด"] S5["5. สร้าง session lineage ID ใหม่
เป็น child session"] S1 --> S2 --> S3 --> S4 --> S5 end ``` ### 3.7 Delegation & Subagents Hermes สร้าง subagent แบบ isolated ที่มี conversation, terminal และ Python RPC ของตัวเอง แล้วส่งกลับมาแค่ **final summary** ทำให้ context ของ parent ไม่บวม — เหมาะกับโมเดล local ที่ context เล็ก ตั้งแต่มี `async_delegation` toolset การ delegate ไม่ block chat หลักอีกต่อไป: `delegate` คืน `task_id` ทันที แล้วมี tool ครบ lifecycle — spawn, check, steer, collect, cancel, list ```mermaid flowchart TD P["Parent Agent"] -->|"delegate_task"| T1["Subagent A
context + tools แยก"] P -->|"delegate_task"| T2["Subagent B"] P -->|"delegate_task"| T3["Subagent C"] T1 -->|"final summary เท่านั้น"| P T2 -->|"final summary เท่านั้น"| P T3 -->|"final summary เท่านั้น"| P N>"subagent สืบทอด provider ของ parent
แต่ไม่สืบทอด fallback config"] T1 -.-> N ``` นอกจากนี้ยังมี **Programmatic Tool Calling** ผ่าน `execute_code` ที่ยุบ pipeline หลายสเต็ปให้เหลือ inference call เดียว ### 3.8 Cron Cron ของ Hermes เป็น **agent task ไม่ใช่ shell task** เก็บใน JSON แนบ skill/script ได้ และส่งผลลัพธ์ไปแพลตฟอร์มไหนก็ได้ ```text Scheduler tick → โหลด job ที่ถึงกำหนดจาก jobs.json → สร้าง AIAgent ใหม่ (ไม่มี history) → inject skill ที่แนบไว้เป็น context → รัน job prompt → ส่งผลไปแพลตฟอร์มปลายทาง → อัปเดต state + next_run ``` Cron **รองรับ fallback provider** เหมือน gateway และสืบทอด trust decision ของ project skill จากที่คุณตัดสินใจไว้ตอน interactive (ไม่ prompt เอง ไม่ auto-trust เอง) --- ## 4. สถาปัตยกรรม ### 4.1 System Overview ```mermaid flowchart TD subgraph EP["Entry Points"] direction LR E1["CLI
cli.py"] E2["Gateway
gateway/run.py"] E3["ACP
acp_adapter/"] E4["Batch Runner
batch_runner.py"] E5["API Server"] E6["Python Library"] end subgraph CORE["AIAgent — run_agent.py"] direction TB C1["Prompt Builder
prompt_builder.py"] C2["Provider Resolution
runtime_provider.py"] C3["Tool Dispatch
model_tools.py"] C4["Compression + Caching
context_compressor.py
prompt_caching.py"] C5["3 API Modes
chat_completions
codex_responses
anthropic_messages"] C6["Tool Registry
registry.py
70+ tools / 28 toolsets"] C1 --> C4 C2 --> C5 C3 --> C6 end subgraph PERSIST["Session Storage"] S1[("SQLite + FTS5
hermes_state.py
gateway/session.py")] end subgraph BACKENDS["Tool Backends"] direction TB B1["Terminal — 6-7 backends
local, docker, ssh,
daytona, modal, singularity"] B2["Browser — 5 backends"] B3["Web — 4 backends"] B4["MCP — dynamic"] B5["File, Vision, etc."] end EP --> CORE CORE --> PERSIST CORE --> BACKENDS ``` ### 4.2 โครงสร้างโค้ด ```text hermes-agent/ ├── run_agent.py # AIAgent — core conversation loop ├── cli.py # HermesCLI — interactive terminal UI ├── model_tools.py # tool discovery, schema collection, dispatch ├── toolsets.py # tool grouping + platform presets ├── hermes_state.py # SQLite session/state DB (FTS5) ├── hermes_constants.py # HERMES_HOME, profile-aware paths ├── batch_runner.py # batch trajectory generation │ ├── agent/ │ ├── prompt_builder.py # ประกอบ system prompt │ ├── context_engine.py # ContextEngine ABC (pluggable) │ ├── context_compressor.py # engine default — lossy summarization │ ├── prompt_caching.py # Anthropic prompt caching │ ├── auxiliary_client.py # LLM สำรองสำหรับงานข้าง ๆ │ ├── anthropic_adapter.py # แปลงฟอร์แมต Anthropic Messages │ ├── memory_manager.py # orchestrate memory │ └── trajectory.py │ ├── hermes_cli/ │ ├── main.py # ทุก subcommand ของ `hermes` │ ├── auth.py # PROVIDER_REGISTRY, resolve_provider() │ ├── runtime_provider.py # provider → api_mode + credentials │ ├── model_switch.py # /model shared logic (CLI + gateway) │ ├── setup.py # setup wizard │ ├── plugins.py # PluginManager │ └── gateway.py │ ├── tools/ │ ├── registry.py # central registry (ไม่มี dep — ทุก tool import) │ ├── approval.py # ตรวจคำสั่งอันตราย │ ├── terminal_tool.py │ ├── file_tools.py │ ├── browser_tool.py # 10 browser automation tools │ ├── code_execution_tool.py │ ├── delegate_tool.py │ ├── mcp_tool.py │ └── environments/ # terminal backends │ ├── gateway/ │ ├── run.py # GatewayRunner — message dispatch │ ├── session.py # SessionStore │ ├── pairing.py # DM pairing authorization │ ├── hooks.py │ └── platforms/ # built-in adapters │ ├── plugins/platforms/ # telegram, discord, slack, whatsapp, matrix, │ # mattermost, email, sms, line, teams ... ├── plugins/memory/ # memory provider plugins ├── plugins/context_engine/ ├── plugins/model-providers/ # per-provider plugin (api_mode, base_url, env_vars) ├── acp_adapter/ # ACP server (VS Code / Zed / JetBrains) ├── cron/ # jobs.py, scheduler.py ├── skills/ # bundled skills ├── optional-skills/ └── tests/ # ~25,000 tests / ~1,250 files ``` ### 4.3 File Dependency Chain ```mermaid flowchart BT R["tools/registry.py
ไม่มี dependency"] T["tools/*.py
เรียก registry.register() ตอน import"] M["model_tools.py
import registry + trigger discovery"] TOP["run_agent.py, cli.py,
batch_runner.py, environments/"] T --> R M --> T TOP --> M N>"tool registration เกิดตอน import
ก่อนสร้าง agent instance ใด ๆ
ไฟล์ใดใน tools/ ที่มี register() ระดับ top-level
จะถูก auto-discover — ไม่ต้องมี import list"] R -.-> N ``` ### 4.4 Data Flow — 3 เส้นทางหลัก **CLI Session** ```text User input → HermesCLI.process_input() → AIAgent.run_conversation() → prompt_builder.build_system_prompt() → runtime_provider.resolve_runtime_provider() → API call → tool_calls? → model_tools.handle_function_call() → loop → final response → display → save to SessionDB ``` **Gateway Message** ```mermaid sequenceDiagram autonumber participant PLT as Platform เช่น Telegram participant AD as Adapter participant GR as GatewayRunner participant A as AIAgent participant DL as delivery.py PLT->>AD: platform event AD->>GR: MessageEvent GR->>GR: authorize user (allowlist / DM pairing) GR->>GR: resolve session key GR->>A: สร้าง AIAgent พร้อม session history A->>A: run_conversation Note over A,GR: step_callback ส่ง progress
กลับไปเป็นข้อความในแชท A-->>GR: final response GR->>DL: deliver DL->>PLT: ส่งกลับผ่าน adapter เดิม ``` **Cron Job** — ตามที่อธิบายในหัวข้อ 3.8 ### 4.5 Prompt System System prompt ประกอบเป็นชั้น (tier) ตามลำดับตายตัว: ```mermaid flowchart TD subgraph SP["System Prompt — ประกอบครั้งเดียวต่อ session"] direction TB T1["stable
identity + tool guidance + skills index"] T2["context
context files เช่น AGENTS.md, SOUL.md"] T3["volatile
memory + profile + timestamp"] T1 --> T2 --> T3 end SP --> CACHE["prompt_caching.py
วาง cache breakpoint สำหรับ prefix caching"] CACHE --> API["ส่งเข้า API"] EPH["Ephemeral layers
budget warning, context pressure"] -.->|"inject ต่อรอบ
ไม่แตะ system prompt"| API N>"Prompt stability คือ design principle
ห้าม mutate ระหว่าง conversation
ยกเว้น user สั่ง /model เอง"] SP -.-> N ``` ### 4.6 Provider Resolution Resolver ตัวเดียวใช้ร่วมกันทั้ง CLI, gateway, cron, ACP และ auxiliary call **ลำดับความสำคัญ:** 1. คำสั่ง CLI / runtime ที่ระบุชัด 2. `config.yaml` (model/provider config) 3. environment variables 4. default ของ provider หรือ auto resolution > ลำดับนี้สำคัญ: Hermes ถือว่า model/provider ที่ save ไว้คือ source of truth เพื่อไม่ให้ `export` ค้างใน shell ไปทับ endpoint ที่ผู้ใช้เพิ่งเลือกใน `hermes model` **Output ของ resolver:** `provider`, `api_mode`, `base_url`, `api_key`, `source` และ metadata เฉพาะ provider เช่น expiry/refresh info **การป้องกัน key leak:** แต่ละ key ผูกกับ base URL ของตัวเอง — `OPENROUTER_API_KEY` ส่งเฉพาะ `openrouter.ai`, `AI_GATEWAY_API_KEY` เฉพาะ `ai-gateway.vercel.sh`, `OPENAI_API_KEY` ใช้กับ custom endpoint และเป็น fallback **การเพิ่ม provider ใหม่:** สร้าง plugin ที่ `plugins/model-providers//` หรือ `$HERMES_HOME/plugins/model-providers//` แล้วเรียก `register_provider()` — resolver จะเห็นเองโดยไม่ต้องแก้ branch ใด ๆ (user plugin override bundled ที่ชื่อซ้ำ) ### 4.7 Fallback Chain ```mermaid flowchart TD CALL["เรียก primary model"] --> ERR{"error?"} ERR -->|"ไม่"| OK["สำเร็จ"] ERR -->|"401 / 403 / 404
non-retryable"| FB ERR -->|"429 / 500 / 502 / 503
หลัง max retries"| FB ERR -->|"invalid response
หลัง max retries"| FB FB{"_try_activate_fallback"} FB -->|"activated แล้ว หรือไม่ได้ config"| FAIL["คืน error"] FB -->|"ยังไม่เคย"| SWAP subgraph SWAP["Activation"] direction TB W1["resolve_provider_client
สร้าง client ใหม่พร้อม auth"] W2["ตัดสิน api_mode ตาม provider ปลายทาง"] W3["swap in-place: model, provider,
base_url, api_mode, client"] W4["ประเมิน prompt caching ใหม่"] W5["_fallback_activated = True
reset retry count เป็น 0"] W1 --> W2 --> W3 --> W4 --> W5 end SWAP --> CALL N>"one-shot ต่อ session
subagent ไม่สืบทอด fallback
auxiliary task มี chain ของตัวเอง"] FB -.-> N ``` Config: ```yaml fallback_providers: - provider: openrouter model: anthropic/claude-sonnet-4 - provider: anthropic model: claude-sonnet-4 - provider: kimi-coding model: kimi-for-coding ``` ### 4.8 Design Principles | หลักการ | ความหมายในทางปฏิบัติ | |---|---| | **Prompt stability** | system prompt ไม่เปลี่ยนกลาง conversation ไม่มี mutation ที่ทำลาย cache ยกเว้น `/model` | | **Observable execution** | tool call ทุกครั้งผู้ใช้เห็น ผ่าน callback — spinner ใน CLI, ข้อความ progress ใน gateway | | **Interruptible** | ทั้ง API call และ tool execution ยกเลิกกลางคันได้ด้วย input ใหม่หรือ signal | | **Platform-agnostic core** | `AIAgent` คลาสเดียวรับใช้ CLI, gateway, ACP, batch, API server — ความต่างอยู่ที่ entry point | | **Loose coupling** | subsystem ที่เป็น optional (MCP, plugins, memory providers, RL env) ใช้ registry pattern + check_fn gating ไม่ hard dependency | | **Profile isolation** | `hermes -p ` ได้ HERMES_HOME/config/memory/session/gateway PID ของตัวเอง รันหลาย profile พร้อมกันได้ | --- ## 5. การนำไปใช้กับ AI CLI หลายตัว นี่คือส่วนที่คนสับสนบ่อยที่สุด เพราะ "ต่อกับ Claude / Codex / Kimi" มีความหมายได้ **4 ทิศทาง** ที่ต่างกันสิ้นเชิง ```mermaid flowchart TD subgraph A["A. Hermes เป็น Harness — ใช้โมเดลจากที่อื่น"] direction LR A1["hermes"] -->|"anthropic_messages"| A2["Claude API / Claude Code creds"] A1 -->|"codex_responses"| A3["OpenAI Codex"] A1 -->|"chat_completions"| A4["Kimi / Moonshot"] end subgraph B["B. Hermes เป็น Backend — ให้เครื่องมืออื่นเรียก"] direction LR B1["Open WebUI / LobeChat
OpenAI SDK / curl"] -->|"POST /v1/chat/completions"| B2["hermes API server
port 8642"] end subgraph C["C. Hermes เป็น Agent ใน Host อื่น — ACP"] direction LR C1["VS Code / Zed / JetBrains"] -->|"JSON-RPC over stdio"| C2["hermes acp"] end subgraph D["D. Hermes เป็น Orchestrator — เรียก CLI อื่นเป็น worker"] direction LR D1["hermes"] -->|"terminal tool"| D2["claude -p ..."] D1 -->|"terminal tool"| D3["codex exec ..."] D1 -->|"terminal tool"| D4["kimi ..."] end ``` ### 5.1 ทิศทาง A — Hermes เป็น Harness เสียบโมเดลจาก Claude / Codex / Kimi นี่คือ use case ที่ตรงไปตรงมาที่สุด และเป็นเหตุผลที่ Nous ยืนยันว่า "harness ที่ดีทำให้โมเดล open-source ใช้งานได้จริง" #### Claude / Anthropic (native) Hermes ใช้ **native Anthropic Messages API** ไม่ผ่าน OpenRouter และที่สำคัญ: **อ่าน credential ของ Claude Code ได้โดยตรง** ```bash # ทาง 1: API key (pay-per-token) export ANTHROPIC_API_KEY=*** hermes chat --provider anthropic --model claude-sonnet-4-6 # ทาง 2 (แนะนำ): ผ่าน hermes model → Anthropic OAuth # Hermes จะใช้ credential store ของ Claude Code โดยตรง แทนที่จะ copy token hermes model # ทาง 3: auto-detect — ถ้าใช้ Claude Code อยู่แล้ว hermes chat --provider anthropic ``` ```yaml model: provider: "anthropic" # alias: claude, claude-code default: "claude-sonnet-4-6" ``` **เรื่องเงินที่ต้องรู้ก่อน:** | แผน | ใช้ได้ไหม | ตัดจากอะไร | ข้อ surprise | |---|---|---|---| | Claude Max + extra usage credits | ได้ | **extra/overage credits เท่านั้น** | Max allowance พื้นฐานที่ Claude Code ใช้ ไม่ถูกแตะเลย | | Claude Pro | **ไม่ได้** | — | ดูเหมือนน่าจะใช้ได้แต่ใช้ไม่ได้ ต้องใช้ `ANTHROPIC_API_KEY` แทน | | `ANTHROPIC_API_KEY` | ได้ | pay-per-token ที่ org ของ key นั้น | ไม่ผูกกับ subscription ใด ๆ | Credential resolution ฝั่ง Anthropic ให้ความสำคัญกับ **refreshable Claude Code credentials มากกว่า env token ที่ copy มา** เพราะ token ที่ copy มาจะหมดอายุแล้ว refresh ไม่ได้ Hermes จะ preflight refresh ก่อนเรียก API และถ้าเจอ 401 จะ rebuild client แล้ว retry อีกครั้งหนึ่ง #### OpenAI Codex ```bash hermes model # → เลือก "ChatGPT or Codex Subscription" # → device code auth (เปิด URL, ใส่โค้ด) ``` - Hermes เก็บ credential ใน auth store ของตัวเองที่ `~/.hermes/auth.json` - **import credential เดิมจาก `~/.codex/auth.json` ได้** ถ้ามีอยู่แล้ว - **ไม่ต้องติดตั้ง Codex CLI** เลย - ใช้ `api_mode = codex_responses` (Responses API) ซึ่งเป็น path แยกจาก chat completions - ถ้า refresh ล้มเหลวแบบ terminal error (4xx, `invalid_grant`, revoked) Hermes จะ mark refresh token เป็น dead แล้วหยุด replay กัน error flood — แก้ด้วย `hermes auth add openai-codex` > เอกสารระบุชัดว่า **plan-quota semantics ของ Codex ยังไม่ได้ documented** — รู้แค่เรื่อง auth และ token refresh ถ้าจะใช้จริงจังต้องดู billing dashboard เอง #### Kimi / Moonshot ```bash # International — api.moonshot.ai hermes chat --provider kimi-coding --model kimi-for-coding # ต้องมี KIMI_API_KEY (หรือ KIMI_CODING_API_KEY) ใน ~/.hermes/.env # China — api.moonshot.cn hermes chat --provider kimi-coding-cn --model kimi-k2.5 # ต้องมี KIMI_CN_API_KEY # aliases: kimi-cn, moonshot-cn ``` ```yaml model: provider: "kimi-coding" default: "kimi-for-coding" ``` override base URL ได้ด้วย `KIMI_BASE_URL` และยังเข้าถึง Kimi ผ่านทางอ้อมได้อีกหลายทาง เช่น Fireworks (`accounts/fireworks/models/kimi-k2p6`), Novita (`moonshotai/kimi-k2.5`), Hugging Face router หรือ Nous Portal #### GitHub Copilot (โบนัส — เข้าถึง GPT-5.x, Claude, Gemini ด้วย sub เดียว) ```bash hermes chat --provider copilot --model gpt-5.4 ``` Auth ไล่ตามลำดับ: `COPILOT_GITHUB_TOKEN` → `GH_TOKEN` → `GITHUB_TOKEN` → `gh auth token` ถ้าไม่เจอจะเสนอ OAuth device code > **สำคัญ:** Copilot API ไม่รองรับ classic PAT (`ghp_*`) ต้องเป็น `gho_` (OAuth), `github_pat_` (fine-grained ที่มี permission **Copilot Requests**) หรือ `ghu_` (GitHub App) #### สรุปตารางเทียบ ทิศทาง A | Provider ID | api_mode | Credential | หมายเหตุ | |---|---|---|---| | `anthropic` | `anthropic_messages` | Claude Code store / OAuth / `ANTHROPIC_API_KEY` | Max + extra credits เท่านั้นสำหรับ OAuth | | `openai-codex` | `codex_responses` | device code → `~/.hermes/auth.json`, import ได้จาก `~/.codex/auth.json` | ไม่ต้องมี Codex CLI | | `kimi-coding` | `chat_completions` | `KIMI_API_KEY` | `kimi-coding-cn` สำหรับ region จีน | | `copilot` | auto (GPT-5+ ใช้ Responses) | GitHub token / OAuth | GPT-5.x, Claude, Gemini | | `copilot-acp` | ACP subprocess | `copilot login` session | spawn `copilot --acp --stdio` | | `openrouter` | `chat_completions` | `OPENROUTER_API_KEY` | routing/sorting ได้ละเอียด | | `nous` (Portal) | `chat_completions` | OAuth | 300+ models + Tool Gateway | | `custom` | ระบุเองผ่าน `transport` | อะไรก็ได้ | Ollama, vLLM, SGLang, llama.cpp, LiteLLM | #### Named Custom Providers — จัดการหลาย endpoint พร้อมกัน ```yaml providers: local: api: http://localhost:8080/v1 # ไม่มี api_key — Hermes ใช้ "no-key-required" กับ local server work: api: https://gpu-server.internal.corp/v1 key_env: CORP_API_KEY transport: chat_completions anthropic-proxy: api: https://proxy.example.com/anthropic key_env: ANTHROPIC_PROXY_KEY transport: anthropic_messages enterprise-gw: base_url: https://gateway.internal.example.com/v1 api_mode: chat_completions key_cmd: "my-auth-cli print-token --profile prod" ``` `key_cmd` แก้ปัญหา enterprise gateway ที่ออก bearer token อายุสั้น (SSO/OIDC broker, cloud IAM, internal auth proxy) — Hermes รันคำสั่ง cache ผลไว้จนใกล้หมดอายุแล้ว mint ใหม่ ใช้ได้กับ `gcloud auth print-access-token`, `az account get-access-token`, `databricks auth token`, `vault read` หรือสคริปต์แบบ `apiKeyHelper` ของ Claude Code สลับกลางเซสชันด้วย triple syntax: ```text /model custom:local:qwen-2.5 /model custom:work:llama3-70b /model custom:anthropic-proxy:claude-sonnet-4 ``` ### 5.2 ทิศทาง B — Hermes เป็น Backend ให้เครื่องมืออื่น Hermes เปิดตัวเองเป็น **OpenAI-compatible HTTP endpoint** พร้อม toolset เต็ม (terminal, file, web, memory, skills) หมายความว่าอะไรก็ตามที่พูด OpenAI format ได้ จะได้ agent ตัวเต็ม ไม่ใช่แค่โมเดล ```bash # ~/.hermes/.env API_SERVER_ENABLED=true API_SERVER_KEY=change-me-local-dev # API_SERVER_CORS_ORIGINS=http://localhost:3000 # เฉพาะเมื่อ browser ต้องเรียกตรง ``` ```bash hermes gateway # [API Server] API server listening on http://127.0.0.1:8642 ``` ```bash 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!"}]}' ``` #### Endpoint ที่มี | Endpoint | ใช้ทำอะไร | |---|---| | `POST /v1/chat/completions` | OpenAI Chat Completions — stateless, ส่ง messages เต็มทุกครั้ง | | `POST /v1/responses` | OpenAI Responses API — มี server-side state ผ่าน `previous_response_id` หรือ `conversation` | | `POST /v1/runs` | สร้าง run แล้ว subscribe progress event แทนการจัดการ stream เอง | | `GET /v1/runs/{id}/events` | SSE stream ของ tool progress, token delta, lifecycle รวม `subagent.start` / `subagent.complete` | | `POST /v1/runs/{id}/stop` | interrupt turn ที่กำลังรัน | | `POST /v1/runs/{id}/approval` | ตอบ approval ที่รออยู่ | | `GET /v1/skills`, `GET /v1/toolsets` | enumerate ความสามารถแบบ deterministic ไม่ต้องถามโมเดล | | `GET /v1/capabilities` | feature flag ให้ client ตรวจว่าเวอร์ชันนี้รองรับอะไร | | `/api/sessions/*` | CRUD + fork + chat + chat/stream ต่อ session | | `/api/jobs/*` | CRUD cron job จากระยะไกล | | `GET /health`, `GET /health/detailed` | liveness / readiness | #### เลือกโมเดลต่อ request ```json { "model": "MiniMax-M3", "provider": "minimax", "model_options": { "reasoning_effort": "high", "service_tier": "priority" }, "messages": [{"role": "user", "content": "Summarize the repo status."}] } ``` ลำดับความสำคัญ: session `/model` override → `model_routes` alias → `model`+`provider` ตรง ๆ → global default > **โดย default ค่า `model` เปล่า ๆ (ไม่มี `provider`) จะถูกเมิน** เพราะ OpenAI client ทั่วไปชอบ hardcode ชื่อโมเดล เปิดได้ด้วย `gateway.platforms.api_server.direct_model_requests: true` #### System prompt จาก frontend ถูก "ซ้อนทับ" ไม่ใช่ "แทนที่" เวลา frontend ส่ง `system` message มา Hermes จะ layer มันบนของเดิม — agent ยังคงมี tools, memory, skills ครบ #### API Server vs Subscription Proxy สองอันนี้ต่างกันมาก: | | API server (`:8642`) | Subscription proxy (`:8645`) | |---|---|---| | เสิร์ฟอะไร | **agent เต็มตัว** (toolset, memory, skills) | **raw model inference** | | ใช้เมื่อ | "อยากใช้ Hermes เป็น chat backend" | "อยากใช้ Portal sub ของฉันจากแอปอื่น" | | Auth | `API_SERVER_KEY` ของคุณ | bearer อะไรก็ได้ — proxy แนบตัวจริงให้ | | Tool calls | ใช่ agent รัน tool จริง | ไม่ — passthrough ล้วน | ```bash hermes portal # OAuth ครั้งเดียว hermes proxy start # → http://127.0.0.1:8645/v1 hermes proxy providers # ตอนนี้: nous, xai hermes proxy status ``` Proxy ทำแค่ 4 ขั้น: รับ request → หา credential ปัจจุบัน (refresh ถ้าใกล้หมดอายุ) → forward body ตรง ๆ พร้อม `Authorization: Bearer ` → stream กลับไม่แตะต้อง (SSE ยังคงสภาพ) ไม่มี transformation ไม่ log request body ไม่มี agent loop #### Multi-user ด้วย profile ```bash hermes profile create alice hermes profile create bob cat >> ~/.hermes/profiles/alice/.env < ACP มาพร้อม extras `[all]` อยู่แล้วถ้าติดตั้งด้วย curl installer Hermes ใน ACP mode ใช้ toolset ชื่อ `hermes-acp` ที่ curate มาสำหรับงาน editor โดยเฉพาะ: file tools, terminal, process, web/browser, memory, todo, session search, skills, `execute_code`, `delegate_task`, vision — **ตัด** messaging delivery และ cron management ออกเพราะไม่เข้ากับ UX ของ editor **VS Code** (ใช้ extension "ACP Client"): ```json { "acp.agents": { "Hermes Agent": { "command": "hermes", "args": ["acp"] } } } ``` **Zed:** ```json { "agent_servers": { "hermes-agent": { "type": "custom", "command": "hermes", "args": ["acp"] } } } ``` **JetBrains:** ใช้ ACP-compatible plugin แล้วชี้ไปที่ `hermes acp` หรือ `hermes-acp` **Approval ใน ACP มี 4 ระดับ:** | Option | ป้ายใน editor | ขอบเขต | persist ข้าม restart | |---|---|---|---| | `allow_once` | Allow once | tool call เดียว | ไม่ | | `allow_session` | Allow for session | ทุก call ที่ match ใน ACP session นี้ | ไม่ — ล้างเมื่อจบ session | | `allow_always` | Allow always | ทุก session ในอนาคต | ใช่ — เขียนลง permanent allowlist | | `deny` | Deny | tool call เดียว | ไม่ | แนวทางที่สมเหตุสมผล: เริ่มที่ `allow_once` สำหรับคำสั่งที่ไม่คุ้น → เลื่อนเป็น `allow_session` เมื่อเห็น pattern เดิมทำงานถูกหลายครั้ง → สงวน `allow_always` ไว้ให้คำสั่ง idempotent ที่ไว้ใจได้จริง เช่น `git status` > **ระวัง:** host มีสิทธิ์ตอบ approval request เองแบบ programmatic โดยไม่แสดงให้คนเห็น (Buzz Desktop ทำแบบนี้) ในกรณีนั้นให้ถือว่าเป็น **unattended execution** ไม่ว่าจะตั้ง `approvals` ไว้ยังไง ### 5.4 ทิศทาง D — Hermes เป็น Orchestrator เรียก CLI อื่นเป็น Worker Hermes มี `terminal` tool (7 backends) + `delegate_task` + `execute_code` ซึ่งเพียงพอจะใช้ CLI ตัวอื่นเป็น worker แบบ headless ได้เลย แนวคิด: ให้ Hermes ถือ memory/skills/orchestration ส่วน CLI ตัวอื่นทำงานที่มันเก่งเป็นพิเศษ (เช่น Claude Code กับ refactor ข้ามไฟล์, Kimi กับงาน bulk ที่ต้องการต้นทุนต่ำ) ```mermaid sequenceDiagram autonumber participant U as User participant H as Hermes Orchestrator participant S as Subagent participant T as terminal tool participant W as Worker CLI U->>H: งานใหญ่ที่แตกเป็นชิ้นได้ H->>H: อ่าน MEMORY.md + โหลด skill ที่เกี่ยวข้อง H->>H: วางแผน แตกเป็น subtask par ขนานกัน H->>S: delegate_task subtask 1 S->>T: run headless CLI T->>W: claude -p PROMPT --output-format json W-->>T: ผลลัพธ์ T-->>S: stdout S-->>H: summary เท่านั้น and H->>T: kimi -p PROMPT สำหรับงาน bulk T-->>H: stdout end H->>H: รวมผล ตรวจสอบ Note over H: background review
บันทึกสิ่งที่เรียนรู้เป็น skill H-->>U: ผลลัพธ์สุดท้าย ``` สิ่งที่ทำให้ pattern นี้ทำงานได้ดี: 1. **Subagent context isolation** — worker CLI อาจพ่น output ยาวมาก ถ้าให้ subagent เป็นตัวรับแล้วส่งกลับแค่ summary parent จะไม่บวม 2. **Env passthrough** — env var ที่ skill ประกาศไว้ (`required_environment_variables`) ถูกส่งเข้า `execute_code` และ `terminal` sandbox อัตโนมัติ worker CLI จึงเห็น key ที่ต้องใช้ สำหรับ env var ที่ไม่ได้มาจาก skill ใช้ `terminal.env_passthrough` 3. **Terminal backend เลือกได้** — สั่งให้ worker รันใน Docker หรือบน SSH host แยกได้ โดยไม่แตะเครื่อง orchestrator 4. **Approval gate** — คำสั่งที่ตรวจว่าอันตราย (`tools/approval.py`) จะเด้ง approval callback ก่อน ตัวอย่าง skill ที่ห่อ worker CLI: ```markdown --- name: kimi-bulk-worker description: Delegate bulk file transforms to the Kimi CLI version: 1.0.0 metadata: hermes: tags: [orchestration, worker] category: devops requires_toolsets: [terminal] --- # Kimi Bulk Worker ## When to Use งานที่ต้องแตะไฟล์จำนวนมากด้วย pattern เดียวกัน และไม่ต้องใช้การให้เหตุผลเชิงลึก ต้นทุนต่อไฟล์สำคัญกว่าคุณภาพสูงสุด ## Procedure 1. รวบรวมรายการไฟล์เป้าหมายด้วย `search_files` ก่อน อย่าให้ worker ค้นเอง 2. แตกเป็น batch ละไม่เกิน 20 ไฟล์ 3. เรียก worker หนึ่ง batch ต่อหนึ่ง terminal call 4. ตรวจ exit code ทุกครั้ง อย่าเชื่อ stdout อย่างเดียว 5. รัน test suite ก่อน commit เสมอ ## Pitfalls - worker CLI บางตัว buffer stdout จน timeout ให้ตั้ง timeout เผื่อไว้ - อย่าส่ง secret ผ่าน argv ใช้ env passthrough แทน ## Verification `git diff --stat` แล้วเทียบจำนวนไฟล์กับที่ตั้งใจไว้ ``` ### 5.5 เลือกทิศทางไหนดี ```mermaid flowchart TD Q1{"คุณอยากได้อะไร?"} Q1 -->|"อยากใช้ agent ของ Hermes
แต่ขับด้วยโมเดลที่ฉันจ่ายอยู่แล้ว"| A["ทิศทาง A
hermes model → เลือก provider"] Q1 -->|"มี UI/แอปอยู่แล้ว
อยากให้มันมี agent จริง ๆ"| B["ทิศทาง B
API server :8642"] Q1 -->|"อยากได้ agent ใน editor
เห็น diff เห็น terminal"| C["ทิศทาง C
hermes acp"] Q1 -->|"อยากให้ Hermes สั่ง CLI อื่น
ทำงานหนักแทน"| D["ทิศทาง D
terminal + delegate"] Q1 -->|"แค่อยากใช้ Portal sub
ในแอปอื่น ไม่ต้องการ agent"| E["Subscription proxy :8645"] A --> MIX["ผสมกันได้หมด
ทุกทิศทางใช้ config เดียวกัน"] B --> MIX C --> MIX D --> MIX E -.->|"ไม่ใช่ agent
เป็น credential passthrough"| MIX ``` --- ## 6. Pattern การใช้งานจริง ### 6.1 Always-on Ops Agent บน VPS ```mermaid flowchart LR subgraph VPS["VPS ราคาถูก"] GW["hermes gateway
systemd service"] AG["AIAgent"] DB[("state.db")] CR["cron scheduler"] GW --> AG AG --> DB CR --> AG end subgraph SURF["Surfaces"] TG["Telegram"] SL["Slack"] EM["Email"] end subgraph TARGET["ระบบที่ดูแล"] SSH1["prod server ผ่าน ssh backend"] DK["Docker containers"] end SURF <--> GW AG -->|"terminal backend = ssh"| SSH1 AG -->|"terminal backend = docker"| DK N>"คุยจาก Telegram ขณะที่ agent ทำงานบน cloud VM
ที่คุณไม่เคย SSH เข้าไปเอง"] GW -.-> N ``` Setup: ```bash hermes gateway setup # เลือกแพลตฟอร์ม ใส่ token hermes config set terminal.backend ssh # หรือ docker hermes tools # ปิด toolset ที่ไม่ต้องการ ``` ### 6.2 รายงานตามตาราง Cron job เป็น agent task เต็มตัว จึงแนบ skill เข้าไปได้: ```bash hermes cron # หรือใช้ POST /api/jobs จากระยะไกล ``` job หนึ่งจะได้ AIAgent ใหม่ที่ไม่มี history, inject skill ที่แนบไว้, รัน prompt, ส่งผลไปแพลตฟอร์มปลายทาง แล้วอัปเดต `next_run` ### 6.3 ทีมใช้ skill ร่วมกันผ่าน tap Tap คือ GitHub repo ธรรมดา ไม่ต้องมี server ไม่ต้องสมัคร registry: ```text my-org/hermes-skills └── skills/ ├── deploy-runbook/ │ └── SKILL.md ├── incident-response/ │ ├── SKILL.md │ └── references/ └── db-migration/ └── SKILL.md ``` ```bash hermes skills tap add my-org/hermes-skills hermes skills install my-org/hermes-skills/deploy-runbook ``` หรือติดตั้ง skill เดียวโดยไม่ต้อง subscribe ทั้ง repo: ```bash hermes skills install owner/repo/skills/my-workflow ``` > ถ้าเป็น private repo ต้องมี `GITHUB_TOKEN` และควรตั้งไว้อยู่ดี เพราะ GitHub API จำกัด 60 req/hr สำหรับ unauthenticated (5,000 req/hr เมื่อมี token) ### 6.4 Mixed-model fleet — ประหยัดโดยไม่ลดคุณภาพ ```yaml model: provider: anthropic default: claude-sonnet-4-6 auxiliary: background_review: provider: openrouter model: google/gemini-3-flash-preview # review บนโมเดลถูก ประหยัด 3-5 เท่า fallback_providers: - provider: kimi-coding model: kimi-for-coding - provider: openrouter model: anthropic/claude-sonnet-4 ``` Auxiliary task ที่แยก routing ได้: vision, web extraction summarization, context compression, skills hub operations, MCP helper, memory flush เมื่อ background review วิ่งบนโมเดลคนละตัวจากโมเดลหลัก มันจะ replay **digest** (เทิร์นล่าสุดแบบเต็ม + สรุปของเก่า) แทน transcript ทั้งก้อน เพราะยังไงก็ reuse prompt cache ของโมเดลหลักไม่ได้ ผลการทดสอบระบุว่า memory capture เหมือนเดิม และ skill capture ใกล้เคียงเดิม --- ## 7. ความปลอดภัยและข้อควรระวัง ```mermaid flowchart TD subgraph LAYER1["ชั้นที่ 1: พื้นผิวการโจมตี"] L1A["terminal + execute_code
= shell access เต็มรูปแบบ"] L1B["API server เปิด toolset ทั้งหมด
รวม terminal"] L1C["subscription proxy
ไม่มี auth ของตัวเอง"] end subgraph LAYER2["ชั้นที่ 2: ประตูควบคุม"] L2A["approvals — dangerous command detection"] L2B["memory.write_approval"] L2C["skills.write_approval"] L2D["API_SERVER_KEY บังคับทุก deployment"] L2E["allowlist + DM pairing บน gateway"] end subgraph LAYER3["ชั้นที่ 3: การแยกส่วน"] L3A["terminal.backend = docker / ssh"] L3B["egress credential-injection proxy"] L3C["profile isolation"] L3D["Blank Slate setup"] end LAYER1 --> LAYER2 --> LAYER3 ``` ### 7.1 ข้อควรระวังที่สำคัญที่สุด | ประเด็น | รายละเอียด | สิ่งที่ควรทำ | |---|---|---| | **API server = shell access** | endpoint ให้สิทธิ์ toolset ทั้งหมดรวม terminal | `API_SERVER_KEY` **บังคับทุก deployment** แม้ bind แค่ `127.0.0.1` และตั้ง `API_SERVER_CORS_ORIGINS` ให้แคบ | | **Subscription proxy ไม่มี auth** | รับ bearer อะไรก็ได้ ถ้า `--host 0.0.0.0` ทุกคนในเน็ตเวิร์กใช้ sub ของคุณได้ | ใช้ firewall, VPN หรือ reverse proxy ที่มี auth | | **ACP host อาจ auto-approve** | host ตอบ permission request เองได้โดยไม่แสดงให้คนเห็น | ถือว่าเป็น unattended execution เสมอ ตั้ง agent เป็น owner-only | | **agent สองตัว home เดียว** | memory write อัตโนมัติทั้งคู่ ทับกันจนเละ | แยก profile ถ้าต้อง share ให้ใช้ external memory provider | | **Project skill จาก repo แปลกหน้า** | skill คือเอกสารที่ agent ทำตาม | Hermes ไม่ auto-load ต้อง `hermes skills trust` และมี scan-time quarantine | | **Memory injection** | memory ถูกยัดเข้า system prompt | มี security scanner บล็อก prompt injection / credential exfil / invisible Unicode | | **`--force` บน skill install** | override ได้แค่ caution/warn | verdict `dangerous` block เสมอ ไม่มีทาง override | | **Multi-profile API routing** | ตั้งแต่ก.ค. 2026 key ของ default profile ใช้กับ `/p//` ไม่ได้แล้ว | ตั้ง `API_SERVER_KEY` แยกในทุก profile `.env` | ### 7.2 Sandbox ```bash hermes config set terminal.backend docker # Docker isolation hermes config set terminal.backend ssh # remote server # egress credential-injection proxy — sandbox ไม่เห็น API key จริง # เห็นแค่ opaque proxy token ที่ใช้ได้เฉพาะหลัง TLS-intercepting daemon hermes egress setup && hermes egress start ``` > ตอนนี้ egress proxy รองรับเฉพาะ Docker — Modal, SSH, Daytona, Singularity ยังไม่ต่อ ### 7.3 Advisory scan เพิ่มเติม (NVIDIA SkillEvaluator) ```bash uv tool install --python 3.13 \ "skillevaluator @ git+https://github.com/NVIDIA/SkillEvaluator.git@v0.1.0" uv tool install "git+https://github.com/NVIDIA/SkillSpector.git@v2.9.5" ``` Tier 1 เป็น deterministic + keyless: PII detection, unicode-smuggling detection, script lint, license compliance, static security scan ผลเป็น **advisory เท่านั้น** — พิมพ์ไฟล์+บรรทัดก่อนยืนยัน install แล้ว install ต่อ ปิดด้วย `skills.tier1_advisory: false` --- ## 8. สรุปและอ้างอิง ### 8.1 สรุปสั้น Hermes Agent คือ agent harness ที่ออกแบบมาให้ **โมเดลอะไรก็ได้ทำงานได้ดี** ไม่ใช่แค่โมเดล frontier ตัวแพงที่สุด จุดต่างที่แท้จริงคือ closed learning loop — memory ที่มีขอบเขตชัด + skill ที่ agent เขียนและปรับปรุงเอง + session search ที่ค้นอดีตได้ฟรี สำหรับคนที่ใช้ AI CLI หลายตัวอยู่แล้ว วิธีคิดที่ตรงที่สุดคือ **แยก "harness" ออกจาก "โมเดล"**: - อยากได้ memory/skills/gateway/cron ของ Hermes แต่ขับด้วย Claude/Codex/Kimi ที่จ่ายอยู่แล้ว → **ทิศทาง A** - มี UI อยู่แล้วอยากให้มันมี agent → **ทิศทาง B** (API server) - อยากได้ agent ใน editor → **ทิศทาง C** (ACP) - อยากให้ Hermes เป็นสมองสั่ง CLI อื่นเป็นมือ → **ทิศทาง D** (terminal + delegate) ทั้งสี่ทางใช้ config, credential, memory, skills และ state ชุดเดียวกันหมด เพราะทุก entry point วิ่งผ่าน `AIAgent` คลาสเดียว ### 8.2 Checklist เริ่มต้นแบบไม่เจ็บตัว ```text [ ] curl install → source shell [ ] hermes setup (เลือกโหมดให้ตรงกับความต้องการคุมความปลอดภัย) [ ] ตรวจว่าโมเดลมี context อย่างน้อย 64k [ ] hermes → คุยหนึ่งรอบให้จบสะอาด รวมถึงให้มันเรียก tool อย่างน้อยหนึ่งครั้ง [ ] hermes --continue → ตรวจว่า session resume ได้ [ ] hermes doctor → ไม่มี warning [ ] ค่อยเพิ่ม: gateway → skills → cron → MCP → ACP → API server [ ] ถ้าจะเปิด API server: ตั้ง API_SERVER_KEY ก่อนเสมอ [ ] ถ้าจะให้แตะ prod: terminal.backend = docker หรือ ssh + approvals ``` ### 8.3 อ้างอิง | หัวข้อ | ลิงก์ | |---|---| | Docs หลัก | `hermes-agent.nousresearch.com/docs` | | Architecture | `/docs/developer-guide/architecture` | | Agent Loop Internals | `/docs/developer-guide/agent-loop` | | Provider Runtime Resolution | `/docs/developer-guide/provider-runtime` | | AI Providers | `/docs/integrations/providers` | | Memory | `/docs/user-guide/features/memory` | | Skills | `/docs/user-guide/features/skills` | | API Server | `/docs/user-guide/features/api-server` | | Subscription Proxy | `/docs/user-guide/features/subscription-proxy` | | ACP | `/docs/user-guide/features/acp` | | MCP | `/docs/user-guide/features/mcp` | | GitHub | `github.com/NousResearch/hermes-agent` | | Skills Hub | `agentskills.io` | | machine-readable docs | `/docs/llms.txt` (~17 KB) และ `/docs/llms-full.txt` (~1.8 MB) | > เกร็ด: `/docs/llms.txt` เป็น index ย่อของทุกหน้าพร้อมคำอธิบายสั้น ขนาดปลอดภัยพอจะโหลดเข้า context ของ LLM ได้ทั้งไฟล์ ส่วน `llms-full.txt` คือทุกหน้าต่อกันเป็นไฟล์เดียวสำหรับ ingest ทีเดียวจบ ทั้งสองไฟล์ generate ใหม่ทุกครั้งที่ deploy

SECURE_ACCESS

DOWNLOAD_LOCKED

Hermes Agent

CONFIRM_DELETE