Agent Execution Capability

The wf.agent-execution capability delegates a bounded subtask to a deployment-resolved agent whose internal control flow is not declared by the Workfile. It differs from a model connector action because the agent can select and invoke several allowlisted actions before returning one typed result.

Use of wf.agent structurally activates wf.agent-execution.

The executor MUST resolve one compatible agent configuration before execution and record its provider, model or runtime identity, tool protocol version, and behavior-affecting settings when history is required. Agent identity is a deployment dependency, not a catalog namespace or workflow value.

The same Workfile can resolve to different conforming agents and can produce different results. The node is therefore an expressly nondeterministic boundary: its returned value and tool trace are external inputs to subsequent deterministic Workfile evaluation.

`wf.agent`

wf.agent delegates a goal to an agent with explicit context, tools, and bounds. The table defines its required goal, returns, and budget configuration and optional with and tools, which default to empty.

Key	Role	Required	Type or domain	Default
`wf.agent`	Subject	Yes	Opaque literal agent identity resolved by the deployment.	—
`goal`	Configuration	Yes	Expression-bearing string.	—
`with`	Configuration	No	Context projection.	`{}`
`tools`	Configuration	No	List of distinct literal `connector.action` references.	`[]`
`returns`	Configuration	Yes	Closed map of field declarations for one object result.	—
`budget`	Configuration	Yes	Closed map containing at least one of `steps`, `tokens`, and `duration`; every supplied bound is positive.	—
`on_exhausted`	Configuration	No	Step list governed by the budget-exhaustion rules below.	Absent

Each handler step has path <agent-path>.(on_exhausted).<id>, with ordinary nesting and indexing continuing from that path.

- resolve:
    wf.agent: triage_assistant
    goal: Find the account for {{ inputs.sender }}; it could belong to a parent organization.
    with:
      sender: "{{ inputs.sender }}"
    tools: [crm.search, billing.lookup]
    returns:
      account_id: { type: string, required: true }
    budget: { steps: 8, tokens: 20000 }
    on_exhausted:
      - notify: { messaging.post: { channel: operations, text: Agent budget exhausted. } }

goal is an expression-bearing string and with is a context projection, both evaluated in the enclosing scope; the projection’s names do not create bindings in an agent expression scope. The resulting map and rendered goal are the agent’s complete readable workflow context.

The implementation MUST NOT expose enclosing bindings omitted from with, including run, trigger payloads, sensitive values, or prior step results. It MUST NOT expose credentials or connection fields.

Each tool uses the connector’s unambiguous deployment default connection and the action’s manifest retry policy. Every action and its connection, scopes, manifest, and required capability MUST resolve before execution.

The implementation MUST reject an undeclared tool invocation, validate arguments and results against the resolved manifest, enforce effects and dry-run behavior, and apply the Connector Execution Contract. The executor MUST prevent the agent from adding a connector, changing a connection, weakening a timeout or policy, invoking a construct, calling another agent, or accessing a tool indirectly. Suppressed context or tool results follow dry-run propagation.

Each tool dispatch counts as an action attempt with its own stable position beneath the agent step. The position identifies the logical invocation and excludes its attempt number, so retry, continuation, recovery, and replay retain the same position.

For a keyed-idempotency tool, the executor is the sole source of the idempotency key. The executor MUST reject a proposed tool call that supplies or overrides the reserved key input before dispatch.

The executor derives the key as wf-agent-v1: followed by the lowercase SHA-256 digest of the UTF-8 encoding of Canonical JSON Value Serialization of the three-element array [run.id, <agent-step-path>, <stable-position>]. It supplies that string as the action’s reserved idempotency input before validation and dispatch.

The reserved input of an action exposed as an agent tool MUST admit every executor-derived key matching \Awf-agent-v1:[0-9a-f]{64}\z; a field constraint that rejects any such key makes that action incompatible with agent tool use.

The executor MUST reuse the fixed key for every attempt, continuation, recovery, or replay of that logical invocation. When applicable history already records the key, continuation, recovery, and replay MUST reuse the recorded value and MUST NOT derive a replacement.

The agent step’s on_unknown modifier applies to every tool invocation. Ambiguous tool results follow that policy under Core Ambiguity Disposition. For wf.agent, the permitted values are abort and fail, plus halt when the Durable Execution Profile is active; reconcile remains action-specific because it requires the action’s adjacent reconcile map.

Under abort or halt, an ambiguous tool result MUST NOT be shown to the agent as definite success or failure. Under fail, the tool result is surfaced to the agent as a tool error carrying flow.action_ambiguous, the originating tool identity, and the ambiguity code and optional details; its effect remains recorded as unknown.

A later tool proposal after that failure is a new logical invocation and can duplicate an effect whose outcome remains unknown. The agent boundary follows the interception or propagation rule of the selected policy under on_unknown.

When the agent finishes, the executor MUST reject unknown fields, apply declared defaults, require required fields, and validate every value before binding.

An invalid result produces an agent.invalid_result failure and creates no partial binding.

Budget steps counts every dispatched tool attempt, including retry; duration measures elapsed time from agent start; and tokens uses the resolved agent’s documented counting method.

Token counting is implementation-defined; the implementation resolving the agent MUST identify the method, and the executor MUST record observed counts when history is required. The executor MUST stop accepting further work requests from the agent when the first bound is reached.

The step-level timeout and budget duration are separate. Budget exhaustion stops the agent cooperatively and runs on_exhausted when present.

Timeout cancels in-progress agent work under Internal Work Cancellation, produces a flow.timeout failure for step policy, and does not run on_exhausted. When both exist, the first reached determines the consequence.

After budget exhaustion, on_exhausted runs in a nested scope that can read the enclosing workflow scope but has no agent result binding. If it completes, agent.budget_exhausted remains available to step failure policy; the handler is for notification, cleanup, or explicit run termination, not an implicit replacement result.

If a handler step fails, the exhaustion code remains the agent step’s failure. wf.stop or wf.fail in the handler retains its ordinary run-level effect.

Handler eligibility and ordering are defined under catch.

An agent can otherwise fail because its resolved runtime is unavailable, its goal or context cannot be accepted, a tool cannot be safely completed, or it returns invalid data. Failures use registered stable codes and follow ordinary step policy.

A deployment cancellation targets the enclosing run under Core Cancellation, not the agent step independently. wf.agent does not accept retry: retrying an autonomous node could select a different tool trace and is not an action retry.

An author who needs another attempt expresses it through bounded workflow control or a handler. The executor applies the tool allowlist under the tool-contract requirements above and MUST record the evaluated goal, projected context, agent configuration identity, budgets and counts, each proposed and dispatched tool call, its fixed key and result, the final agent result, and every stop or failure decision when an applicable history profile requires it.

Replay reconstruction reads this history; re-evaluation treats the entire agent execution and its tool trace as recorded nondeterministic input and MUST NOT contact the agent or repeat its tools. The agent receives no ambient network or filesystem access through this capability.

Any external effect occurs through an allowlisted connector action and remains subject to that action’s credentials and policy. Text in goal, with, or tool results is untrusted input and MUST NOT be allowed to expand the allowlist, reveal omitted context, or override execution bounds.