Tích hợp có lập trình

Hermes cung cấp ba giao thức để điều khiển tác nhân từ các chương trình bên ngoài - plugin IDE, giao diện người dùng tùy chỉnh, quy trình CI, tác nhân phụ được nhúng. Chọn một trong những phù hợp với vận chuyển và người tiêu dùng của bạn.

| Giao thức | Vận tải | Tốt nhất cho | Được xác định bởi | |----------|----------||----------|----------|| | ACP | JSON-RPC qua stdio | Các máy khách IDE (VS Code, Zed, JetBrains) đã sử dụng Agent CLIent Protocol |

ACP_adapter/ ` | | Cổng TUI | JSON-RPC qua stdio (hoặc WebSocket) | Máy chủ tùy chỉnh muốn kiểm soát chi tiết các phiên, lệnh gạch chéo, phê duyệt và sự kiện phát trực tuyến |

TUI_gateway/server.py ` | | Máy chủ API | Sự kiện HTTP + Máy chủ gửi | Các giao diện tương thích với OpenAI (Open WebUI, LobeChat, LibreChat…) và các ứng dụng khách web không phân biệt ngôn ngữ |

gateway/platforms/API_server.py ` |

Cả ba đều chạy cùng một lõi `AIAgent

. Chúng chỉ khác nhau ở dạng dây và bộ tính năng mà chúng thể hiện.

ACP (Giao thức máy khách đại lý)

Hermes ACP ` khởi động máy chủ JSON-RPC stdio nói ACP. Được sử dụng trong sản xuất bởi VS Code (tiện ích mở rộng ACP của Zed Industries), Zed và bất kỳ IDE JetBrains nào có plugin ACP.

Các khả năng được bộc lộ: tạo phiên, gửi lời nhắc, khối thông báo của tác nhân phát trực tuyến, sự kiện gọi công cụ, yêu cầu cấp phép, phân nhánh phiên, hủy và xác thực. Đầu ra của công cụ được hiển thị thành nội dung ACP

/
`ToolCall
` mà IDE hiểu được.

Toàn bộ vòng đời, cầu nối sự kiện và luồng phê duyệt: [ACP Internals](./ACP-internals).

`bash
Hermes ACP                  # serve ACP on stdio
Hermes ACP --bootstrap      # print install snippet for an ACP-capable IDE

`

---

## Cổng TUI JSON-RPC``TUI_gateway/server.py
` là giao thức mà Ink TUI (
`Hermes --TUI

) và cầu nối PTY của bảng điều khiển nhúng giao tiếp. Bất kỳ máy chủ bên ngoài nào cũng có thể sử dụng cùng một giao thức qua stdio (hoặc WebSocket qua 
`TUI_gateway/ws.py

).

### Danh mục phương pháp (đã chọn)

`
prompt.submit           prompt.background       session.steer
session.create          session.list            session.interrupt
session.history         session.compress        session.branch
session.title           session.usage           session.status
clarify.respond         sudo.respond            secret.respond
approval.respond        config.set / config.get commands.catalog
command.resolve         command.dispatch        CLI.exec
reload.MCP              reload.env              process.stop
delegation.status       subagent.interrupt      spawn_tree.save / list / load
terminal.resize         CLIpboard.paste         image.attach

`

### Sự kiện được phát lại``message.delta

, 
`message.complete

, 
`tool.start

, 
`tool.progress

, 
`tool.complete

, 
`approval.request

, 
`clarify.request

, 
`sudo.request

, 
`secret.request

, 
`gateway.ready

, cùng với vòng đời phiên và lỗi sự kiện.

### Ánh xạ RPC kiểu Pi

Mọi lệnh trong thông số Pi-mono RPC ([issue #360](https://GitHub.com/NousResearch/Hermes-agent/issues/360)) đều có cổng TUI tương đương:

| Lệnh Pi | Hermes tương đương |
|----------||-------------------|
| 
`prompt
` | 
`prompt.submit
` (hoặc ACP 
`session/prompt

) |
| 
`steer
` | 
`session.steer
` |
| 
`follow_up
` | 
`prompt.submit
` xếp hàng sau lượt hiện tại |
| 
`abort
` | 
`session.interrupt
` |
| 
`set_model
` | 
`command.dispatch
` dành cho 

