Algen Agent Runtime

Algen Agent Runtime is a typed, provider-neutral Python runtime for building governed AI agents. It provides deterministic execution state, model routing, tool controls, human approvals, retrieval, verification, durable stores, streaming events, and OpenTelemetry instrumentation without binding applications to one model vendor or agent framework.

[!IMPORTANT]
0.1.0a21 is a pre-release, single-node foundation. The repository is suitable for evaluation and contribution, but it is not yet presented as a production distributed control plane. Review the known production gaps, threat model, and security policy before deployment.

Documentation · Why use it · Examples · Changelog

See it in one minute

No API key and no network: the built-in mock provider stands in for the model.

python -m pip install --pre algen-agent-runtime
python -m examples.quickstart_approval.app

The workflow proposes a change, then pauses at an approval node and asks Approve or reject?.
Approve it and the change is applied once, under an idempotency key; reject it and nothing is
written. The final state records the decision, who made it, and the key:

"approval": {"decision": "approved", "decided_by": "example-user", ...},
"result": {"idempotency_key": "approval:299123bf-...", "status": "applied", ...}

The approval is part of the Runtime's execution path, not an instruction in the prompt, so the model
cannot skip it. Pass --approve-all or --reject-all to run it without a prompt.

Why Algen Agent Runtime?

• Provider-neutral execution: route across local and hosted model providers through typed contracts.
• Governance in the execution path: enforce policies, approvals, budgets, verification, and tenant boundaries around every run.
• Durable and observable: persist agent and multi-agent workflow checkpoints, events, conversations, approvals, artifacts, and tool-execution records with optional PostgreSQL and Redis adapters.
• Governed artifact inputs: stage tenant-scoped files with checksums, scan/quarantine state,
  expiry, metadata-only listing, and bounded retention before attaching them to a run. Agents that
  opt in read attached images and PDFs natively, passed by reference and never stored inline.
• Application-friendly: use the same runtime as an embedded Python library or through its FastAPI REST/SSE service.
• Runtime-owned multi-agent DAGs: declare JSON-Schema inputs/outputs, agent, dynamic map-agent, deterministic-handler,
  predicate, and join nodes with conditions, bounded loops and repairs, clarification limits, and
  lifecycle events; compose exact-version child workflows without duplicating their topology.
• Ready-made connectors: email (SMTP, Gmail, Outlook), messaging, databases, documents, GitHub
  and more ship as governed toolkits in
  algen-agent-tools, which builds on this runtime.
• Typed System One decisions: use the optional TypeSafe Jev client for fast Choice, Score, and
  Noul routing gates while keeping generative work in model providers and deterministic work in code.
• Extensible by design: add model providers, tools, planners, context builders, verifiers, stores, and external-framework adapters without changing the state machine.
• Offline-testable: the deterministic mock provider supports tests without credentials, network access, or paid model calls.

The Algen agent lifecycle

Runtime is the open-source execution foundation in a three-product lifecycle:

An agent can be built directly with Runtime or visually in Studio. Studio validates and evaluates the
same Runtime project, publishes a versioned package to Marketplace, and deploys it with
environment-specific credentials. Marketplace consumers import that package into Studio before
configuration and deployment. Secrets and live environment values never belong in a marketplace
artifact.

Typed workflows can reference staged file IDs rather than embedding bytes. See the
artifact lifecycle for upload, checksum, quarantine, retention, and storage
boundaries.

Workflows can also call exact, trusted child workflow versions through a WorkflowRegistry; Runtime
preserves correlation, lineage, checkpoints, pause/approval propagation, and recovery. See
multi-agent workflows and the importable
examples/pattern_child_workflow. For governed outbound messages, see email.

Status and support

Install

Install the latest package from PyPI:

python -m pip install algen-agent-runtime
# Or for pre-release builds:
python -m pip install --pre algen-agent-runtime

Optional integrations are installed as extras:

# Storage, cache, auth
python -m pip install --pre 'algen-agent-runtime[postgres,redis,auth]'

# Model Context Protocol (MCP) client
python -m pip install --pre 'algen-agent-runtime[mcp]'

# External framework adapters
python -m pip install --pre 'algen-agent-runtime[langgraph]'

To install a release from its GitHub tag instead of PyPI:

python -m pip install git+https://github.com/AlgenAI/[email protected]

For development from a checkout:

git clone https://github.com/AlgenAI/algen-agent-runtime.git
cd algen-agent-runtime
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

