Agentic Runtime Platform

Run YAML-defined AI workflows through a native DAG engine or a LangGraph adapter.

Documentation · Quick start · Architecture · Known limitations

Agentic Runtime Platform is a Python and React monorepo for defining, running, observing, and evaluating multi-step AI workflows. A workflow is a YAML file whose steps form a directed acyclic graph (DAG). Independent steps can run at the same time, dependent steps wait for their inputs, and failures prevent downstream work from running with incomplete data.

The repository is an inspectable implementation and development platform. It includes operational controls, but it is not a hosted service or a claim that every deployment concern is solved. Read Known limitations before using it in a long-running or multi-tenant environment.

Demo and evidence

• Five-minute demo — proves the CLI, API, WebSocket stream, and dashboard work together end to end, with no provider credential.
• Load and shared-state evidence — a reproducible local harness that records POST /api/run acceptance throughput at one and three replicas, plus a direct concurrent-writer test showing the Redis compare-and-swap circuit-breaker counter stays exact. The Redis check is a separate worker experiment, not driven by the k6 traffic.

Two concrete outcomes from that demo:

A successful run. The Quick start command below (AGENTIC_NO_LLM=1 agentic run test_deterministic ...) finishes with Status: SUCCESS; the five-minute demo repeats the same workflow through the dashboard and confirms the HTTP request, the live WebSocket event stream, and the saved run all reach the UI.

An approval-denied run. High-impact tools (shell, shell_exec, execute_python, file_write, file_delete, build_app, http_post, and more) require approval from a registered ApprovalProvider. A fresh install registers none, so the gate fails closed: the call is denied and the tool body never runs. Run the tests that exercise this directly:

cd agentic-workflows-v2
python -m pytest tests/test_approval_gates.py -k fails_closed -v

Every case denies before the tool body runs, and the dispatch-path tests also assert metadata["approval_decision"] == "denied" — for example, test_build_app_no_provider_fails_closed proves BuildAppTool never starts its install/build/test shell. The denial message itself, quoted directly from the gate rather than paraphrased:

Tool 'build_app' requires approval: denied by no provider registered (fail-closed). Register an ApprovalProvider via agentic_v2.governance.set_approval_provider(...) or disable the requirement.

See Known limitations §4.3 for what this gate covers today and what is still missing (a UI-driven pause/resume flow).

What is included

Area	What it provides
Workflow runtime	YAML loading, input validation, DAG scheduling, conditional steps, bounded loops, retries, timeouts, and run records
Execution engines	A dependency-light native DAG engine and an optional LangGraph adapter behind one ExecutionEngine interface
Model routing	Capability tiers, provider selection, health tracking, fallback chains, and circuit breakers
Tool controls	Explicit tool allowlists and approval checks for high-impact tools; approval-required calls fail closed when no approval provider is registered
Server and UI	FastAPI endpoints, SSE and WebSocket run events, a React dashboard, workflow editing, run history, model settings, and evaluation views
Evaluation	YAML rubrics, objective metrics, batch and streaming runners, LLM-as-judge support, and report generation
Integrations	OpenTelemetry, Prometheus, Redis-backed shared state, and an MCP client

Quick start

Requirements

• Python 3.11 or newer
• Node.js 22.22.2 or newer (CI uses Node 22)
• npm
• PowerShell and just for the shortest setup path

Clone and install the workspace on Windows:

git clone https://github.com/tafreeman/agentic-runtime-platform.git
cd agentic-runtime-platform
just setup
.\.venv\Scripts\Activate.ps1

just setup installs into .venv but does not activate it in your shell, so activate it as above (or call .\.venv\Scripts\agentic.exe). The current justfile selects powershell.exe. On Linux or macOS, use the manual installation steps.

Run the deterministic workflow with the input file shipped in the repository:

AGENTIC_NO_LLM=1 agentic run test_deterministic \
  --input agentic-workflows-v2/tests/fixtures/deterministic_input.json

PowerShell:

