Interactive Sessions: Workflow Integration

Interactive Sessions can become durable human-collaboration points inside a Xema Workflow. The integration uses the standard xema/[email protected] action with agentSession: true; there is no separate Session action and no separate Agent profile.

Operating sequence

  1. The Workflow reaches an Agent job.
  2. Xema resolves the published agentRef, including its Skills, tools, sub-agents, model policy, and workspace composition.
  3. With agentSession: true, Xema opens a workflow-linked Session and sends agentContext.prompt as its first turn.
  4. People and the Agent collaborate through the Session while the Workflow remains durable.
  5. The Session produces a structured handoff.
  6. That handoff becomes the Agent job's output and downstream jobs continue.

Complete pattern

yaml
1apiVersion: xema.dev/workflow/v1alpha1
2kind: Workflow
3metadata:
4  name: governed-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  prepare:
16    uses: xema/[email protected]
17    with:
18      agentRef: case-analyst@3
19      deliverableSpecRef: case-brief@2
20      agentContext:
21        prompt: Assemble the evidence and unresolved questions.
22        caseId: ${{ inputs.caseId }}
23    outputs:
24      brief: ${{ job.outputs.structuredOutput }}
25
26  collaborate:
27    needs: [prepare]
28    uses: xema/[email protected]
29    timeout: 24h
30    with:
31      agentRef: operations-coordinator@5
32      deliverableSpecRef: exception-resolution@2
33      agentContext:
34        prompt: Review the case with the operator and produce the agreed resolution.
35        caseId: ${{ inputs.caseId }}
36        brief: ${{ needs.prepare.outputs.brief }}
37      agentSession: true
38    outputs:
39      sessionId: ${{ job.outputs.sessionId }}
40      resolution: ${{ job.outputs.structuredOutput }}
41
42  apply:
43    needs: [collaborate]
44    uses: customer/case-apply-[email protected]
45    with:
46      caseId: ${{ inputs.caseId }}
47      resolution: ${{ needs.collaborate.outputs.resolution }}

Automated and interactive use of the same Agent

Omit agentSession for drive-once automated execution. Set it to true only where live human collaboration adds value:

yaml
1jobs:
2  automated-assessment:
3    uses: xema/[email protected]
4    with:
5      agentRef: risk-reviewer@4
6      deliverableSpecRef: risk-assessment@2
7      agentContext:
8        prompt: Assess this standard request.
9
10  guided-assessment:
11    uses: xema/[email protected]
12    timeout: 24h
13    with:
14      agentRef: risk-reviewer@4
15      deliverableSpecRef: risk-assessment@2
16      agentContext:
17        prompt: Assess this exceptional request with the risk owner.
18      agentSession: true

This preserves one governed Agent identity and revision history across both experiences.

Operational guidance

  • Set a generous timeout for human-guided jobs.
  • Use typed deliverables for the handoff to downstream jobs.
  • Project sessionId when an experience should offer an “Open conversation” link.
  • Use Decisions for explicit approvals; use Sessions for collaboration.
  • Keep side effects behind Capabilities and policy checks even while the Session is interactive.

See Agent Step, Session API, and Sub-agents.