Verify your installation with the CLI:

algen-agent-runtime --help

Quickly scaffold a new agent project:

algen-agent-runtime new my-agent --template agent
cd my-agent
python app.py

Five-minute offline quickstart

Single agent

This example uses the built-in mock provider, so it requires no API key or external service:

import asyncio

from algen_agent_runtime.config.settings import AppSettings
from algen_agent_runtime.orchestration.container import build_container
from algen_agent_runtime.runtime.client import AlgenAgentRuntimeClient
from algen_agent_runtime.types.contracts import RunRequest


async def main() -> None:
    settings = AppSettings.model_validate(
        {
            "providers": {"mock": {"type": "mock", "default_model": "deterministic"}},
            "agents": [
                {
                    "name": "hello",
                    "version": "1.0.0",
                    "description": "Offline quickstart agent",
                    "system_instructions": "Answer concisely.",
                    "default_model": {
                        "name": "default",
                        "provider": "mock",
                        "model": "deterministic",
                    },
                }
            ],
        }
    )
    container = build_container(settings)
    try:
        result = await AlgenAgentRuntimeClient(container.runtime).run(
            RunRequest(
                agent="hello",
                input="Hello",
                tenant_id="quickstart",
                user_id="local-user",
            )
        )
        print(result.output)
    finally:
        await container.aclose()


asyncio.run(main())

Expected output:

Hello

Multi-agent DAG workflow

Execute a multi-agent DAG with dynamic map-agent fan-out, evidence joining, and synthesis:

import asyncio

from algen_agent_runtime.config.settings import load_settings
from algen_agent_runtime.orchestration.container import build_container
from algen_agent_runtime.runtime.client import AlgenAgentRuntimeClient
from algen_agent_runtime.workflows import MultiAgentWorkflowExecutor
from examples.pattern_multi_agent_fanout.hooks import create_hooks


async def main() -> None:
    settings = load_settings(("examples/pattern_multi_agent_fanout/agent.yaml",))
    container = build_container(settings)
    manifest = settings.workflows["multi-agent-fanout"]
    hooks = create_hooks(container=container, manifest=manifest)
    try:
        executor = MultiAgentWorkflowExecutor(
            AlgenAgentRuntimeClient(container.runtime),
            hooks,
            store=container.workflow_checkpoints,
        )
        state = await executor.run(
            manifest,
            {"question": "Assess a migration to managed queues"},
            tenant_id="quickstart",
            user_id="local-user",
        )
        print(state.values["answer"]["summary"])
    finally:
        container.close()


asyncio.run(main())

Expected output:

Completed bounded parallel research for: Assess a migration to managed queues

For a real local model, follow the Ollama quickstart.

CLI & Project Scaffolding

Algen Agent Runtime provides a CLI for project scaffolding and serving runtime endpoints:

# Scaffold a new agent project (templates: agent, approval, workflow)
algen-agent-runtime new my-agent
algen-agent-runtime new my-approval-agent --template approval
algen-agent-runtime new my-workflow-agent --template workflow

# Test and run the scaffolded project offline
cd my-agent
python app.py
pytest

# List every component the settings register (tools, planners, providers, ...) and its source,
# without running any of them; --path adds a directory for plugin imports
algen-agent-runtime describe --config agent.yaml --path src --json

# Validate the project as Studio will and warn about code Studio cannot run
algen-agent-runtime check agent.yaml --path src
# ...or for a project that runs its own server, without the Studio-only warnings
algen-agent-runtime check agent.yaml --path src --profile standalone

Run the HTTP service

From a source checkout with Ollama running and llama3.2 installed:

ALGEN_AGENT_RUNTIME_CONFIG=examples/quickstart_local_chat/agent.yaml \
  algen-agent-runtime serve

Alternatively, invoking algen-agent-runtime without subcommands defaults to serve for backward compatibility.

In a terminal, serve first prints a banner naming the agent, its model, tools, guards and URLs
(--no-banner turns it off, --banner prints it to a log too). An application that runs its own
server prints the same banner with its own name and rows:

from algen_agent_runtime.banner import print_startup_banner

print_startup_banner(settings, title="ms-email-test", details={"mailbox": "fake (in-process Graph)"})

The default bind is 127.0.0.1:8000. Development-header authentication is intentionally limited to loopback unless the insecure-development override is explicitly enabled.

Start a run:

