Skip to content

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.

For each argument listed in resolve whose value is a non-empty string:

  1. aidy calls op as the user. When the list pages by a page_size query parameter, it asks for 100 items.
  2. 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": [...]}.
  3. If an item’s key equals the value, the value is already an id and is kept.
  4. Otherwise the value is matched against each item’s name, display_name, displayName or title, ignoring case and surrounding spaces.
  5. 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.

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.

Resolve runs after validation and after a host form, and before the confirmation lookup and the approval:

validate → form → resolve → confirmation lookup → approval → execute

The 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.

The catalog fails validation when resolve names an operation that does not exist or is not a read. See The catalog.