Skip to Content
Technical walkthroughsCompose & Release a Flow

Compose & Release a Flow

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

This walkthrough focuses on the implemented orchestration flow contract and the release process needed to make that flow live.

What you will do

  1. Create the governed assets a flow depends on
  2. Create an orchestration_flow
  3. Validate the flow shape
  4. Bind the flow and supporting assets into a release
  5. Move the release through draft -> review_ready -> approved -> active

1. Create the supporting assets

Create these assets and versions first:

  • prompt_template
  • model_policy
  • policy_bundle

Example model policy asset:

curl -s -X POST http://localhost:8000/v1/assets \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "summarizer-model-policy",
    "asset_kind": "model_policy",
    "owner_ref": "team:platform"
  }' | jq .
curl -s -X POST http://localhost:8000/v1/assets/{asset_id}/versions \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "version_label": "v1",
    "content": {
      "provider_route": {
        "route_id": "your-provider-summarizer-us",
        "provider": "your-provider",
        "model": "your-provider/your-model",
        "account_slot": "your-provider-prod",
        "region": "us-east-1",
        "residency": "us",
        "state": "approved",
        "sensitivity_tiers": ["public", "internal"],
        "capability_tags": ["chat"],
        "cost_class": "standard",
        "prompt_caching": "allowed",
        "logging": "redacted"
      },
      "fallback_routes": [],
      "supports_streaming": true,
      "supports_tool_use": true,
      "temperature": 0.3,
      "max_tokens": 1024
    }
  }' | jq .

2. Create the orchestration flow

This example uses the implemented task, llm_call, and return step types.

curl -s -X POST http://localhost:8000/v1/flows \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "summarizer-flow",
    "owner_ref": "team:platform",
    "version_label": "v1",
    "content_yaml": "name: Summarizer Flow\ndescription: Evaluate policy, summarize text, and return the result\ntrigger:\n  type: api_request\n  inputs_schema:\n    document_text: string\nentry_step: evaluate_policy\nsteps:\n  - id: evaluate_policy\n    type: task\n    action: evaluate_policy\n    inputs:\n      content: \"{{trigger.document_text}}\"\n    on_success: summarize\n    on_failure: return_denied\n  - id: summarize\n    type: llm_call\n    inputs:\n      prompt_ref: \"{{release.prompt_template}}\"\n      question: \"{{trigger.document_text}}\"\n    next: return_result\n  - id: return_result\n    type: return\n    output:\n      summary: \"{{steps.summarize.output}}\"\n  - id: return_denied\n    type: return\n    output:\n      error: policy_denied\n      reason: \"{{steps.evaluate_policy.output.reason}}\"\n"
  }' | jq .

Save the returned flow asset_id, then retrieve the created version from:

curl -s http://localhost:8000/v1/assets/{flow_asset_id}/versions | jq .

3. Validate the flow shape

The create call already validates the initial version, but you can also use the explicit validate endpoint:

curl -s -X POST http://localhost:8000/v1/flows/{flow_id}/validate \
  -H "Content-Type: application/json" \
  -d '{
    "content_yaml": "name: Summarizer Flow\ntrigger:\n  type: api_request\n  inputs_schema:\n    document_text: string\nentry_step: return_result\nsteps:\n  - id: return_result\n    type: return\n    output:\n      status: ok\n"
  }' | jq .

Expected response shape:

{
  "valid": true,
  "errors": [],
  "warnings": []
}

4. Create the release

curl -s -X POST http://localhost:8000/v1/releases \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "workload_id": "<workload_id>",
    "environment": "production",
    "target_lane": "all",
    "policy_bundle_id": "<policy_asset_id>"
  }' | jq .

5. Bind asset versions

curl -s -X POST http://localhost:8000/v1/releases/{release_id}/bindings \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{"asset_version_id": "<prompt_version_id>", "role": "prompt_template"}' | jq .
 
curl -s -X POST http://localhost:8000/v1/releases/{release_id}/bindings \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{"asset_version_id": "<model_policy_version_id>", "role": "model_policy"}' | jq .
 
curl -s -X POST http://localhost:8000/v1/releases/{release_id}/bindings \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{"asset_version_id": "<policy_version_id>", "role": "policy_bundle"}' | jq .
 
curl -s -X POST http://localhost:8000/v1/releases/{release_id}/bindings \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{"asset_version_id": "<flow_version_id>", "role": "orchestration_flow"}' | jq .

6. Move the release to active

curl -s -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{"to_state": "review_ready"}' | jq .
 
curl -s -X POST http://localhost:8000/v1/releases/{release_id}/approvals \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: reviewer@acme.com" \
  -d '{
    "outcome": "approved",
    "subject_kind": "release",
    "subject_ref": "<release_id>"
  }' | jq .
 
curl -s -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: reviewer@acme.com" \
  -d '{"to_state": "approved"}' | jq .
 
curl -s -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: deployer@acme.com" \
  -d '{"to_state": "active"}' | jq .

7. Verify the workload entry point

curl -s "http://localhost:8000/v1/workloads/{workload_id}/active-release?environment=production" \
  -H "X-Actor-Ref: developer@acme.com" | jq .

Check that:

  • the release is active
  • the bindings array includes orchestration_flow, model_policy, and policy_bundle
  • the workload can now resolve a live flow for the selected environment

Operational notes

  • The public flow schema uses task for action-driven steps. The older type: action examples are not the right shape for the current validator.
  • Use policy_bundle_id on the release record and a policy_bundle binding on the release itself.
  • Bind the workload entry flow with role orchestration_flow for the current workload execution path.
Deploy Knowledge AssistantPolicy Governance