curl --fail-with-body -X POST http://127.0.0.1:8000/v1/runs \
  -H 'content-type: application/json' \
  -H 'x-tenant-id: demo' \
  -H 'x-user-id: user-1' \
  -H 'x-scopes: runs:write' \
  -d '{"agent":"minimal","input":"Hello"}'

Production deployments should use verified JWT authentication, TLS termination, durable stores, explicit CORS rules, secret references, and infrastructure-level resource controls. See the operations guide.

Agent Manifest UI (Swagger-Style Visualizer)

Similar to Swagger UI for OpenAPI specifications, Algen Agent Runtime provides an in-built interactive UI for inspecting, visualizing, and testing agent.yaml specifications and multi-agent workflows.

Access via running server:
Start the server with the --ui flag:

ALGEN_AGENT_RUNTIME_CONFIG=agent.yaml algen-agent-runtime serve --ui

Then navigate to http://127.0.0.1:8000/agent-ui (or /ui) in your browser to explore the interactive DAG workflow graph, agent configurations, model provider matrices, tools/MCP servers, and test runs via the built-in playground. You can also enable it permanently in agent.yaml:

api:
  agent_ui_enabled: true

Generate standalone static HTML from CLI:
Generate a completely self-contained, offline-compatible static HTML documentation file:

algen-agent-runtime ui --config agent.yaml --output agent-ui.html

# Or open directly in your browser:
algen-agent-runtime ui --config agent.yaml --open

Architecture

flowchart TD
  subgraph Interface["Interface Layer"]
    Client["Application / Studio / REST / SSE"]
  end

  subgraph Workflows["Multi-Agent Workflow Orchestration"]
    WorkflowExec["MultiAgentWorkflowExecutor"]
    Manifest["WorkflowManifest (DAG)"]
    Hooks["WorkflowHookRegistry"]
    WorkflowExec --- Manifest
    WorkflowExec --- Hooks
  end

  subgraph Core["AgentRuntime Execution State Machine"]
    Runtime["AgentRuntime State Machine"]
    Policies["Policy Middleware"]
    Context["Context Builder"]
    Planner["Planner"]
    Router["Model Router"]
    ToolExec["Tool Executor"]
    Verifier["Verifier Pipeline"]
  end

  subgraph Adapters["Infrastructure & Adapters"]
    Providers["Model Providers (Local / Cloud)"]
    Tools["Tools & Resource Connectors"]
    Stores["Run, Memory & Artifact Stores"]
    Events["Events, Audit & Telemetry"]
  end

  Client -->|Execute workflow DAG| WorkflowExec
  Client -->|Direct agent run| Runtime
  WorkflowExec -->|agent / map_agent nodes| Runtime
  WorkflowExec -->|handler hooks| Hooks
  Runtime --> Policies
  Runtime --> Context
  Runtime --> Planner
  Runtime --> Router --> Providers
  Runtime --> ToolExec --> Tools
  Runtime --> Verifier
  Runtime --> Stores
  Runtime --> Events

The orchestration layer depends on typed contracts rather than provider SDKs. The composition root resolves configured adapters and registries, while applications retain ownership of domain prompts, metrics, tools, policies, and data access.

See the full architecture guide for the state machine, component boundaries, persistence model, and extension points.

Capabilities

Provider and integration dependencies remain optional. See the provider compatibility matrix, MCP guide, and framework adapter guide.

Documentation

Importable examples

The source and wheel distributions include the examples package so portable workflow hook
providers remain importable by Algen Agent Studio. Import an example directory—or its agent.yaml
or config/agent.yaml—and Studio preserves the Runtime WorkflowManifest exactly. Credential-free
examples use deterministic mock providers; service-backed case studies retain explicit prerequisites.
The domain case studies case_study_responsible_hiring and pattern_text_to_sql ship only in
the repository and sdist, not the wheel; run them from a checkout.

The workflow examples cover first-class approve/modify/reject checkpoints, human clarification,
bounded repair, exact-version parent/child dispatch, dynamic fan-out,
parallel branches, joins, framework adapters, evaluation gates, and secret-free links to tools,
retrieval, memory, services, storage, and telemetry.

Running examples from the CLI

Every example runs from the terminal without API keys or services, except those that need Ollama or
pgvector. tests/integration/test_all_examples_run.py runs each one in CI, so a new example must
be runnable offline or listed there with the service it needs.

