Workflow Templates¶

Workflow templates are reusable execution blueprints for multi-step Prometheus analyses. They let the client-agent run a known sequence of skills, collect required inputs, pass outputs from one step into later steps, and publish the workflow as a catalog item, planner tool, and slash command.

Use a workflow template when the order of operations matters or when the same chain of skills should be available to users without asking the planner to rediscover the sequence every time. Examples include material assessment workflows that retrieve material data, run several specialist analyses, and synthesize a final report.

Templates can be owned by the platform or by specialist agents:

• Platform-owned workflows live in agents/client-agent/workflows/*.yaml or *.yml.
• Agent-owned workflows live with the agent, either in the agent card's top-level workflows array or in workflow files loaded by PrometheusAgent from workflows/ or AGENT_WORKFLOWS.

Agent-owned workflows are discovered from the agent card, compiled against the currently discovered skill schemas, merged into the same platform workflow catalog, and health-checked against their provider agent before execution.

File locations¶

Platform-owned workflows¶

The client-agent workflow registry loads local workflow files from WORKFLOW_LIBRARY_DIR, which defaults to /app/workflows inside the client-agent container. In the source tree these are normally authored under:

agents/client-agent/workflows/*.yaml
agents/client-agent/workflows/*.yml

Each platform-local file should contain one workflow object.

Agent-owned workflows¶

Agents can publish workflow templates in two ways:

1. Add workflow objects to the source agent_card.json under a top-level workflows array.
2. Add *.yaml, *.yml, or *.json workflow files to workflows/ beside agent_card.json.

PrometheusAgent loads workflow files at startup and inserts them into the served raw agent card. If AGENT_WORKFLOWS is set, it overrides the default workflows/ directory. Relative AGENT_WORKFLOWS paths resolve relative to agent_card.json, so agent cards and workflow files stay relocatable as a pair.

Agent-owned workflow files may contain one workflow object, a list of workflow objects, or a wrapper object:

workflows:
  - id: thermal_agent.quick_check
    name: Quick Thermal Check
    version: "1.0.0"
    description: Run a quick thermal analysis.
    steps:
      - id: analyze
        skill_id: analyze_thermal

Minimal template¶

id: provider.workflow_name
name: Workflow Name
version: "1.0.0"
description: What this workflow does.

inputs:
  required:
    - input_data
  optional: []

execution:
  mode: sequential
  max_concurrency: 1
  on_error: fail_fast

steps:
  - id: run_primary_skill
    skill_id: primary_skill_id
    is_final: true
    params:
      input_data:
        from: input.input_data

outputs:
  final:
    from: step.run_primary_skill.result

metadata:
  requires_approval: false
  estimated_duration_seconds: 30
  owner: provider

ui:
  category: Provider
  display_name: Workflow Name
  summary: One-sentence catalog summary.

Complete schema¶

Top-level workflow object¶

Unknown fields are not part of the stable contract. The current Pydantic models ignore extra fields, so do not depend on unrecognized keys for durable behavior.

matching¶

matching:
  priority: 0
  patterns: []
  tags: []
  semantic_fallback:
    enabled: false
    min_confidence: 0.8

patterns are kept for compatibility. Prefer workflow catalog selection, generated planner tools, or slash commands for new user-facing behavior.

inputs¶

inputs:
  required:
    - material_id
    - context.temperature_c
  optional:
    - context.pressure_mpa

The compiler also scans step params and skill input schemas:

• Any binding from input.* becomes a required workflow input unless the binding has optional: true or its path appears in inputs.optional.
• Required skill fields bound from input.* become required workflow inputs.
• Required skill fields satisfied by literal, step.*, or context produced by ancestor step outputs do not become user inputs.
• Required skill fields bound from external context.* become required as context.<path> unless an ancestor step writes that context path.

execution¶

execution:
  mode: sequential
  max_concurrency: 3
  on_error: fail_fast

Sequential mode runs one ready step at a time. Parallel and DAG modes run currently ready steps up to max_concurrency. Dependencies are still enforced in DAG mode.

steps¶

steps:
  - id: retrieve_material
    skill_id: get_material_data
    depends_on: []
    params: {}
    outputs: []
    when: {}
    is_final: false

Step IDs must be unique. Unknown depends_on references and dependency cycles are compile errors.

when.not_in_context skips the step if the named context path already exists:

when:
  not_in_context: material_data

params¶

Step params can be plain values or recursive binding nodes.

Literal values:

params:
  width:
    literal: 512
  color:
    literal: blue

User inputs:

params:
  material_id:
    from: input.material_id

Workflow context:

params:
  material_data:
    from: context.material_data

Prior step results:

params:
  radiation:
    from: step.analyze_radiation.result

Optional bindings:

params:
  context:
    pressure_mpa:
      from: input.context.pressure_mpa
      optional: true

Supported from roots are input., context., and step.. Optional bindings are omitted from the step payload when the value is missing. The executor also adds conversation_id to every step payload and forwards context.artifacts as artifacts when the step payload does not set artifacts explicitly.

Step outputs¶

steps:
  - id: retrieve_material
    skill_id: get_material_data
    outputs:
      - to_context: material_data
        from: result
      - to_context: material_id
        from: material_id

from: result maps the whole step result if the result object has no nested result key.

Workflow outputs¶

outputs:
  final:
    from: step.synthesize_report.result

If outputs.final.from is not set, the executor returns the first is_final: true step result. If no step is marked final, it returns the last step result.

metadata¶

metadata:
  requires_approval: false
  estimated_duration_seconds: 30
  owner: provider-name
  source_agent_id: provider-agent-id
  source_agent_url: http://provider:8000

For agent-owned workflows, source_agent_id and source_agent_url are used for the provider health check before workflow execution. Local platform workflows do not have source metadata and skip this guard.

ui¶

ui:
  category: Safety
  display_name: Comprehensive Material Analysis
  summary: Full multi-domain assessment.
  input_overrides:
    context.temperature_c:
      label: Coolant temperature
      description: Operating coolant temperature.
      type: number
      unit: C
      options: []

Input override fields:

Full example¶

id: comprehensive_material_analysis
name: Comprehensive Material Analysis
version: "1.0.0"
description: Multi-step safety analysis using data and specialist skills.

inputs:
  required:
    - material_id
    - context.temperature_c
  optional:
    - context.pressure_mpa
    - context.neutron_flux_n_cm2_s
    - context.operating_hours

execution:
  mode: dag
  max_concurrency: 3
  on_error: fail_fast

steps:
  - id: retrieve_material
    skill_id: get_material_data
    params:
      material_id:
        from: input.material_id
    outputs:
      - to_context: material_data
        from: result

  - id: analyze_radiation
    skill_id: analyze_radiation_damage
    depends_on: [retrieve_material]
    params:
      material_id:
        from: input.material_id
      context:
        neutron_flux_n_cm2_s:
          from: input.context.neutron_flux_n_cm2_s
          optional: true
        operating_hours:
          from: input.context.operating_hours
          optional: true

  - id: synthesize_report
    skill_id: synthesize_material_analysis
    depends_on: [retrieve_material, analyze_radiation]
    is_final: true
    params:
      material_id:
        from: input.material_id
      material_data:
        from: context.material_data
      radiation:
        from: step.analyze_radiation.result

outputs:
  final:
    from: step.synthesize_report.result

metadata:
  requires_approval: true
  estimated_duration_seconds: 270
  owner: materials-team

ui:
  category: Safety
  display_name: Comprehensive Material Analysis
  summary: Full multi-domain assessment with data retrieval and specialist analysis.
  input_overrides:
    context.temperature_c:
      label: Coolant temperature
      description: Operating coolant temperature.
      unit: C
      type: number

Authoring notes¶

• Keep workflow IDs stable and globally unique. Prefer provider.workflow_name.
• Quote YAML scalars containing #, colon-sensitive text, leading braces, or other YAML-sensitive characters. For example, write literal: "USA is #1".
• Do not depend on matching.patterns for core behavior in new workflows. Registered workflows are exposed to the planner as workflow tools and can be invoked explicitly by slash command.
• If an agent is containerized, copy its workflow directory into the runtime image. The generated agent template uses COPY workflows /app/workflows.
• The agent template ships workflows/example_workflow.yaml.example so new agents do not publish a sample workflow until the author intentionally renames and reviews it.