Deploy a Knowledge Assistant

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

This walkthrough creates a governed knowledge assistant using the asset kinds, flow schema, and release requirements that the current platform actually implements.

What you will create

one workload
one prompt_template
one model_policy
one knowledge_base
one policy_bundle
one orchestration_flow
one governed release that binds all of the above

1. Create the workload


curl -s -X POST http://localhost:8000/v1/workloads \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "my-knowledge-assistant",
    "owner_ref": "team:platform",
    "invocation_mode": "chat"
  }' | jq .

Save the returned workload_id.

2. Create the governed assets

Prompt template


curl -s -X POST http://localhost:8000/v1/assets \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "ka-prompt",
    "asset_kind": "prompt_template",
    "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": {
      "system_prompt": "You are a grounded knowledge assistant. Answer only from the provided context and cite sources."
    }
  }' | jq .

Model policy


curl -s -X POST http://localhost:8000/v1/assets \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "ka-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-ka-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", "retrieval"],
        "cost_class": "standard",
        "prompt_caching": "allowed",
        "logging": "redacted"
      },
      "fallback_routes": [],
      "supports_streaming": true,
      "supports_tool_use": true,
      "temperature": 0.2,
      "max_tokens": 800
    }
  }' | jq .

Knowledge base


curl -s -X POST http://localhost:8000/v1/assets \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "ka-docs",
    "asset_kind": "knowledge_base",
    "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": {
      "source_type": "manual",
      "source_ref": "/docs/replace-me",
      "chunk_strategy": "markdown_section",
      "retrieval": {
        "strategy": "hybrid",
        "top_k": 5,
        "chunk_size_tokens": 800,
        "score_threshold": 0.15
      },
      "access_contract": {
        "contract_id": "ka-docs-v1-access",
        "version": 1,
        "default_decision": "deny",
        "allowed_principals": ["user:developer@acme.com"],
        "allowed_groups": [],
        "allowed_workspaces": [],
        "allowed_access_modes": ["interactive"],
        "citation_required": true,
        "revoked": false,
        "revoked_at": null
      },
      "metadata": {
        "owner": "team:platform"
      }
    }
  }' | jq .

Policy bundle


curl -s -X POST http://localhost:8000/v1/assets \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "ka-policy",
    "asset_kind": "policy_bundle",
    "owner_ref": "team:governance"
  }' | 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": {
      "rules": [
        {
          "id": "DEFAULT-ALLOW",
          "condition": "always",
          "outcome": "allow",
          "reason_code": "DEFAULT_ALLOW"
        }
      ]
    }
  }' | jq .

3. Create the orchestration flow

The flow uses the implemented step types and action names: task, llm_call, and return.


curl -s -X POST http://localhost:8000/v1/flows \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "ka-flow",
    "owner_ref": "team:platform",
    "version_label": "v1",
    "content_yaml": "name: Knowledge Assistant Flow\ndescription: Evaluate policy, retrieve context, and answer grounded questions\ntrigger:\n  type: api_request\n  inputs_schema:\n    question: string\nentry_step: evaluate_policy\nsteps:\n  - id: evaluate_policy\n    type: task\n    action: evaluate_policy\n    inputs:\n      question: \"{{trigger.question}}\"\n    on_success: retrieve_context\n    on_failure: return_denial\n  - id: retrieve_context\n    type: task\n    action: retrieve_documents\n    inputs:\n      question: \"{{trigger.question}}\"\n      knowledge_base_ref: \"{{release.knowledge_base}}\"\n    next: generate_answer\n  - id: generate_answer\n    type: llm_call\n    inputs:\n      prompt_ref: \"{{release.prompt_template}}\"\n      context: \"{{steps.retrieve_context.output}}\"\n      question: \"{{trigger.question}}\"\n    next: return_answer\n  - id: return_answer\n    type: return\n    output:\n      answer: \"{{steps.generate_answer.output}}\"\n      sources: \"{{steps.retrieve_context.output}}\"\n  - id: return_denial\n    type: return\n    output:\n      status: denied\n      reason: \"{{steps.evaluate_policy.output.reason}}\"\n"
  }' | jq .

Save the returned flow asset_id, then save the created flow version from GET /v1/assets/{asset_id}/versions.

Optional dry-run validation


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

4. Create the release

Set policy_bundle_id on the release record and also bind the policy bundle version.


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 all required 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": "<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": "<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": "<knowledge_base_version_id>", "role": "knowledge_base"}' | 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 active release


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

The response should include:

workload_id
state: active
the bindings array for all bound asset versions
valid_transitions

8. What matters operationally

The workload path still uses {workload_id}, but release payloads use workload_id.
approved -> active requires a policy_bundle binding. This scenario also requires a model_policy binding because the flow contains an llm_call step; legacy releases may continue to bind model_config.
The knowledge assistant path should bind the flow with role orchestration_flow so the workload entry flow resolves predictably.
Retrieval strategy is governed by the bound knowledge_base; Orqestra applies its access contract before retrieved context reaches a model call.
The current scenario is governance-first: asset versions are created explicitly, then frozen into a release.