$env:AGENTIC_NO_LLM = "1"
agentic run test_deterministic `
  --input agentic-workflows-v2/tests/fixtures/deterministic_input.json

The command should finish with Status: SUCCESS. The --input option accepts a JSON file path, not inline JSON. To write your own input file from PowerShell, use Set-Content -Encoding ascii: Windows PowerShell 5.1 adds a byte-order mark with -Encoding utf8, which the CLI rejects.

To run the same workflow through both execution engines and compare them:

agentic compare test_deterministic \
  --input agentic-workflows-v2/tests/fixtures/deterministic_input.json \
  --adapters native,langchain

agentic compare exits non-zero if either engine fails. The quick start covers saving and inspecting the result file.

AGENTIC_NO_LLM=1 replaces model calls with a fixed response. It is useful for testing workflow shape, server wiring, and streaming without provider credentials. It does not test response quality, structured model output, or tool selection. See No-LLM mode.

On Windows, start the backend and UI for local development:

just dev

The development launcher uses:

• UI: http://127.0.0.1:5173
• API: http://127.0.0.1:8010
• OpenAPI: http://127.0.0.1:8010/docs

Use just dev-stop to stop both processes. The standalone agentic serve command defaults to port 8000; pass --port 8010 when you want it to match the UI development proxy.

Without just (for example on Linux or macOS), run the two processes yourself with the environment active: agentic serve --port 8010 --no-open in one terminal and npm --prefix agentic-workflows-v2/ui run dev in another. See Installation.

If just is not available, follow the manual installation steps.

Workflow example

This two-step workflow runs without a model. The second step waits for the first step's output:

name: test_deterministic
description: Simple deterministic workflow for testing (no LLM calls)
version: "1.0"

inputs:
  input_text:
    type: string
    description: Text to process
    required: true

outputs:
  processed_text:
    from: ${steps.step1.outputs.result}
  step_count:
    from: ${steps.step2.outputs.count}

steps:
  - name: step1
    agent: tier0_process
    description: Process input text (tier-0, no LLM)
    inputs:
      text: ${inputs.input_text}
    outputs:
      result: processed_text

  - name: step2
    agent: tier0_counter
    description: Count characters (tier-0, no LLM)
    depends_on: [step1]
    inputs:
      text: ${steps.step1.outputs.result}
    outputs:
      count: count_value

Built-in definitions live in agentic_v2/workflows/definitions. Use the CLI to inspect and validate them:

agentic list workflows
agentic validate test_deterministic
agentic run test_deterministic --input .\agentic-input.json --dry-run

See the workflow authoring guide for the complete schema and workflow reference for the shipped definitions.

Execution engines

Named YAML workflows use the LangGraph adapter by default. Install the langchain extra for that path. The native engine has no LangGraph dependency and is selected explicitly:

agentic run code_review --input review-input.json --adapter langchain
agentic run code_review --input review-input.json --adapter native

Runtime-generated DAG and Pipeline objects use the native engine. The server validates AGENTIC_DEFAULT_ADAPTER at startup and stops with an install hint when the selected adapter is unavailable.

The two engines are both supported. ADR-031 proposed removing LangGraph but was superseded; the adapter remains part of the current architecture. See Architecture and the ADR index.

Model providers

The runtime supports OpenAI, Anthropic, Gemini, Azure OpenAI, Azure AI Foundry, NVIDIA NIM, OpenRouter, DigitalOcean Serverless Inference, Mistral La Plateforme, Ollama, and compatible local endpoints. Provider packages and credentials depend on the selected execution path.

Copy the environment template before using a real provider:

cp .env.example .env

PowerShell:

Copy-Item .env.example .env

Set only the credentials you need. Do not commit .env. The configuration reference lists the supported variables and explains which settings are read at startup or per request.

Repository layout

agentic-runtime-platform/
├── agentic-workflows-v2/
│   ├── agentic_v2/           # Runtime, CLI, server, providers, and MCP
│   ├── tests/                # Python tests
│   └── ui/                   # React and Vite dashboard
├── agentic-v2-eval/          # Rubric and evaluation package
├── tools/                    # Shared provider and benchmark utilities
├── tests/e2e/                # Cross-package tests
├── docs/                     # Published documentation and ADRs
├── examples/                 # Runnable Python examples
├── datasets/                 # Evaluation fixtures
├── infra/                    # Deployment examples
├── load/                     # k6 load harness and committed results
├── otel/                     # Local observability configuration
├── proofs/                   # Lean 4 scheduler proofs
└── scripts/                  # Repo-level checks, eval gate, and doc generators

Package boundaries are intentional. Review Architecture and the relevant ADR before adding a cross-package import.

Documentation

Need	Start here
Install and run one workflow	Quick start
Understand every CLI command	CLI reference
Author a workflow	Workflow authoring
Understand the runtime	Architecture
Integrate with HTTP or WebSocket	API contracts
Configure providers and security	Configuration
Run or extend the UI	UI architecture
Evaluate outputs	Evaluation overview
Deploy and operate the service	Operations
Check known gaps	Known limitations
Review architecture decisions	ADR index

Development

Run commands from the repository root unless a command says otherwise:

just test
just docs
pre-commit run --all-files
npm --prefix agentic-workflows-v2/ui run build

Useful narrower checks:

python -m pytest agentic-workflows-v2/tests -q
python -m pytest agentic-v2-eval/tests -q
python -m pytest tests/e2e -q
npm --prefix agentic-workflows-v2/ui test
python agentic-workflows-v2/scripts/check_docs_refs.py
python scripts/generate_doc_stats.py --check

The runtime coverage gate is 80% over the configured core subset. Optional provider and plugin modules are excluded from that calculation and require their own targeted tests. The UI coverage thresholds are defined in agentic-workflows-v2/ui/vitest.config.ts.

See Contributing for branch, commit, test, documentation, and pull-request requirements.

Security and operational scope

• High-impact tools require approval. When no approval provider is registered, the call is denied.
• API authentication is disabled until AGENTIC_API_KEY or OIDC is configured.
• The built-in rate limiter is process-local. Use a shared edge or gateway limiter for multi-replica deployments.
• Redis can share circuit-breaker state and persist replay events, but it does not replace every in-process control.
• The SSRF guard blocks private, loopback, link-local, and reserved targets by default. Network-level egress controls are still required for hostile DNS or high-assurance environments.

Read Security hardening, Known limitations, and the security policy before deployment.

License

MIT. See LICENSE.