Examples: Workflow-linked Agent Sessions

An interactive collaboration point is a normal xema/[email protected] job with agentSession: true. The same published Agent can therefore run autonomously or collaborate with people without introducing a second Agent definition or a separate Session action.

Minimal interactive Agent job

yaml

1apiVersion: xema.dev/workflow/v1alpha1
2kind: Workflow
3metadata:
4  name: guided-exception-resolution
5  version: 1.0.0
6
7on:
8  workflow_dispatch:
9    inputs:
10      caseId:
11        type: string
12        required: true
13
14jobs:
15  resolve:
16    uses: xema/[email protected]
17    timeout: 24h
18    with:
19      agentRef: operations-coordinator@5
20      deliverableSpecRef: exception-resolution@2
21      agentContext:
22        prompt: Work with the operator to investigate and resolve this exception.
23        caseId: ${{ inputs.caseId }}
24      agentSession: true
25    outputs:
26      sessionId: ${{ job.outputs.sessionId }}
27      resolution: ${{ job.outputs.structuredOutput }}

Xema opens the Session, sends the prompt as the first turn, and keeps the workflow job durable until the Session produces its structured handoff. The sessionId allows an experience to open the live conversation.

Prepare, collaborate, then continue

yaml

1jobs:
2  prepare:
3    uses: xema/[email protected]
4    with:
5      agentRef: case-analyst@3
6      deliverableSpecRef: case-brief@2
7      agentContext:
8        prompt: Prepare the evidence and unresolved questions for this case.
9        caseId: ${{ inputs.caseId }}
10    outputs:
11      brief: ${{ job.outputs.structuredOutput }}
12
13  collaborate:
14    needs: [prepare]
15    uses: xema/[email protected]
16    timeout: 24h
17    with:
18      agentRef: operations-coordinator@5
19      deliverableSpecRef: exception-resolution@2
20      agentContext:
21        prompt: Review the prepared brief with the operator and agree the resolution.
22        caseId: ${{ inputs.caseId }}
23        brief: ${{ needs.prepare.outputs.brief }}
24      agentSession: true
25    outputs:
26      sessionId: ${{ job.outputs.sessionId }}
27      resolution: ${{ job.outputs.structuredOutput }}
28
29  record:
30    needs: [collaborate]
31    uses: customer/case-record-[email protected]
32    with:
33      caseId: ${{ inputs.caseId }}
34      resolution: ${{ needs.collaborate.outputs.resolution }}

The preparation and recording jobs remain automated. Only the job that benefits from human judgement becomes interactive.

Decision gate before collaboration

Use a Decision when the workflow needs explicit authority before opening or continuing a human-guided operation:

yaml

1jobs:
2  propose:
3    uses: xema/[email protected]
4    with:
5      agentRef: risk-reviewer@4
6      deliverableSpecRef: action-proposal@1
7      agentContext:
8        prompt: Prepare a bounded action proposal for this request.
9    outputs:
10      proposal: ${{ job.outputs.structuredOutput }}
11
12  approve:
13    needs: [propose]
14    uses: xema/decision-[email protected]
15    with:
16      subject: ${{ needs.propose.outputs.proposal }}
17      recipients:
18        - kind: human
19          target:
20            userId: ${{ trigger.actorSubject }}
21      policy:
22        kind: single
23
24  execute-with-operator:
25    needs: [approve]
26    if: ${{ needs.approve.outputs.outcome == 'approved' }}
27    uses: xema/[email protected]
28    timeout: 24h
29    with:
30      agentRef: operations-coordinator@5
31      deliverableSpecRef: execution-record@1
32      agentContext:
33        prompt: Execute the approved proposal with the operator.
34        approvedProposal: ${{ needs.propose.outputs.proposal }}
35      agentSession: true

The Decision owns the approval evidence; the Agent Session owns the collaborative execution; the Workflow owns the durable sequence.

Design guidance

Use the same agentRef for automated and interactive execution when the responsibility is the same.
Pin agentRef and deliverableSpecRef versions for reproducible production workflows.
Give interactive jobs a timeout that reflects human response time.
Carry business state through typed deliverables rather than relying on transcript parsing.
Use the sessionId to deep-link from the workflow run into the collaboration surface.

See Agent Step and Interactive Sessions.