mirror of
https://github.com/katanemo/plano.git
synced 2026-04-25 00:36:34 +02:00
743d074184
Some checks are pending
CI / pre-commit (push) Waiting to run
CI / plano-tools-tests (push) Waiting to run
CI / native-smoke-test (push) Waiting to run
CI / docker-build (push) Waiting to run
CI / validate-config (push) Waiting to run
CI / security-scan (push) Blocked by required conditions
CI / test-prompt-gateway (push) Blocked by required conditions
CI / test-model-alias-routing (push) Blocked by required conditions
CI / test-responses-api-with-state (push) Blocked by required conditions
CI / e2e-plano-tests (3.10) (push) Blocked by required conditions
CI / e2e-plano-tests (3.11) (push) Blocked by required conditions
CI / e2e-plano-tests (3.12) (push) Blocked by required conditions
CI / e2e-plano-tests (3.13) (push) Blocked by required conditions
CI / e2e-plano-tests (3.14) (push) Blocked by required conditions
CI / e2e-demo-preference (push) Blocked by required conditions
CI / e2e-demo-currency (push) Blocked by required conditions
Publish docker image (latest) / build-arm64 (push) Waiting to run
Publish docker image (latest) / build-amd64 (push) Waiting to run
Publish docker image (latest) / create-manifest (push) Blocked by required conditions
Build and Deploy Documentation / build (push) Waiting to run
* feat: add initial documentation for Plano Agent Skills * feat: readme with examples * feat: add detailed skills documentation and examples for Plano --------- Co-authored-by: Adil Hafeez <adil.hafeez@gmail.com>
75 lines
3 KiB
Markdown
75 lines
3 KiB
Markdown
---
|
||
title: Write Capability-Focused Agent Descriptions for Accurate Routing
|
||
impact: HIGH
|
||
impactDescription: The orchestrator LLM routes requests purely by reading agent descriptions — poor descriptions cause misroutes to the wrong specialized agent
|
||
tags: agent, orchestration, descriptions, routing, multi-agent
|
||
---
|
||
|
||
## Write Capability-Focused Agent Descriptions for Accurate Routing
|
||
|
||
In an `agent` listener, Plano's orchestrator reads each agent's `description` and routes user requests to the best-matching agent. This is LLM-based intent matching — the description is the entire specification the router sees. Write it as a capability manifest: what can this agent do, what data does it have access to, and what types of requests should it handle?
|
||
|
||
**Incorrect (generic, overlapping descriptions):**
|
||
|
||
```yaml
|
||
listeners:
|
||
- type: agent
|
||
name: orchestrator
|
||
port: 8000
|
||
router: plano_orchestrator_v1
|
||
agents:
|
||
- id: agent_1
|
||
description: Helps users with information # Too generic — matches everything
|
||
|
||
- id: agent_2
|
||
description: Also helps users # Indistinguishable from agent_1
|
||
```
|
||
|
||
**Correct (specific capabilities, distinct domains, concrete examples):**
|
||
|
||
```yaml
|
||
version: v0.3.0
|
||
|
||
agents:
|
||
- id: weather_agent
|
||
url: http://host.docker.internal:8001
|
||
- id: flight_agent
|
||
url: http://host.docker.internal:8002
|
||
- id: hotel_agent
|
||
url: http://host.docker.internal:8003
|
||
|
||
listeners:
|
||
- type: agent
|
||
name: travel_orchestrator
|
||
port: 8000
|
||
router: plano_orchestrator_v1
|
||
agents:
|
||
- id: weather_agent
|
||
description: >
|
||
Provides real-time weather conditions and multi-day forecasts for any city
|
||
worldwide. Handles questions about temperature, precipitation, wind, humidity,
|
||
sunrise/sunset times, and severe weather alerts. Examples: "What's the weather
|
||
in Tokyo?", "Will it rain in London this weekend?", "Sunrise time in New York."
|
||
|
||
- id: flight_agent
|
||
description: >
|
||
Provides live flight status, schedules, gate information, delays, and
|
||
aircraft details for any flight number or route between airports.
|
||
Handles questions about departures, arrivals, and airline information.
|
||
Examples: "Is AA123 on time?", "Flights from JFK to LAX tomorrow."
|
||
|
||
- id: hotel_agent
|
||
description: >
|
||
Searches and books hotel accommodations, compares room types, pricing,
|
||
and availability. Handles check-in/check-out dates, amenities, and
|
||
cancellation policies. Examples: "Hotels near Times Square for next Friday."
|
||
```
|
||
|
||
**Description writing checklist:**
|
||
- State the primary domain in the first sentence
|
||
- List 3–5 specific data types or question categories this agent handles
|
||
- Include 2–3 concrete example user queries in quotes
|
||
- Avoid capability overlap between agents — if they overlap, the router will split traffic unpredictably
|
||
- Keep descriptions under 150 words — the orchestrator reads all descriptions per request
|
||
|
||
Reference: https://github.com/katanemo/archgw
|