/model &lt;provider:model>
` (giữa phiên, liên tục) |
| 
`compact
` | 
`session.compress
` |
| 
`get_state
` | 
`session.status
` |
| 
`get_messages
` | 
`session.history
` |
| 
`switch_session
` | 
`session.resume
` |
| 
`fork
` | 
`session.branch
` |
| 
`ui_request
` / 
`ui_response
` | 
`clarify.respond
` / 
`sudo.respond
` / 
`secret.respond
` / 
`approval.respond
` |

---

## Máy chủ API tương thích với OpenAI``gateway/platforms/API_server.py
` hiển thị Hermes qua HTTP cho bất kỳ khách hàng nào đã nói định dạng OpenAI. Hữu ích khi bạn muốn có giao diện người dùng web, trình chạy CI điều khiển cuộn tròn hoặc người dùng không sử dụng Python.

Điểm cuối:

`
POST /v1/chat/completions        OpenAI Chat Completions (streaming via SSE)
POST /v1/responses               OpenAI Responses API (stateful)
POST /v1/runs                    Start a run, returns run_id (202)
GET  /v1/runs/\&#123;id&#125;               Run status
GET  /v1/runs/\&#123;id&#125;/events        SSE stream of lifecycle events
POST /v1/runs/\&#123;id&#125;/approval      Resolve a pending approval
POST /v1/runs/\&#123;id&#125;/stop          Interrupt the run
GET  /v1/capabilities            Machine-readable feature flags
GET  /v1/models                  Lists Hermes-agent
GET  /health, /health/detailed

`
``Thiết lập, tiêu đề (
`X-Hermes-Session-Id

, 
`X-Hermes-Session-Key

) và nối dây giao diện người dùng: [API Server](../user-guide/features/API-server).

---

## Tôi nên sử dụng cái nào?
- **Bạn đang viết plugin IDE và IDE đã đọc ACP** → ACP. Giao thức Zero hoạt động ở phía IDE.

- **Bạn đang viết một máy chủ lưu trữ máy tính để bàn / web / TUI tùy chỉnh và muốn có mọi tính năng của Hermes** (lệnh gạch chéo, phê duyệt, làm rõ, đa tác nhân, phân nhánh phiên) → Cổng TUI JSON-RPC.
- **Bạn muốn bất kỳ giao diện người dùng nào tương thích với OpenAI, ứng dụng khách HTTP không phân biệt ngôn ngữ hoặc tự động hóa theo hướng cuộn tròn** → Máy chủ API.
- **Bạn muốn nhúng Python trong quá trình mà không có quy trình con** → nhập trực tiếp 
`run_agent.AIAgent

. Xem [Agent Loop](./agent-loop).

---

## Trao đổi nóng mô hình

Chuyển đổi mô hình giữa phiên hoạt động trên mọi bề mặt - đó là lệnh gạch chéo 

/model
` dưới mui xe.
- **CLI / TUI:** 

/model Claude-sonnet-4
` hoặc 

/model OpenRouter:Anthropic/Claude-sonnet-4.6

- **RPC cổng TUI:** 
`command.dispatch
` với 

\&#123;"command": "/model Claude-sonnet-4"&#125;

- **ACP:** IDE gửi lệnh gạch chéo dưới dạng lời nhắc; đại lý gửi nó
- **Máy chủ API:** bao gồm trường 
`model
` trong nội dung yêu cầu hoặc đặt 
`X-Hermes-Model

Độ phân giải nhận biết nhà cung cấp (cùng tên kiểu máy sẽ chọn định dạng phù hợp cho bất kỳ nhà cung cấp nào bạn đang sử dụng) được tích hợp sẵn. Xem 
`Hermes_CLI/model_switch.py

.

---

## Một lưu ý về 

--mode rpc
``Hermes không có cờ 

--mode rpc

. Ba giao thức ở trên đã bao gồm các trường hợp sử dụng — ACP cho máy khách giao thức IDE, cổng TUI cho máy chủ JSON-RPC stdio và máy chủ API cho HTTP. Nếu bạn tìm thấy một khoảng trống thực sự mà không ai trong số họ lấp đầy được, hãy giải quyết vấn đề với người tiêu dùng cụ thể mà bạn đang xây dựng.

ACP (Giao thức máy khách đại lý)​

ACP (Giao thức máy khách đại lý)