# Multi-agent dynamic fan-out, evidence join, and synthesis
python -m examples.pattern_multi_agent_fanout.app "Assess a migration to managed queues"

# Deterministic handler and resource tool pattern
python -m examples.quickstart_tool.app

# The reference tool project: a Toolkit with a read tool and an approval-gated write tool, from a plugin
python -m examples.quickstart_agent_tool.app

# An approval node: approve, modify or reject a proposal before it is applied
python -m examples.quickstart_approval.app --approve-all

# Human approval checkpoint (interactive prompt, or automated with --approve-all)
python -m examples.pattern_approval_workflow.app --approve-all

# Governed research with retrieval and cited synthesis
python -m examples.pattern_governed_research.app

# A streamed conversation: deltas, a steering message, a tool note, an approval pause and resume
python -m examples.quickstart_conversation.app

# Typed tools behind a precheck, tool-call guards, a user-keyed cache and a usage meter
python -m examples.pattern_guarded_tools.app

# A release gate: evaluation cases decide whether a new agent version is promoted
python -m examples.pattern_evaluation_gate.app

# MCP servers declared in YAML, with operator overrides deciding which tools need approval
python -m examples.pattern_mcp_governance.app

# Hosted-provider examples: the real provider by default, the mock provider with --offline
python -m examples.quickstart_rag.app --offline
python -m examples.quickstart_cloud_chat.app --offline
python -m examples.pattern_provider_fallback.app --offline
python -m examples.pattern_text_to_sql.app --offline

All workflow examples support non-interactive execution in automated environments and CI pipelines:

• --approve-all: automatically approve all approval checkpoints
• --reject-all: automatically reject all approval checkpoints
• --answers-file PATH: supply ordered approval/clarification decisions from a JSON file

Examples that call a hosted provider (quickstart_rag, quickstart_cloud_chat,
pattern_provider_fallback, pattern_text_to_sql, case_study_teaching_assistant) take
--offline: the same agent.yaml with the provider swapped for the mock provider and a scripted
reply (see examples/offline.py). Without --offline they need the provider's key and say so when
it is missing. Traccia export is opt-in in every example
(ALGEN_AGENT_RUNTIME__TELEMETRY__TRACCIA__ENABLED=true with the traccia extra).

Operating patterns

Two examples walk through production controls offline, with mock models and in-process fakes:

# A write whose outcome is unknown: pause, reconcile by idempotency key, resolve over
# /v1/tool-executions, compensate on request, and ToolNotAttemptedError recorded as failed
python -m examples.pattern_side_effect_reconciliation.app

# The HTTP API behind OIDC with a local JWKS stub: scopes from claims, the approval inbox,
# redacted modified parameters, conversation ownership, token revocation and auth.type: caller
# (needs the auth extra: pip install 'algen-agent-runtime[auth]'; without it, it says so and exits 0)
python -m examples.pattern_secured_api.app

See pattern_side_effect_reconciliation
and pattern_secured_api.

Development

make install
make lint
make typecheck
make test

Before opening a pull request, run the whole suite against throwaway PostgreSQL and Redis
containers (scripts/integration-tests.sh, docker or podman), and smoke-test the latest
algen-agent-tools release against a wheel built from your branch. Both steps are described in
CONTRIBUTING.md.

AI coding skills

Repository-scoped skills under .agents/skills help coding agents use the current
Runtime contracts instead of inventing parallel abstractions:

• algen-runtime-contributor — safe, compatible open-source contributions;
• algen-runtime-extension — providers, tools, stores, retrieval, telemetry, and framework adapters;
• algen-agent-builder — Studio-importable single-agent and multi-agent projects;
• algen-agent-connector — governed combinations of APIs, MCP, databases, retrieval, memory,
  persistence, and telemetry.

Invoke a skill by name when supported by your coding agent, for example:

Use $algen-agent-builder to create a multi-agent support workflow with CRM reads,
approval-gated ticket updates, deterministic tests, and a Studio-importable manifest.

The complete contributor workflow, architecture rules, DCO requirement, and test expectations are in CONTRIBUTING.md. Project decision-making and maintainership are documented in GOVERNANCE.md and MAINTAINERS.md.

Security

Do not report vulnerabilities in public issues. Use GitHub private vulnerability reporting as described in SECURITY.md. Never include live credentials, private prompts, customer data, or production endpoints in reports or test fixtures.

License

Licensed under the Apache License 2.0. Third-party components retain their respective licenses. See NOTICE.