Skip to content

Chains

Some actions take two calls: prepare a draft, then commit it. A chain lets the first operation name the second, so aidy runs it directly after success, before the model speaks, with arguments taken from the first result. The model does not have to copy ids between calls, and the user sees the second step’s approval right away.

"/api/vm-drafts": {
"post": {
"x-aidy": {
"name": "prepare_vm_draft",
"description": "Prepare a new cloud server (VM) configuration.",
"effect": "create",
"approval": "never",
"next": {
"op": "commit_vm_draft",
"arguments": { "draft_id": "id", "revision": "revision" },
"when": { "status": "prepared" }
}
}
}
},
"/api/vm-drafts/{draft_id}/commit": {
"post": {
"x-aidy": {
"name": "commit_vm_draft",
"title": "Create server",
"confirmation": { "title": "Create server from draft {draft_id}?" }
}
}
}

When prepare_vm_draft answers:

{ "id": "d-7", "revision": 3, "status": "prepared", "name": "gpu-train-03" }

aidy calls commit_vm_draft with {"draft_id": "d-7", "revision": 3}.

Key Meaning
op Required. The operation to run next. It must exist in the catalog and not be a role operation.
arguments Maps each argument of the next call to a path in this call’s result.
argumentsFrom A result path whose object becomes the next call’s whole input.
when Result paths and the values they must equal. Otherwise the chain stops.

Paths are dotted (draft.id, config.network.cidr).

arguments builds the input field by field. If any mapped path is missing from the result, the chain stops.

argumentsFrom takes a prepared configuration as a whole. The host returns the exact input of the next call, and aidy passes it on unchanged:

"next": {
"op": "create_vm",
"argumentsFrom": "config",
"arguments": { "project_id": "project_id" }
}

With argumentsFrom, arguments may add values the object lacks, such as path parameters, but never overwrite a field the object already has. If the path does not hold an object, the chain stops.

when compares each path in the result with a JSON value, and every entry must be equal. A draft that comes back "status": "needs_quota" stops the chain, and the model reads the result and explains it to the user.

The next operation keeps its own policy. When it needs approval, the run finishes with an aidy:approval interrupt for it immediately, before the model writes anything. The arguments on the card are those the chain built, frozen and hashed like any other approval. See Approvals.

A chain can continue: the next operation may have its own next. Each operation is followed at most once per chain, so a cycle ends.

The catalog fails validation when next.op names no operation or names a role operation. See The catalog.