Agent Step (xema/[email protected])

The Agent step runs a published Xema Agent in a governed workspace. The Agent reference is the single source of truth for the Agent definition, its recursive sub-agent tree, Skills, tools, model defaults, and workspace layout.

For the broader workflow grammar, see DSL Reference.

Minimal usage

1jobs:
2  draft-spec:
3    uses: xema/[email protected]
4    with:
5      agentRef: requirements@3
6      deliverableSpecRef: feature-spec@2
7      agentContext:
8        prompt: Draft a feature specification from the supplied request.

agentRef, deliverableSpecRef, and agentContext are required keys. Use deliverableSpecRef: null when the invocation does not need a typed deliverable.

Core inputs

agentRef (required)

A bare Agent slug or a pinned slug@version reference. A bare slug resolves to the latest published revision; a versioned reference makes the workflow reproducible against that exact revision.

The workflow does not separately select a workspace manifest. Workspace composition is owned by the resolved Agent.

deliverableSpecRef (required, nullable)

The contract for the structured output the Agent must produce. An unknown literal reference fails validation. Set the field to null for an invocation that does not require a typed deliverable.

agentContext (required)

A context object supplied to the Agent. Use prompt for the invocation-specific instruction and add domain fields when the Agent expects them.

1with:
2  agentRef: risk-reviewer@4
3  deliverableSpecRef: risk-assessment@2
4  agentContext:
5    prompt: Review the proposed change and identify material risks.
6    changeId: ${{ inputs.change_id }}
7    severityFloor: medium

Optional execution controls

model

Override the Agent's normal model resolution for this job. Prefer a strategy when the organisation should be able to change the concrete provider or model centrally.

1with:
2  model:
3    kind: strategy
4    modelLane: general-purpose
5    temperature: 0.2

modelLane names a model lane — the kind of work this invocation is, which the organisation binds to a concrete model centrally. Lanes are an open vocabulary: none is built into the platform, and each one is declared by a model-lane contribution, so the lanes you may name are the ones the biomes you have installed declare. A standard install gets four from the agent runtime — general-purpose, coder, planner and light. Naming a lane the organisation has not declared is refused when the Workflow is authored, not silently at run time.

modelLane is optional. Omit it to route through the strategy and let the organisation's declared default binding answer:

1with:
2  model:
3    kind: strategy
4    temperature: 0.2

A concrete pin is also supported:

1with:
2  model:
3    kind: concrete
4    modelId: provider/model-id
5    providerSlug: provider
6    temperature: 0.2

subAgents

Add invocation-specific sub-agent bindings to the resolved Agent's intrinsic delegates. Each binding names a sub-agent slug and may assign an alias or model override.

1with:
2  subAgents:
3    - slug: policy-researcher
4    - slug: data-reviewer
5      alias: evidence-reviewer
6      modelOverride:
7        kind: strategy
8        modelLane: light

For recursive composition limits, use composition.limits; composition.allowedSubAgents can narrow which delegates the coordinator may invoke.

1with:
2  composition:
3    limits:
4      maxDepth: 3
5      maxSpawns: 16
6    allowedSubAgents: [policy-researcher, data-reviewer]

agentSession

Set agentSession: true to turn the Agent job into a workflow-linked, real-time human collaboration point. Xema opens a Session, sends agentContext.prompt as the first turn, keeps the workflow durable while people collaborate, and resumes when the Session produces its structured handoff.

1jobs:
2  resolve-exception:
3    uses: xema/[email protected]
4    timeout: 24h
5    with:
6      agentRef: operations-coordinator@5
7      deliverableSpecRef: exception-resolution@2
8      agentContext:
9        prompt: Investigate this exception with the operator and propose a resolution.
10        caseId: ${{ inputs.case_id }}
11      agentSession: true

The sessionId output is populated for this branch so a product surface can deep-link to the conversation. Use a generous job timeout because the human interaction may take hours.

Inquiries and resumption

• allowAgentToolInquiries enables in-band questions from tools.
• toolInquiryRecipients and toolInquiryPolicy define who may answer and how answers are combined.
• resumeFrom names a prior Agent Session when a coordinator must resume the same conversational state after a gate.

Outputs

The current Agent action exposes:

structuredOutput is the one artifact an Agent job produces. The former deliverables and deliverable outputs were removed on 2026-08-29 along with the workspace harvester, so neither job.outputs.deliverables nor job.outputs.deliverable names a declared field. See the deliverables note.

Declare job outputs from the fields the workflow needs:

1jobs:
2  assess:
3    uses: xema/[email protected]
4    with:
5      agentRef: risk-reviewer@4
6      deliverableSpecRef: risk-assessment@2
7      agentContext:
8        prompt: Assess the request.
9    outputs:
10      assessment: ${{ job.outputs.structuredOutput }}

See also

• Interactive Sessions
• Sub-agents
• Deliverable specifications
• Best Practices

Previous: ← Review Step Next: Dispatch Workflow →