vrr/OmniRoute
2
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-04-29 06:49:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs(i18n): sync documentation updates to 32 languages

Browse source
This commit is contained in:
diegosouzapw 2026-04-18 02:51:32 -03:00
parent 857b692aac
commit e5c4e450c0
2062 changed files with 257153 additions and 64249 deletions
Download patch file Download diff file Expand all files Collapse all files

299
docs/i18n/vi/src/lib/a2a/README.md
View file

@ -4,9 +4,11 @@
---
> **Giao thức giữa tác nhân với tác nhân v0.3**— Cho phép mọi tác nhân AI sử dụng OmniRoute làm tác nhân định tuyến thông minh thông qua JSON-RPC 2.0.
> **Agent-to-Agent Protocol v0.3** — Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0.
Máy chủ A2A hiển thị OmniRoute với tư cách là**nhân viên hỗ trợ hạng nhất**mà các nhân viên khác có thể khám phá, ủy quyền nhiệm vụ và cộng tác bằng cách sử dụng [Giao thức A2A](https://google.github.io/A2A/).---
The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/).
---
## Kiến trúc
@ -41,12 +43,15 @@ Máy chủ A2A hiển thị OmniRoute với tư cách là**nhân viên hỗ tr
### Agent Discovery
Mọi tác nhân tương thích với A2A đều hiển thị**Thẻ tác nhân**tại `/.well-known/agent.json`:```bash
Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`:
```bash
curl http://localhost:20128/.well-known/agent.json
```
````
**Response:**
**Phản ứng:**```json
```json
{
"name": "OmniRoute",
"description": "Intelligent AI gateway with auto-routing across 50+ providers",
@ -83,7 +88,7 @@ curl http://localhost:20128/.well-known/agent.json
"apiKeyHeader": "Authorization"
}
}
````
```
---
@ -91,24 +96,27 @@ curl http://localhost:20128/.well-known/agent.json
### `message/send` — Synchronous Execution
Gửi tin nhắn đến một kỹ năng và nhận được phản hồi đầy đủ.```bash
Send a message to a skill and receive the complete response.
```bash
curl -X POST http://localhost:20128/a2a \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Write a Python hello world"}],
"metadata": {"model": "auto", "combo": "fast-coding"}
}
}'
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Write a Python hello world"}],
"metadata": {"model": "auto", "combo": "fast-coding"}
}
}'
```
````
**Response:**
**Phản ứng:**```json
```json
{
"jsonrpc": "2.0",
"id": "1",
@ -125,33 +133,36 @@ curl -X POST http://localhost:20128/a2a \
}
}
}
````
```
### `message/stream` — SSE Streaming
Tương tự như `message/send` nhưng trả về Sự kiện do máy chủ gửi để phát trực tuyến theo thời gian thực.```bash
Same as `message/send` but returns Server-Sent Events for real-time streaming.
```bash
curl -N -X POST http://localhost:20128/a2a \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "message/stream",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Explain quantum computing"}]
}
}'
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "message/stream",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Explain quantum computing"}]
}
}'
```
````
**SSE Events:**
**Sự kiện SSE:**```
```
data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}}
: heartbeat 2026-03-04T21:00:00Z
data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}}
````
```
### `tasks/get` — Query Task Status
@ -177,36 +188,40 @@ curl -X POST http://localhost:20128/a2a \
### `smart-routing`
Định tuyến các lời nhắc thông qua đường dẫn thông minh của OmniRoute với khả năng quan sát đầy đủ.
Routes prompts through OmniRoute's intelligent pipeline with full observability.
**Thông số (trong `siêu dữ liệu`):**
**Parameters (in `metadata`):**
| Tham số | Loại | Mặc định | Mô tả |
| ----------- | ------- | ----------------- | ------------------------------------------------------------------------------------------------ |
| `người mẫu` | `chuỗi` | `"tự động"` | Mô hình mục tiêu (ví dụ: `claude-sonnet-4`, `gpt-4o`, `auto`) |
| `kết hợp` | `chuỗi` | kết hợp hoạt động | Combo cụ thể để định tuyến |
| `ngân sách` | `số` | không | Chi phí tối đa bằng USD cho yêu cầu này |
| `role` | `chuỗi` | không | Gợi ý vai trò nhiệm vụ: `viết mã`, `đánh giá`, `lập kế hoạch`, `phân tích`, `gỡ lỗi`, `tài liệu` |
| Parameter | Type | Default | Description |
| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- |
| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) |
| `combo` | `string` | active combo | Specific combo to route through |
| `budget` | `number` | none | Maximum cost in USD for this request |
| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` |
**Trả về:**
**Returns:**
| Lĩnh vực | Mô tả |
| -------------------------------------- | ----------------------------------------------------- | ---------------------- |
| `hiện vật[].content` | Văn bản phản hồi LLM |
| `siêu dữ liệu.routing_explanation` | Giải thích dễ hiểu về quyết định định tuyến |
| `siêu dữ liệu.cost_envelope` | Ước tính so với chi phí thực tế bằng đơn vị tiền tệ |
| `siêu dữ liệu.khả năng phục hồi_trace` | Mảng sự kiện (primary*selected, fallback* Need, v.v.) |
| `siêu dữ liệu.chính sách_bản án` | Liệu yêu cầu có được cho phép hay không và tại sao | ### `quota-management` |
| Field | Description |
| ------------------------------ | --------------------------------------------------------- |
| `artifacts[].content` | The LLM response text |
| `metadata.routing_explanation` | Human-readable explanation of routing decision |
| `metadata.cost_envelope` | Estimated vs actual cost with currency |
| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) |
| `metadata.policy_verdict` | Whether the request was allowed and why |
Trả lời các truy vấn bằng ngôn ngữ tự nhiên về hạn ngạch của nhà cung cấp.
### `quota-management`
**Các loại truy vấn (suy ra từ nội dung tin nhắn):**
Answers natural-language queries about provider quotas.
| Mẫu truy vấn | Loại phản hồi |
| --------------------------------------------------------- | ------------------------------------------------------------------------------- | --- |
| Chứa `"xếp hạng"`, `"hạn ngạch nhiều nhất"`, `"tốt nhất"` | Nhà cung cấp được xếp hạng theo hạn ngạch còn lại |
| Chứa `"miễn phí"`, `"gợi ý"` | Liệt kê các combo miễn phí hoặc đề xuất các nhà cung cấp cấp miễn phí |
| Mặc định | Tóm tắt hạn ngạch đầy đủ kèm theo cảnh báo dành cho nhà cung cấp hạn ngạch thấp | --- |
**Query types (inferred from message content):**
| Query Pattern | Response Type |
| ---------------------------------------------- | -------------------------------------------------------- |
| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota |
| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers |
| Default | Full quota summary with warnings for low-quota providers |
---
## Task Lifecycle
@ -216,17 +231,19 @@ submitted ──→ working ──→ completed
──────────→ cancelled
```
| Tiểu bang | Mô tả |
| ------------ | ----------------------------------------------------------------------- |
| `đã gửi` | Tác vụ đã được tạo, xếp hàng để thực hiện |
| `làm việc` | Trình xử lý kỹ năng đang thực thi |
| `hoàn thành` | Thực hiện thành công, hiện vật có sẵn |
| `thất bại` | Thực thi không thành công hoặc tác vụ đã hết hạn (TTL: mặc định 5 phút) |
| `đã hủy` | Đã bị khách hàng hủy qua `tasks/cancel` |
| State | Description |
| ----------- | ----------------------------------------------------- |
| `submitted` | Task created, queued for execution |
| `working` | Skill handler is executing |
| `completed` | Execution succeeded, artifacts available |
| `failed` | Execution failed or task expired (TTL: 5 min default) |
| `cancelled` | Cancelled by client via `tasks/cancel` |
- Trạng thái đầu cuối: `đã hoàn thành`, `không thành công`, `đã hủy` (không có chuyển tiếp nào nữa)
- Các tác vụ đã hết hạn trong `đã gửi` hoặc `đang làm việc` được tự động đánh dấu là `không thành công`
- Các tác vụ được thu gom rác sau 2× TTL---
- Terminal states: `completed`, `failed`, `cancelled` (no further transitions)
- Expired tasks in `submitted` or `working` are auto-marked as `failed`
- Tasks are garbage-collected after 2× TTL
---
## Client Examples
@ -524,12 +541,15 @@ func main() {
### 🤖 Use Case 1: Multi-Agent Coding Pipeline
Tác nhân điều phối ủy quyền việc tạo mã cho OmniRoute, sau đó chuyển kết quả đầu ra cho tác nhân đánh giá.```python
def coding_pipeline(task: str): # Step 1: Generate code via OmniRoute A2A
code_result = a2a_send("smart-routing", [
{"role": "user", "content": f"Write production-quality code: {task}"}
], metadata={"model": "auto", "role": "coding"})
code = code_result["artifacts"][0]["content"]
An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent.
```python
def coding_pipeline(task: str):
# Step 1: Generate code via OmniRoute A2A
code_result = a2a_send("smart-routing", [
{"role": "user", "content": f"Write production-quality code: {task}"}
], metadata={"model": "auto", "role": "coding"})
code = code_result["artifacts"][0]["content"]
# Step 2: Review the code via OmniRoute A2A (different model)
review_result = a2a_send("smart-routing", [
@ -542,12 +562,13 @@ code = code_result["artifacts"][0]["content"]
print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}")
return {"code": code, "review": review}
````
```
### 💡 Use Case 2: Quota-Aware Agent Swarm
Nhiều đại lý chia sẻ hạn ngạch thông qua OmniRoute, sử dụng kỹ năng hạn ngạch để phối hợp.```python
Multiple agents share quota through OmniRoute, using the quota skill to coordinate.
```python
async def quota_aware_agent(agent_name: str, task: str):
# Check quota before starting
quota = a2a_send("quota-management", [
@ -570,30 +591,32 @@ async def quota_aware_agent(agent_name: str, task: str):
print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}")
return result
````
```
### 📊 Use Case 3: Real-Time Streaming Dashboard
Tác nhân giám sát truyền các phản hồi và hiển thị tiến trình trong thời gian thực.```typescript
A monitoring agent streams responses and displays progress in real-time.
```typescript
async function streamingDashboard(prompt: string) {
const response = await fetch(`${BASE_URL}/a2a`, {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` },
body: JSON.stringify({
jsonrpc: "2.0",
id: "dash-1",
method: "message/stream",
params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] },
}),
});
body: JSON.stringify({
jsonrpc: "2.0",
id: "dash-1",
method: "message/stream",
params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] },
}),
});
let totalChunks = 0;
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let totalChunks = 0;
const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
while (true) {
const { done, value } = await reader.read();
if (done) break;
for (const line of decoder.decode(value).split("\n")) {
if (line.startsWith("data: ")) {
@ -617,15 +640,15 @@ if (done) break;
}
}
}
}
}
}
````
```
### 🔁 Use Case 4: Task Polling Pattern
Đối với các tác vụ chạy dài, hãy thăm dò trạng thái tác vụ thay vì chờ đợi đồng bộ.```python
For long-running tasks, poll the task status instead of waiting synchronously.
```python
import time
def poll_task(task_id: str, timeout: int = 60):
@ -655,71 +678,75 @@ def poll_task(task_id: str, timeout: int = 60):
"params": {"taskId": task_id},
})
raise TimeoutError(f"Task {task_id} timed out after {timeout}s")
````
```
---
## Error Codes
| Mã | Hằng số | Ý nghĩa |
| ------ | ------------------------ | -------------------------------------------- | --- |
| -32700 | — | Lỗi phân tích cú pháp (JSON không hợp lệ) |
| -32600 | `INVALID_REQUEST` | Yêu cầu JSON-RPC không hợp lệ hoặc trái phép |
| -32601 | `PHƯƠNG PHÁP_NOT_FOUND` | Phương pháp hoặc kỹ năng không xác định |
| -32602 | `INVALID_PARAMS` | Tham số bị thiếu hoặc không hợp lệ |
| -32603 | `NỘI BỘ_ERROR` | Thực hiện kỹ năng không thành công |
| -32001 | `TASK_NOT_FOUND` | Không tìm thấy ID nhiệm vụ |
| -32002 | `TASK_ALREADY_COMPLETED` | Không thể sửa đổi một nhiệm vụ đã hoàn thành |
| -32003 | `TRÁI PHÉP` | Khóa API không hợp lệ hoặc bị thiếu |
| -32004 | `BUDGET_EXCEEDED` | Yêu cầu vượt quá ngân sách đã định cấu hình |
| -32005 | `PROVIDER_UNAVAILABLE` | Không có nhà cung cấp nào | --- |
| Code | Constant | Meaning |
| ------ | ------------------------ | ---------------------------------------- |
| -32700 | — | Parse error (invalid JSON) |
| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized |
| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill |
| -32602 | `INVALID_PARAMS` | Missing or invalid parameters |
| -32603 | `INTERNAL_ERROR` | Skill execution failed |
| -32001 | `TASK_NOT_FOUND` | Task ID not found |
| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task |
| -32003 | `UNAUTHORIZED` | Invalid or missing API key |
| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget |
| -32005 | `PROVIDER_UNAVAILABLE` | No available providers |
---
## Authentication
Tất cả các yêu cầu `/a2a` đều yêu cầu mã thông báo Bearer thông qua tiêu đề `Ủy quyền`:```
Authorization: Bearer YOUR_OMNIROUTE_API_KEY
All `/a2a` requests require a Bearer token via the `Authorization` header:
```
Authorization: Bearer YOUR_OMNIROUTE_API_KEY
```
Nếu không có khóa API nào được định cấu hình trên máy chủ (`OMNIROUTE_API_KEY` trống), xác thực sẽ bị bỏ qua.---
If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed.
---
## File Structure
```
src/lib/a2a/
├── taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup
├── taskExecution.ts # Generic task executor with state management
├── streaming.ts # SSE stream formatting, heartbeat, chunk/completion events
├── routingLogger.ts # Routing decision logger (stats, history, retention)
├── taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup
├── taskExecution.ts # Generic task executor with state management
├── streaming.ts # SSE stream formatting, heartbeat, chunk/completion events
├── routingLogger.ts # Routing decision logger (stats, history, retention)
└── skills/
├── smartRouting.ts # Smart routing skill (routes via /v1/chat/completions)
└── quotaManagement.ts # Quota management skill (natural-language quota queries)
├── smartRouting.ts # Smart routing skill (routes via /v1/chat/completions)
└── quotaManagement.ts # Quota management skill (natural-language quota queries)
src/app/a2a/
└── route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch)
└── route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch)
open-sse/mcp-server/
└── schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events)
└── schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events)
```
---
## Comparison: MCP vs A2A
| Tính năng | Máy chủ MCP | Máy chủ A2A |
| Feature | MCP Server | A2A Server |
| ----------------- | ---------------------------- | ------------------------------------------------- |
|**Giao thức**| Giao thức bối cảnh mô hình | Giao thức giữa tác nhân với tác nhân v0.3 |
|**Giao thông**| stdio / HTTP | HTTP (JSON-RPC 2.0) |
|**Khám phá**| Danh sách công cụ qua MCP | `/.well-known/agent.json` |
|**Mức độ chi tiết**| 16 công cụ riêng lẻ | 2 kỹ năng cấp cao |
|**Tốt nhất cho**| Tác nhân IDE (Con trỏ, Mã VS) | Hệ thống đa tác nhân (LangChain, CrewAI) |
|**Truyền phát**| Không được hỗ trợ | SSE qua `tin nhắn/luồng` |
|**Theo dõi nhiệm vụ**| Không | Toàn bộ vòng đời (đã gửi → đã hoàn thành) |
|**Khả năng quan sát**| Nhật ký kiểm tra mỗi cuộc gọi công cụ | Đường bao chi phí + dấu vết khả năng phục hồi + phán quyết chính sách |---
| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 |
| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) |
| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` |
| **Granularity** | 16 individual tools | 2 high-level skills |
| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) |
| **Streaming** | Not supported | SSE via `message/stream` |
| **Task tracking** | No | Full lifecycle (submitted → completed) |
| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict |
---
## Giấy phép
Một phần của [OmniRoute](https://github.com/diegosouzapw/OmniRoute) — Giấy phép MIT.
```
Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) — MIT License.