Diagnose which decision failed
A message can fail at discovery, selection, extraction, or execution. Do not fix every failure by expanding the system prompt.
For the booking catalog, “show available times” should reach availability, “book tomorrow” should reach book, and “thanks” may need no tool. Create a small evaluation set containing those cases, paraphrases, Arabic equivalents, and ambiguous requests. Keep expected tool IDs and expected user-owned arguments beside each message.
const runtime = await AgentRuntime.create({
configPath: "./config.yml",
debug: true,
});
const result = await runtime.chat({
sessionId: "routing-check-1",
message: "What times are available tomorrow?",
});
console.log(result.status, result.tool, result.meta, result.debug);
runtime.dispose();
This host fragment requires a configured routing model and credentials. It tests discovery and extraction, unlike the model-free fixtures.
If availability is absent from candidates, improve its description/hints or investigate recall limits. If it is present but another tool wins, distinguish their descriptions. If the tool is correct but a date is missing, check the input schema and relative-date context. If invoke() with the same arguments fails, investigate config/API execution rather than routing.
Understand the cost of a change
Adding an exact trigger phrase can let lexical retrieval skip a recall-model call. Disabling semantic recall can save that call but miss paraphrases. Raising the final candidate limit shows more tools to the selector and can make neighboring intents harder to distinguish.
The semantic catalog limit is a gate: an oversized catalog disables this recall path rather than silently paging through every tool. Use a selective retriever for large domains. Compare tool-choice accuracy and modelRecallCalls before and after a change; an isolated successful prompt is not an evaluation.
AGENTO uses a hybrid routing pipeline instead of sending every Tool and every implementation detail to the model.
Stage 1 — lexical retrieval
LexicalToolRetriever indexes tool ID, title, description, trigger hints and weighted keywords. By default it performs Unicode normalization and Arabic-friendly normalization such as removing Arabic diacritics/tatweel and normalizing common alef forms.
Strong lexical matches can skip semantic recall entirely.
Stage 2 — semantic recall when confidence is weak
If the best lexical score is below routing.lexical.min_score, AGENTO may ask the routing model to recall relevant tool IDs from a lightweight catalog.
The recall catalog contains only safe metadata such as:
id
optional title
description
It does not include endpoint URLs, auth configuration, mappings, dependency data, session facts, API responses, or credentials.
Semantic recall is skipped when the catalog exceeds configured tool/character limits. For very large deployments, inject a custom selective ToolRetriever.
Stage 3 — candidate fusion
Lexical and recalled candidates are fused and deduplicated into a bounded candidate set.
Stage 4 — final model selection
Only the shortlisted model-facing tool definitions are presented for final selection. The model must select one relevant tool or no tool and may extract only declared user-supplied arguments.
AGENTO rejects:
- a tool outside the candidate set;
- unknown argument keys;
- sensitive argument names;
- arguments that fail the partial input schema.
No tool is a valid answer
If no tool is appropriate and conversation is enabled, AGENTO calls ConversationResponder instead of returning a routing failure.
That enables normal exchanges such as:
User: مرحبا
Assistant: أهلًا! كيف أقدر أساعدك؟
without inventing a fake greeting tool.
Conversation is not execution
The conversation system prompt explicitly states that no API tool was executed for a conversation-only response. It should not claim an action was performed.
Conversation may also receive bounded safe capability summaries and pending display facts, but never credentials.
Disable conversation for router-only behavior
assistant:
conversation:
enabled: false
Then deliberate no-match behavior returns ROUTING_NO_MATCH.
Dates and times
The routing prompt receives the trusted application timezone and local date. Explicit relative dates such as “today” or “tomorrow” may be normalized to YYYY-MM-DD when the selected tool declares an appropriate date field. Explicit clock times may be normalized to HH:mm when a declared time field requires it.
Do not use this as a substitute for your business calendar or availability endpoint; relative-date normalization is input interpretation, not business truth.