1. Run the Reference Stack
Start PostgreSQL, the FastAPI decision service, and the durable research worker together.
The decision endpoint can return a durable research job, so running only the backend is incomplete. The repository's Docker Compose stack builds the actual backend image, applies database migrations during API startup, and starts the worker that claims queued research.
git clone https://github.com/AxWise-GmbH/axwise-flow-oss.gitcd axwise-flow-osscp .env.example .env# Set GEMINI_API_KEY in .env.# Replace AXWISE_API_KEY before exposing the service.docker compose up -d --build db backend worker# Health and interactive OpenAPIdocker compose pscurl http://localhost:8000/health# Visit http://localhost:8000/docsThe reference endpoints fail closed unless a trusted host tenant is mapped to an AxWise workspace. For a local-only reference tenant, run docker compose exec backend python -m backend.scripts.seed_reference_tenant --org-id local-org --user-id local-user. Provision production mappings through an administrator-controlled process, never from a browser request.
2. Create an Evidence-aware Decision
POST /api/orqaly-axwise/v1/orchestration/decisions
Start every integrated goal here. AxWise evaluates ambiguity, evidence sufficiency, consequence, and value of more information before choosing direct, evidence-assisted, bounded-research, or human-clarification routing. It then returns an immutable recommendation package. It does not authorize or execute the recommendation.
import requestsbase = "https://api.axwise.de/api/orqaly-axwise/v1"headers = { "x-axwise-key": "<SERVICE_KEY>", "Idempotency-Key": "<GOAL_VERSION_KEY>", "X-Request-ID": "<TRACE_ID>"}payload = { "contract_version": "1.0", "tenant": { "orgId": "<ORQALY_ORG_ID>", "userId": "<ORQALY_USER_ID>" }, "task": { "contract_version": "1.0", "task_id": "goal-warehouse-handoff-v1", "domain": "operations", "objective": "Reduce damage at warehouse handoffs", "desired_outcome": "A reviewed plan with owners and measurable controls", "required_capabilities": ["operational analysis"], "preferred_capabilities": ["stakeholder communication"], "stakeholders": ["warehouse manager", "shift lead"], "constraints": ["No external side effect without host approval"], "data_classification": "internal", "risk_level": "medium" }, "available_agents": [{ "agent_id": "agent-operations", "org_id": "<ORQALY_ORG_ID>", "name": "Operations Analyst", "capabilities": [ "operational analysis", "stakeholder communication" ], "availability": "available", "max_data_classification": "confidential", "max_risk_level": "high" }], "policy_context": { "maximum_risk_without_human": "medium", "guardrails": ["The host must approve execution"] }, "budget": { "currency": "EUR", "maximum_cost": 25, "maximum_latency_ms": 120000 }}response = requests.post( f"{base}/orchestration/decisions", headers=headers, json=payload, timeout=30)response.raise_for_status(){ "contract_version": "1.0", "decision_id": "decision-…", "task_id": "goal-warehouse-handoff-v1", "routing_mode": "direct", "status": "recommended", "recommended_agents": [{ "agent_id": "agent-operations", "eligible": true, "score": 0.82, "factors": [] }], "execution_plan": { "nodes": [{ "node_id": "node-direct-assignment", "assigned_agent_id": "agent-operations" }], "executable": true }, "approval_points": [], "evidence": [], "confidence": 0.82, "requires_orqaly_authorization": true, "request_hash": "4c61236d…"}Construct available_agents, available_tools, policy, and tenant identifiers on the trusted host backend from the authenticated catalogue. Never accept candidate ownership, the machine credential, or authorization decisions from a browser. Retrieve the exact JSON Schemas at /orchestration/schemas/decision-request-v1 and /orchestration/schemas/execution-outcome-v1.
401 missing or invalid service key; 403 inactive or unknown tenant mapping; 409 idempotency key reused with different input; 422 invalid strict contract. Retry transient failures with backoff and the same idempotency key.3. Retrieve or Refresh the Decision
GET /decisions/{decision_id} · POST /decisions/{decision_id}/research/refresh
A direct, evidence-assisted, or clarification decision is immediately retrievable. A research-assisted decision returns status: pending_research and a durable research_job. Call refresh with a new idempotency key: HTTP 202 means the worker is still running; HTTP 201 returns a new linked decision after the evidence is available. The original snapshot is never rewritten.
tenant_headers = { "x-axwise-key": "<SERVICE_KEY>", "X-Orqaly-Org-ID": "<ORQALY_ORG_ID>", "X-Orqaly-User-ID": "<ORQALY_USER_ID>"}decision = requests.get( f"{base}/orchestration/decisions/{decision_id}", headers=tenant_headers, timeout=30)decision.raise_for_status()refresh_headers = { **tenant_headers, "Idempotency-Key": "<REFRESH_ATTEMPT_KEY>", "X-Request-ID": "<TRACE_ID>"}refreshed = requests.post( f"{base}/orchestration/decisions/{decision_id}/research/refresh", headers=refresh_headers, timeout=30)if refreshed.status_code == 202: # Keep the goal non-executable and retry with backoff. passelif refreshed.status_code in (200, 201): next_decision = refreshed.json()else: refreshed.raise_for_status(){ "decision_id": "decision-parent", "routing_mode": "research_assisted", "status": "pending_research", "research_job": { "job_id": "hybrid-…", "status": "queued", "pipeline": "hybrid_a_plus_b" }, "execution_plan": {"nodes": [], "executable": false}, "requires_orqaly_authorization": true}4. Replan and Report Outcomes
Immutable recovery decisions and observed execution receipts
If the host rejects a recommendation or live execution state changes, request a linked replan instead of mutating the original decision. After the host authorizes and executes the plan, report observed outcomes using the real decision, node, and agent IDs. Outcomes improve evaluation; they do not give AxWise authority to run anything.
replan = requests.post( f"{base}/orchestration/decisions/{decision_id}/replan", headers={ **tenant_headers, "Idempotency-Key": "<REPLAN_KEY>" }, json={ "contract_version": "1.0", "trigger": "agent_unavailable", "reason": "Selected agent became unavailable", "unavailable_agent_ids": ["agent-operations"], "replacement_agents": [{ "agent_id": "agent-operations-backup", "org_id": "<ORQALY_ORG_ID>", "name": "Backup Operations Analyst", "capabilities": ["operational analysis"], "availability": "available" }] }, timeout=30)replan.raise_for_status()outcome = requests.post( f"{base}/orchestration/decisions/{decision_id}/outcomes", headers={ **tenant_headers, "Idempotency-Key": "<OUTCOME_KEY>" }, json={ "contract_version": "1.0", "outcome_id": "outcome-goal-warehouse-v1", "decision_id": decision_id, "authorization_status": "approved", "execution_status": "completed", "task_success": True, "quality_score": 0.86, "stakeholder_acceptance": 0.80, "cost": 7.50, "currency": "EUR", "latency_ms": 42000, "node_receipts": [{ "receipt_id": "receipt-node-direct-v1", "node_id": "node-direct-assignment", "agent_id": "agent-operations", "status": "completed", "quality_score": 0.86 }] }, timeout=30)outcome.raise_for_status()List accepted records with GET /orchestration/decisions/{decision_id}/outcomes. Reuse the same idempotency key only for an identical body; changed retries return HTTP 409.
5. Lower-level Research Is Secondary
POST /api/orqaly-axwise/v1/simulate-enhanced-async
Use the enhanced simulation endpoint only when a trusted integration deliberately needs the raw durable customer-and-executor pipeline. It starts research unconditionally. For normal goal handling, the decision endpoint is the correct entry point because it may determine that existing evidence, direct routing, or human clarification is safer and faster.
{ "secondary_flow": { "start": "POST /api/orqaly-axwise/v1/simulate-enhanced-async", "status": "GET /api/orqaly-axwise/v1/runs/{job_id}/status", "result": "GET /api/orqaly-axwise/v1/runs/{job_id}", "cancel": "POST /api/orqaly-axwise/v1/runs/{job_id}/cancel" }, "rule": "Synthetic output remains an unverified working hypothesis", "preferred_goal_entry": "POST /api/orqaly-axwise/v1/orchestration/decisions"}6. Host Authorization and Execution Boundary
AxWise intelligence → host approval, tools, execution, and delivery
AxWise returns who the work is for, what remains uncertain, the ideal executor requirements, a goal-specific execution persona, ranked eligible agents or teams, and an advisory plan. In the reference integration, Orqaly preserves permanent Agent Hub identities and owns both human gates, tenant ownership, live availability, budget, connectors, execution, monitoring, and delivery.
# Evidence-bounded customer and stakeholder context# Ideal executor requirements and goal persona overlay# Ranked authenticated catalogue candidates# Routing rationale, confidence, plan, and fallbacks# Immutable request and decision hashes# requires_orqaly_authorization = True# Authenticate the user and establish tenant ownership# Confirm context before planning# Confirm exact team, tools, budget, and plan before execution# Revalidate approvals and live state when a queued task starts# Execute through customer-authorized connectors# Deliver output and report observed outcomesLegacy /twins/* demonstration routes are not the cognitive decision contract. Do not build new integrations against them. Self-hosting gives you control of the data plane; it does not by itself establish authorization, compliance, or safe autonomy.