Resolve
Users say “stop gpu-train-01”; your API takes vm-42. resolve bridges the two: before
approval, aidy looks a string argument up in a list operation and replaces a name with the id
it belongs to.
"/api/vm/{vm_id}/stop": { "post": { "x-aidy": { "name": "stop_vm", "effect": "update", "resolve": { "vm_id": { "op": "list_vms" } } } }},"/api/vms": { "get": { "x-aidy": { "name": "list_vms", "description": "List the user's cloud servers (VMs)." } }}resolve maps an argument name to {op, key?}:
| Key | Meaning |
|---|---|
op |
A read operation in the catalog that lists the candidates. |
key |
The item field that holds the id. Default id. |
How a value is resolved
Section titled “How a value is resolved”For each argument listed in resolve whose value is a non-empty string:
- aidy calls
opas the user. When the list pages by apage_sizequery parameter, it asks for 100 items. - It finds the items: the response body itself when it is an array, otherwise the first nested
array of objects that carry
key, such as{"items": [...]}. - If an item’s
keyequals the value, the value is already an id and is kept. - Otherwise the value is matched against each item’s
name,display_name,displayNameortitle, ignoring case and surrounding spaces. - Exactly one match replaces the value with that item’s
key.
With this list:
{ "items": [ { "id": "vm-42", "name": "gpu-train-01" }, { "id": "vm-43", "name": "gpu-train-02" } ]}{"vm_id": "gpu-train-01"} becomes {"vm_id": "vm-42"}, and {"vm_id": "vm-42"} stays as it
is.
unresolved_reference
Section titled “unresolved_reference”When no item matches, or several do, the call fails with unresolved_reference and nothing is
sent to the operation. The message names up to ten candidates, so the model can ask the user or
pick the right one:
{ "status": "failed", "error": { "code": "unresolved_reference", "message": "\"gpu-train\" matches several items; say which one: gpu-train (vm-42), gpu-train (vm-51)." }}The error goes back to the model as a tool result. It is not shown to the user as an error.
Where resolve runs
Section titled “Where resolve runs”Resolve runs after validation and after a host form, and before the confirmation lookup and the approval:
validate → form → resolve → confirmation lookup → approval → executeThe approval therefore binds to the resolved id. The user approves “Stop server
gpu-train-01?”, and argsHash covers {"vm_id": "vm-42", ...}. A name that later points to a
different server cannot change what was approved.
Validation
Section titled “Validation”The catalog fails validation when resolve names an operation that does not exist or is not a
read. See The catalog.