Build governed agents. Own the runtime.

Where Runtime fits#

Runtime is the open-source execution layer of the Algen lifecycle. Projects you design in Agent Studio run on Runtime, and the same agent.yaml runs on your laptop, in CI, or behind your own API.

One execution contract, end to end#

Runtime puts governance in the path of execution instead of around it. Every request, model call, tool operation, approval, checkpoint, and output moves through typed contracts with tenant and user context preserved.

Install#

Choose the matching release artifact or published package for the documentation version selected above. Core execution has no provider lock-in; add only the integrations your deployment needs.

$ python -m pip install --pre algen-agent-runtime

# durable stores and JWT auth
$ python -m pip install --pre 'algen-agent-runtime[postgres,redis,auth]'
# declarative MCP servers
$ python -m pip install --pre 'algen-agent-runtime[mcp]'
# LangGraph, OpenAI Agents SDK, AutoGen, CrewAI adapters
$ python -m pip install --pre 'algen-agent-runtime[frameworks]'

$ 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]'

Optional extras#

Five-minute offline quickstart#

The deterministic mock provider needs no credentials, network access, or paid model calls, so the same first run works for local exploration and CI.

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({1
        "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)2
    try:
        result = await AlgenAgentRuntimeClient(container.runtime).run(3
            RunRequest(
                agent="hello", input="Hello",
                tenant_id="quickstart", user_id="local-user",
            )
        )
        print(result.output)
    finally:
        await container.aclose()4


asyncio.run(main())

$ python quickstart.py
Hello

quickstart.py in your editor (sample)

• 1Settings — strictly validated; unknown fields fail fast.
• 2Composition root — build_container wires strategies and adapters from settings.
• 3Typed run — the request carries agent, input, tenant, and user through every boundary.
• 4Lifecycle — always close the container to release stores, clients, and adapters.

1. Define configurationDeclare a provider instance and an agent. In real projects this lives in agent.yaml — see Agents & configuration.
2. Build the composition rootbuild_container wires runtime strategies and adapters from settings without hiding ownership.
3. Submit a typed runrun() returns a RunResult with status, output, citations, warnings, and an execution_summary of decisions, model calls, tool calls, and usage.

Scaffold a project instead#

The CLI generates agent, approval, or workflow projects that run offline out of the box and import cleanly into Agent Studio.

$ algen-agent-runtime new support-desk --template workflow
# templates: agent · approval · workflow   flags: --dir PATH, --force

Architecture#

Runtime is execution as nested authority. Requests enter through the host boundary, are composed from strict configuration, and run inside a native kernel where policies, tools, approvals, and workflows sit in the path of execution. Integration, state, and evidence planes wrap the kernel without owning it.

Interactive architecture map — follows the documentation version selected in the header

• Click a capability to inspect its contracts, source anchor, and direct relationships, then jump to its guide.
• Domains focus one concern, such as governance, across every layer.
• Compare marks what was added, changed, or removed since an earlier release.
• Full screen gives the map the whole window; press Esc to return.

What's new#

Use the version selector in the header to read the documentation for a specific pre-release. Entries are taken from CHANGELOG.md.

Release history#

Agents & configuration#

An agent is a versioned definition: a default model plus instructions, tools, policies, and limits. Agents, providers, workflows, stores, and telemetry are all declared in one strictly validated settings document — usually agent.yaml.

providers:
  local:1
    type: mock
    default_model: deterministic

agents:
  - name: support-assistant
    version: 1.0.0
    description: Answers help-center questions
    system_instructions: Answer only from cited help-center articles.
    default_model:
      name: default
      provider: local2
      model: deterministic
    planning_strategy: react
    max_steps: 83
    guardrail_policy:
      policies: [secrets, pii, prompt_injection, authorization]
    budget:
      max_tokens: 20000
      max_cost_usd: 0.50
      max_latency_seconds: 60

telemetry: {enabled: false}

from pathlib import Path

from algen_agent_runtime.config.settings import load_settings
from algen_agent_runtime.orchestration.container import build_container

settings = load_settings((Path("agent.yaml"),))4
container = build_container(settings)

agent.yaml and app.py (sample) — click the file tabs to switch

• 1Provider instance — a named deployment of an adapter type; several can share one type.
• 2Reference — must resolve to a configured provider instance at load time.
• 3Limits — step count, policies, and budget bound every run.
• 4Load — load_settings merges files and environment into one validated object.

Configuration precedence#

Settings merge in a deliberate order. Later sources override earlier ones; request overrides must be explicitly allowlisted by operators.

Supported hosted and local providers, capability narrowing, and fallback chains are covered in Providers and Provider compatibility.

providers:
  gemini: {type: gemini, default_model: gemini-flash-latest}   # env://GEMINI_API_KEY
  groq: {type: groq, default_model: openai/gpt-oss-120b}       # env://GROQ_API_KEY
agents:
  - name: support-assistant
    default_model: {name: primary, provider: gemini, model: gemini-flash-latest, routing_preference: ordered}
    fallback_models:
      - {name: fast, provider: groq, model: openai/gpt-oss-120b, routing_preference: ordered}

From 0.1.0a21 a model's malformed tool call (arguments that are not valid JSON, not an object, or cut off by the output-token limit) is a retryable InvalidToolCallError from the Anthropic and OpenAI-compatible adapters, not a failed run. The run retries the model call within its retry_policy; a call cut off by the limit is retried with a higher one. The error names the tool and the parse error, never the arguments. Each is recorded as a model.tool_call_invalid audit event and does not count against the provider's circuit breaker.

Context & memory#

Simple agents use bounded context assembly. Multi-step agents can add recoverable summaries, artifact read-back, structured progress, selected skill guidance, and learned memory. Each capability is explicit and governed; a summary or remembered procedure never grants authorization.

Simple agents#

The built-in default builder allows 16,000 estimated message tokens. It loads session history once and protects system instructions, the latest user request, and the newest complete message group. Tool calls and results stay together. A required input that cannot fit fails with BudgetExceededError; orphan tool results fail with ConflictError. Disabled session memory or a zero item limit prevents loading prior turns.

Set a model profile's context_window_tokens and a positive output cap to reserve output, tool definitions, response schemas, profile extensions, and safety headroom before dispatch. Each fallback packs from the original request. Estimates cover normalized text, not a provider tokenizer or image/file costs. Profiles without a configured window retain their previous routing behavior.

Multi-step configuration#

This complete offline manifest enables all context capabilities for demonstration. Default write and destructive-action approvals remain active. Choose only the capabilities and permissions your application needs.

providers:
  mock: {type: mock, default_model: deterministic}
agents:
  - name: context-demo
    version: 1.0.0
    description: Governed context for a multi-step agent
    system_instructions: Verify evidence and keep concise task progress.
    default_model:
      name: bounded
      provider: mock
      model: deterministic
      context_window_tokens: 16000
      context_safety_margin_tokens: 256
    budget:
      max_output_tokens: 2048
    enabled_tools:
      - core.context_read
      - core.working_state_update
      - core.skills_load
      - core.memory_recall
      - core.memory_write
      - core.memory_delete
    tool_permissions: [context.read, context.write, skills.read,
                       memory.read, memory.write, memory.delete]
    context_policy:
      offload_tool_results: true
      compact_history: true
      archive_compacted_history: true
      compaction_trigger_tokens: 12000
      compaction_trigger_ratio: 0.8
      compaction_keep_recent_groups: 6
      compaction_max_input_tokens: 8000
      compaction_max_output_tokens: 1024
      artifact_retention_seconds: 86400
      working_state_enabled: true
      skills_enabled: true
    skills:
      - name: reporting
        version: 1.0.0
        description: Prepare an evidence-based report.
        instructions: Check sources, compare totals, and list open questions.
    learned_memory_policy:
      enabled: true
      max_recall_tokens: 2048
      max_retention_seconds: 2592000

Configuration defaults#

Packing, compaction & recovery#

core.context_read requires context.read and returns at most 4,096 Unicode characters per page using artifact_id, offset, and limit. Follow next_offset until null. Reads and replays check tenant, originating run/user, checksum, purpose, availability, and expiry. New opaque ctx_ IDs avoid incidental numeric PII redaction; existing UUID references still work.

Compaction selects at most one bounded prefix per context build. The effective trigger uses the smallest configured builder/allowed-model allowance after reservations; retrieval reserves evidence space, and working state/skill projections count toward the trigger. The recent-group floor and indivisible tool exchanges can prevent compaction. Summary calls use normal policies, allowlists, deadlines, and the same run token/cost budget. Empty, truncated, oversized, tool-calling, or non-reducing summaries fail without advancing the cursor.

By default, canonical history remains inline. archive_compacted_history: true keeps an absolute context_history_offset, protected context_history_pinned messages, the summary, and the remaining tail. Sources move into a linked archive chain before the smaller checkpoint commits. This reduces historical payload duplication; protected inputs, the uncompacted tail, and artifact references may still grow.

context_policy:
  shorten_older_tool_results: true
  shortened_tool_result_chars: 1200   # 64 to 16384

Working state & progressive skills#

core.working_state_update requires context.write and replaces the five-field record using expected_revision. It follows write approvals and memory-write policies; stale revisions return a small conflict receipt. The bounded assistant projection survives summaries but remains untrusted notes. New runs start empty.

core.skills_load requires skills.read. Its names array replaces the selected guidance (up to four distinct names); an empty array clears it. Configured AgentDefinition.skills contain a name, version, description, instructions, and optional required permissions. Descriptions are visible first; selected bodies are loaded only after authorization and policy checks. Recovery rechecks identity, version, source hash, and permissions.

These are Runtime instruction records, separate from the IDE SKILL.md packs described in Skills & prompts. No filesystem discovery, executable installation, or permission grant occurs. Built-in compaction, working state, and skills require the default or retrieval builder; custom builders keep their own behavior.

Learned memory across runs#

core.memory_recall, core.memory_write, and core.memory_delete require memory.read, memory.write, and memory.delete respectively. Records are scoped to tenant, user, and logical agent name; versions share that namespace. Writes and deletes follow approvals and expected-revision checks. Atomic operation receipts prevent interrupted retries from resurrecting corrected or deleted content.

Recall is explicit, bounded, and based on an exact key or literal case-insensitive substring search. There is no automatic extraction, semantic ranking, injection into every prompt, or conversion of remembered procedures into executable skills. Default writes request one day, capped by the agent's retention policy and anchored to source-run start. Recall/replay checks current revisions and expiry.

For durable storage, install the postgres extra and set storage.learned_memory_store: postgres with storage.postgres_dsn: env://ALGEN_POSTGRES_DSN. Migration 011_learned_memory.sql adds records and replay receipts independently of source-run retention. Maintenance clears expired payloads; content-free revision tombstones and operation receipts currently have no automatic garbage collection.

Evaluations & diagnostics#

Use ContextEvaluationCase, ContextEvaluationArtifact, and ContextEvaluationRunner from algen_agent_runtime.evaluation to check exact message retention, required/forbidden text, estimated token and checkpoint-byte limits, complete tool exchanges, and ordered source recovery. Missing measurements and failed cases block promotion; reports omit source text and exception payloads. Lexical checks and scripted fixtures do not establish real-model factual quality.

python -m examples.context_evaluation
python -m examples.context_compaction
python -m examples.context_offloading
python -m examples.working_state
python -m examples.progressive_skills
python -m examples.learned_memory

context.retrieved adds estimates for total, summary, working-state, catalog, and loaded-skill tokens plus retained/archived history counts. context.compaction.assessed explains planning with fixed reasons such as below_trigger, recent_groups_only, pending_tools, input_limit, or ready. Ready is not a commit receipt: context.compacted follows successful persistence and includes before/after history estimates. New diagnostics are content-free and are distinct from optional model-content telemetry.

a7 upgrade checklist#

• Upgrade strict manifest, checkpoint, and event readers together, including workers. New defaulted fields and event types are incompatible with older strict readers.
• Run the learned-memory migration when using PostgreSQL. Context checkpoint fields themselves require no SQL migration; old checkpoints can recover only their surviving messages.
• Use RunState.append_message() for execution history. Direct edits to packed messages do not append to canonical history.
• Review reduced payload limits and earlier eviction from serialized-message estimates. Required oversized input now fails explicitly.
• Verify the four offline context scenarios, application-specific summary quality, artifact retention, and recovery before enabling optional features.

Detailed contracts: compaction and artifacts, working state, progressive skills, learned memory, and evaluations and diagnostics.

Typed tools#

Every callable becomes a typed ToolDefinition. The governed executor validates arguments, checks permissions, reserves idempotency, handles approval, records outcomes, and redacts results — the model never calls your function directly.

from typing import Any

from algen_agent_runtime.plugins.sdk import PluginManifest, plugin
from algen_agent_runtime.tools.contracts import SideEffect, Tool, ToolContext, ToolDefinition


@plugin(PluginManifest(name="example.utilities", version="1.0.0", publisher="example"))
class UtilitiesPlugin:
    def register(self, context: Any) -> None:
        async def word_count(arguments: dict[str, Any], tool_context: ToolContext) -> dict[str, int]:4
            return {"count": len(arguments["text"].split())}

        context.tools.register(
            Tool(
                ToolDefinition(
                    name="text.word_count",1
                    version="1.0.0",
                    description="Count whitespace-separated words.",
                    input_schema={2
                        "type": "object",
                        "properties": {"text": {"type": "string"}},
                        "required": ["text"],
                        "additionalProperties": False,
                    },
                    output_schema={
                        "type": "object",
                        "properties": {"count": {"type": "integer"}},
                        "required": ["count"],
                    },
                    side_effect=SideEffect.NONE,3
                ),
                word_count,
            )
        )

A read-only tool registered from a plugin (from examples/plugins.py)

• 1Identity — a lowercase, namespaced name plus a version.
• 2Schemas — arguments are validated before execution; results against the output schema.
• 3Classification — decides approval, caching, and recovery posture.
• 4Handler — async; receives validated arguments and a ToolContext.

What the executor does#

Side effects & idempotency#

From 0.1.0a17 an operator settles a call whose outcome is unknown: lists it, records what happened, asks the tool, or undoes it. A tool can answer for itself with a reconcile hook, and an agent can wait for the operator instead of failing. See Side-effect operations.

Enable a registered tool on an agent with enabled_tools, and gate it with required_permissions on the definition. For ready-made, bounded utilities see the opt-in starter tool pack.

Also in 0.1.0a19: ToolContext.session_id (also declarable in cache_context); a tool-result cache with scope: session works instead of failing every cacheable call; Ollama replies no longer carry a model's private reasoning ending in </think>. The document extractors in algen_agent_runtime.security are deprecated and warn on import: use algen_agent_tools.documents (algen-agent-tools 0.2.0a7 or later), which DOCX and PPTX with images now report as review.

Tool behaviour & HTTP tools#

Agents that work through many tool calls, such as coding helpers, need to recover from a failed call, accept a declined action, and call APIs without custom code. Each behaviour is opt-in on the agent definition; defaults keep the earlier fail-the-run behaviour.

Agent tool policy#

From 0.1.0a18 a tool can also report a failure it returns as data, so the model can correct itself without the run failing; see Failures as data.

Declarative HTTP API tools#

http_tools turns an HTTP API operation into a tool. Path placeholders must be required parameters and the host cannot be templated. Credentials are env:// references resolved per call. Requests use the SSRF-safe client without redirects, and settings validation refuses a tool whose host is not in security.allowed_http_hosts. GET is a read; other methods are external side effects that need approval under the default policy. A non-2xx response returns ok: false to the model instead of failing.

security:
  allowed_http_hosts: ["api.github.com"]
http_tools:
  - name: github.issue
    description: Read one GitHub issue.
    method: GET
    url: https://api.github.com/repos/{owner}/{repo}/issues/{number}
    parameters:
      type: object
      properties:
        owner: {type: string}
        repo: {type: string}
        number: {type: integer}
      required: [owner, repo, number]
    auth: {type: bearer, token: env://GITHUB_TOKEN}
    response: {select: /title}

Authentication is none, bearer, basic, or header. Pagination follows link_header or increments a page_param, up to max_pages. timeout_seconds and max_result_bytes bound each request. The tool returns {"ok", "status", "headers", "data", "pages"}. See HTTP API tools and agent tool behaviour.

Authentication is none, bearer, basic, header, or caller (the signed-in user's credential, below). Pagination follows link_header or increments a page_param, up to max_pages. timeout_seconds and max_result_bytes bound each request. The tool returns {"ok", "status", "headers", "data", "pages"}. See HTTP API tools and agent tool behaviour.

http_tools:
  - name: lms.my_courses
    description: List the courses the signed-in user is enrolled in.
    url: https://lms.example.com/api/me/courses
    auth:
      type: caller
      credential: lms_token       # key in the run's credentials (default: authorization)
      # header_name: Authorization  (default)
      # scheme: Bearer              (optional prefix)

Workflow tool steps#

A workflow handler node can call any registered tool, including an HTTP API tool, with handler: tool:<name> and an arguments map. The call goes through the same permissions, approval, and idempotency checks as an agent's tool call, and its result is stored under the node's output_key.

Tool-call guards#

Guards keep a model from wasting a run on calls that cannot succeed, on reads it already made, or on tools when it should be answering. A refused or held-back call never runs; it still answers the model's tool call, with a note saying what to do instead. Their state (tool_refusals, tool_call_counts, seen_read_calls) is kept in RunState, so it survives an approval pause and a restart, and a checkpoint without it still loads. Except for the schema check, every guard is off by default.

Configure#

agents:
  - name: people-os.assistant
    # ...
    max_steps: 30
    enabled_tools: [hr.find_people, hr.update_record, jobs.status]
    tool_policy:
      on_error: return_to_model
      max_refusals_per_tool: 3      # from the third refusal: stop and tell the user
      repeat_guard: true            # an identical read with nothing changed returns a note
      max_calls_per_tool:
        hr.find_people: 5           # a search the model could keep rephrasing
    wrap_up_policy:
      enabled: true
      tool_calls_left: 2            # warn while two or fewer tool calls are affordable
      token_wrap_up_share: 0.75     # from 75% of the token budget: at most two more calls
      token_answer_share: 0.9       # from 90%: answer now
http_tools:
  - name: jobs.status
    # ...
    volatile: true                  # the status changes on its own: never a repeat

Checks before a side effect#

A precheck refuses a change before it runs or anyone is asked to approve it. The Runtime calls it for every call whose side effect is not none or read, whether or not the call needs approval; a call already approved is not prechecked again.

async def config_precheck(
    definition: ToolDefinition, arguments: Mapping[str, Any], earlier: Sequence[EarlierCall]
) -> str | None:
    """Why the change would be refused, or None. ``earlier`` holds the calls planned
    before this one in the same model reply, as (definition, arguments)."""
    ...

Tool(definition, handler, precheck=config_precheck)
# or: @tool(write(approval=True), precheck=config_precheck)

earlier is filled only when a reply's calls run together (parallel_calls); otherwise the earlier calls have already run, one at a time, and the precheck sees their effect. A refused call is answered with {"ok": false, "error": <problem>, "note": <note>} and status refused: nothing ran and nobody was asked.

Repeats, limits and room to answer#

With repeat_guard, a successful write, external or destructive call lets every read run again, and a failed read is forgotten, so its retry runs. This is separate from the run-scoped tool cache: the cache hides a repeat from the model, the guard tells the model it is repeating. An answer takes two steps and each further tool call two more; with wrap_up_policy on, the Runtime computes the calls still affordable after each tool call and adds the notice at or below tool_calls_left, whatever the result's type. There is no notice while continuation_policy still has automatic extensions left.

Events, audit and spans#

Each guarded call also has an agent.tool.call span with its tool.status and tool.guard.* attributes, and the wrap-up notice sets agent.wrap_up.tool_calls_left. None of them carries argument values. Alert on runs whose refusal_limit_reached is true or with many tool.repeated events: the model is stuck on a tool's contract or its instructions. See Tool-call guards and Operations.

Upgrading from the Algen Agent Harness#

• prechecks.py → Tool.precheck, the built-in schema check and tool_policy.max_refusals_per_tool: 3 (the harness's MAX_REFUSED). The planned-call bookkeeping and the serial lock are not needed: calls that need approval run one at a time, in the model's order, and a parallel reply's earlier calls arrive as earlier.
• policies.py ApprovalRules → approval_policy and ToolDefinition.requires_approval (or write(approval=True)).
• repeats.py → repeat_guard, max_calls_per_tool (was turn_call_limits) and volatile (was repeatable_tools).
• allowance.py → wrap_up_policy; the notice is a second text block on the tool message, not keys merged into a dict result.
• metering.py → a UsageMeter passed to build_container; see Usage metering. Counts are per run, which is one turn of a Studio conversation.

Plugins, tools & project validation#

Every component an agent names now has a declared source. Code components are registered by a plugin that agent.yaml names, so describe can list them without running them, check can validate a project the way Studio will, and the build fails on a name nothing registered. Tools are written as typed functions with a policy preset.

Declare a plugin#

A domain_plugins entry is module:attribute or an entry point in the algen_agent_runtime.plugins group, and loads only from security.trusted_plugin_prefixes, checked on module boundaries before anything is imported. A plugin registers tools, planners, context builders, verifiers, response composers, model providers, MCP servers, semantic layers, analytical methods and model services; a name that is already taken raises ConflictError, so a plugin cannot replace a built-in.

security:
  trusted_plugin_prefixes: [crm_agent]
agents:
  - name: crm-assistant
    enabled_tools: [crm.find_account, crm.update_owner]
    tool_permissions: [crm.read, crm.write]
    domain_plugins: ["crm_agent.plugin:CrmPlugin"]

crm = Toolkit("crm", env=("CRM_API_TOKEN",), client=open_crm)


@crm.tool(read())
async def find_account(domain: str) -> Account:
    """Find one account by its web domain."""
    return await (await crm.client()).find(domain)


@crm.tool(write(approval=True))
async def update_owner(account_id: str, owner: str, context: ToolContext) -> Receipt:
    """Change an account's owner."""
    return await (await crm.client()).set_owner(account_id, owner, key=context.idempotency_key)


@plugin(PluginManifest(name="crm-agent.tools", version="1.0.0", publisher="acme"))
class CrmPlugin:
    def register(self, context):
        crm.register(context)

From 0.1.0a18 a plugin package can also be signed, and verified before it is imported; see Plugin signing.

A plugin only constructs and registers in register; a toolkit's client opens at container start or on first use, with env:// secrets, and closes with the container. build_container(additional_tools=...) keeps working for tests, but Studio cannot see it.

Tool presets#

@tool and Toolkit.tool build strict schemas from type hints or Pydantic models and take the description from the docstring. A preset sets the governance fields together; a change is keyed by the idempotency key and never retried.

assert_tool_contract and fake_tool_context test a tool offline. algen-agent-runtime new scaffolds a plugin with a toolkit, and examples/quickstart_agent_tool is a complete project.

@crm.tool(write(), failure_field="ok")
async def change_setting(name: str, value: str) -> ChangeReceipt:
    """Change a setting; {"ok": false, "error": ...} when the name is not a setting."""
    ...


@crm.tool(read(), cache_context={"user_id"})
async def my_open_orders(context: ToolContext) -> list[Order]:
    """List the signed-in user's open orders."""
    await context.emit_note(title="Looked up open orders", suggestions=["Show overdue only"])
    ...

result = await runtime.run(request, credentials={"authorization": request_headers["authorization"]})
# After an approval or clarification pause, supply them again: none are kept.
await runtime.resume(run_id, tenant_id, {"decision": "approved"}, credentials=fresh_credentials)

@crm.tool(read())
async def my_open_tickets(context: ToolContext) -> list[Ticket]:
    """List the open tickets assigned to the signed-in user."""
    authorization = context.credentials.get("authorization")
    if authorization is None:
        raise ToolExecutionError("authentication required: sign in again and retry")
    client = await crm.client()
    return await client.tickets(assignee="me", headers={"Authorization": authorization})

Startup validation, describe and validate#

build_container fails when an agent's enabled_tools, planning_strategy, response_composer, verification_policy.verifiers, context_builder or model provider names something nothing registered, and suggests the closest name. MCP tools are checked when their server connects. runtime.component_check: warn logs instead while a project moves to a plugin.

algen-agent-runtime describe --config agent.yaml --path src --json
algen-agent-runtime check agent.yaml --path src

In Studio#

Studio validates the same names without importing project code. It describes the Runtime's and the manifest's components itself; for declared plugins, each managed build runs describe --json in the build sandbox (no network, read-only, unprivileged) and keeps the result with the build, for every revision on the same code that declares the same plugins. The overview's Code and Studio panel lists the project-code warnings, and each agent's Tools section shows what every tool changes, whether it asks for approval first and what registers it. An exported project declares its tools in agent_service/plugin.py and validates clean.

From 0.1.0a21 a project that runs its own server or workers, rather than deploying through Studio, checks with algen-agent-runtime check agent.yaml --path src --profile standalone. It keeps every error but leaves out the warnings about code Studio cannot run (OWN_CONTAINER, DIRECT_ENV_READ, constructor and post-build registration, code-defined agents). The default profile, studio, is unchanged; the report's profile field names the one used.

Multi-agent workflows#

Runtime-owned DAGs compose agent nodes, deterministic handlers, dynamic fan-out, predicates, joins, bounded loops, repair, approvals, and exact-version child workflows. Domain behavior is named in YAML and implemented in a hook provider — never embedded as code in the manifest.

workflows:
  approval-quickstart:
    name: approval-quickstart
    version: 1.0.0
    hook_provider: examples.quickstart_approval.hooks:create_hooks1
    nodes:
      - id: propose2
        kind: agent
        agent: approval-proposer
        input_builder: approval.propose
        output_key: proposal
      - id: approve3
        kind: approval
        depends_on: [propose]
        output_key: approval
        approval:
          prompt: Review this synthetic change before it is applied.
          review_from: [proposal.change]
          parameters_from: proposal.parameters
          allow_modification: true
          rejection_policy: skip_dependents
          expires_seconds: 1800
      - id: decide4
        kind: handler
        depends_on: [approve]
        handler: approval.apply
        output_key: result

from typing import Any

from algen_agent_runtime.workflows import WorkflowHookRegistry


def create_hooks(**_: Any) -> WorkflowHookRegistry:
    hooks = WorkflowHookRegistry()

    def propose(context: Any) -> dict[str, Any]:
        change = str(context.state.values["question"])
        return {"change": change, "parameters": {"change": change}}

    def apply(context: Any) -> dict[str, Any]:
        approval = context.state.values["approval"]
        return {"status": "applied", "parameters": approval["parameters"]}

    hooks.register_builder("approval.propose", propose)
    hooks.register_handler("approval.apply", apply)
    return hooks

$ python -m examples.quickstart_approval.app --approve-all
# --approve-all resolves the checkpoint; --reject-all and --answers-file PATH also work
# omit them in a TTY to approve or reject interactively

An approval workflow from examples/quickstart_approval (excerpt)

• 1Hook provider — trusted Python that supplies named builders, handlers, and schemas.
• 2Agent node — invokes a registered agent; output stored under output_key.
• 3Approval node — durable human checkpoint with optional parameter edits.
• 4Handler node — deterministic application logic after the decision.

Node kinds#

The Runtime's workflow guide (0.1.0a21) documents the hook factory's keyword arguments under serve (container, manifest, environment), every WorkflowHookContext field and which hooks receive it, each hook kind's signature, and how serve loads hooks and recovers workflows: hook provider reference. Its MCP guide documents the tool-result shape, and its operations guide has a route-by-route scope table.

Conversation turns#

A conversation turn is one user message and the assistant message that answers it. From 0.1.0a16 the built-in runtime conversation handler, which runs one agent run per turn, streams the answer as it is written, pauses the turn when its run needs an approval or an answer, and resumes into the same assistant message, also after a restart.

Streaming#

When conversation_streaming.enabled is true (the default) and every model the agent may use can stream, the turn's run is started with stream=True and its text reaches GET /v1/conversations/{id}/events as assistant.message.delta events, with data {message_id, delta}. A turn whose models cannot stream gives only the final message, as before.

conversation_streaming:
  enabled: true           # false: only the final message, and turns use the model-response cache again
  delta_interval_ms: 50   # at most one delta event per interval per turn; smaller deltas are coalesced
  delta_max_chars: 2048   # largest delta event; a fuller buffer is sent at once, in pieces of this size

Deltas are provisional and may include text the model wrote before a tool call: the assistant.message.completed message is the record. They carry only model text, never tool arguments or results, and are not audited. Streamed model calls bypass the model-response cache, as streaming runs always have.

Approvals and questions in a turn#

When the turn's run awaits an approval or a clarification, the assistant message moves to awaiting_approval or awaiting_input. Its pending action, also in the assistant.message.awaiting_approval or assistant.message.awaiting_input event, carries what a UI needs to ask: turn_id, run_id, approval_id, tool, proposed_action, side_effect_summary, risk, expires_at, options, redacted_parameters (as in the run's approval.required event; never raw arguments) and the tool's parameters_schema, or the question to answer.

turn_id is the user message id (pending.turn_id), and the authenticated user is recorded as decided_by. Both routes return 202 with the assistant message id and streaming; the answer resumes the run, which keeps streaming into the same assistant message (assistant.message.resumed). Another tenant or user gets 404. An answer of the wrong kind, a second answer, or an answer to a turn that no longer waits gets 409; an answer after the approval expired ends the turn expired and gets 409. A rejected action ends the turn failed with the Runtime's “Proposed action was rejected.” text (metadata.reason: approval_rejected).

from algen_agent_runtime.conversations import ConversationApprovalDecision, ConversationInputAnswer

await container.conversations.respond(
    conversation_id, turn_id, tenant_id, user_id,
    ConversationApprovalDecision(decision="approved"),
    credentials={"authorization": request_headers["authorization"]},
)
# A question is answered with ConversationInputAnswer(text="The Berlin office").

ConversationService.respond(conversation_id, turn_id, tenant_id, user_id, response, *, credentials=None) takes a ConversationApprovalDecision (approved, rejected, or modified with modified_parameters) or a ConversationInputAnswer. ConversationPendingAction, ConversationTurnResponse, PendingTurnExpiredError and ResumableConversationHandler are exported from algen_agent_runtime.conversations too, and ConversationTurnResult takes the outcomes awaiting_approval, awaiting_input, cancelled and expired with pending.

One waiting turn per conversation#

Only one turn per conversation can wait. A new message while one waits is refused with 409 naming the waiting turn id: answer it, or cancel it with DELETE /v1/conversations/{id}/active-response, which also cancels the paused run. Deleting the conversation cancels it too.

Restarts#

The pending action is stored on the assistant message and the paused run in the run store, so a restart loses neither and nothing re-runs. recover() leaves a waiting turn waiting, and the user can answer it after the restart. If the run was resumed but the process stopped before the message was updated, recovery follows the run to its end instead of running it again; if the run ended while the turn waited, the turn ends with that outcome. ConversationService.reconcile_pending_turns() does this, and the maintenance sweep runs it for turns whose paused run it expires (reconciled_pending_turns). A custom handler opts in by implementing ResumableConversationHandler (resume, follow, settle, pending_state, cancel_pending).

Credentials of the caller#

ConversationService.submit(..., credentials=...) and respond(..., credentials=...) pass the caller's credentials to the turn's run for its tools, exactly as Runtime.start and resume do (see Credentials of the caller). They are held in memory only, never stored, emitted, audited or logged; a turn that pauses drops them, so pass them again when answering. The HTTP routes never forward request headers as credentials. A custom handler receives them by accepting a credentials keyword argument in handle; passing credentials to a handler that does not is a ConfigurationError.

Message statuses and events#

assistant.message.resumed data is {turn_id, kind, decided_by} plus approval_id and decision for an approval, or the answer text for input. The awaiting, completed, failed and expired events carry the assistant message, with turn_id on the awaiting events. A resumed turn opens a new conversation.turn span with conversation.turn.resumed=true; its agent run continues the run's original trace.

File attachments#

From 0.1.0a19 an agent can read files a caller gives it: a photo of an ID document, a scanned invoice, a screenshot or a PDF. The model sees the file natively (vision or PDF input) in the same call as the question. Files are passed by reference to an uploaded artifact, never as inline bytes. Attachments are off by default: an agent or workflow opts in, and text-only runs are unchanged.

Opt in#

agents:
  - name: kyc-reader
    attachments:
      enabled: true
      types: [image/png, image/jpeg, image/webp, image/gif, application/pdf]  # the default
      max_count: 5          # default 5, at most 32
      retention: turn       # turn (default) or session
security:                   # the deployment's outer limits; an agent can only narrow them
  allowed_attachment_types: [image/png, image/jpeg, image/webp, image/gif, application/pdf]
  max_attachments_per_run: 10
  max_attachment_bytes_total: 20971520   # 20 MiB per run
  upload_scanner: basic                  # none (default) or basic

GET /v1/agents and GET /v1/workflows return each one's attachments policy. Show an attach control only when it has enabled: true and its default or fallback model reports the capability (images, or files for PDF), and use types as the file picker's accept list.

Upload, then run#

curl -X POST -H 'X-Tenant-ID: acme' -H 'X-User-ID: clerk' -H 'X-Scopes: runs:write' \
  -H 'Content-Type: application/json' http://localhost:8000/v1/runs -d '{
    "agent": "kyc-reader",
    "input": "What kind of document is this, and is it expired?",
    "attachments": [{"artifact_id": "9b2c…", "media_type": "image/jpeg"}]
  }'

Upload first with POST /v1/artifacts. The same attachments list is accepted by RunRequest.attachments, POST /v1/conversations/{id}/messages, POST /v1/workflows/{name}/runs, algen-agent-runtime run AGENT "question" --attach passport.jpg and evaluation cases (GoldenQuestion.attachments). input stays required; media_type is optional, and when given must match the file's real type.

Checked before any model call#

• The agent (or workflow) opted in, and every artifact exists in the caller's tenant and is available.
• The real type, read from the bytes, is allowed by the agent and by security.allowed_attachment_types. Formats models do not read, such as HEIC, are refused; nothing is converted.
• Count and total size are within max_count, max_attachments_per_run and max_attachment_bytes_total; images are at most 5 MB and 8000 px a side, PDFs at most 32 MB.
• A configured model can read them. Models without the capability are skipped, fallbacks included; a file is never silently dropped.

Hosts can veto or filter files with a policy on the attachments point. It receives {artifact_id, media_type, name, size_bytes, sha256} per file, never content.

References in history, bytes at dispatch#

History, memory, checkpoints, conversation records, events, audits and spans hold only file blocks (artifact_id, media_type), never base64, even with telemetry content capture on. The bytes are loaded onto a copy of the request just before each provider call. A file deleted or expired since becomes a note instead of failing the run. With retention: turn the file is replaced by a note in session memory after the turn, so later turns do not pay for it again; context budgets count about 1,600 tokens per image and 8,000 per PDF.

Tools and workflows#

ToolContext.attachments lists the run's files and await context.read_attachment(artifact_id) returns one with its bytes, from the run's tenant only. In algen-agent-tools, documents_toolkit(artifact_loader=runtime_attachment_loader) extracts the text of an attached document through the document security checks. A workflow declares attachments: {enabled: true}, and each agent node that should see the files sets pass_attachments: true; settings validation fails when a node passes files to an agent that does not accept them.

Scanning and retention#

Uploads start pending_scan and cannot be attached until something makes them available. security.upload_scanner: basic runs BasicArtifactScanner on each upload: it quarantines an image or PDF whose bytes are not what it claims, is malformed or exceeds model limits, and records scan evidence before the status changes. It does not inspect content; add your own ArtifactScanner for that. ID documents and similar uploads are sensitive personal data: give them a short expires_in_seconds and schedule ArtifactStore.purge_expired().

Agent Manifest UI#

A Swagger-style visualizer for agent.yaml. It reads validated settings and renders the agent catalog, workflow DAG, provider and model matrix, tools and MCP servers, retrieval stores, a read-only execution view, and the raw manifest. Output is self-contained HTML with no CDN dependency.

providers:
  local: {type: mock, default_model: deterministic}
  openai:
    type: openai
    default_model: gpt-4o-mini
    api_key: env://OPENAI_API_KEY
agents:
  - name: support-assistant
    version: 1.2.0
    description: Answers from cited help-center articles
    system_instructions: Answer only from cited help-center articles.
    default_model: {name: default, provider: openai, model: gpt-4o-mini}
    fallback_models:
      - {name: offline, provider: local, model: deterministic}
    guardrail_policy: {require_citations: true}
    budget: {max_tokens: 20000, max_cost_usd: 0.50, max_latency_seconds: 60}
  # triage-agent and refund-proposer omitted
workflows:
  refund-review:
    name: refund-review
    version: 1.0.0
    hook_provider: support_desk.hooks:create_hooks
    nodes:
      - {id: intake, kind: agent, agent: triage-agent, output_key: ticket}
      - {id: lookup-order, kind: handler, depends_on: [intake], handler: orders.lookup, output_key: order}
      - {id: kb-search, kind: agent, depends_on: [intake], agent: support-assistant, output_key: policy}
      - {id: merge, kind: join, depends_on: [lookup-order, kb-search], join_strategy: json_array, output_key: evidence}
      - {id: propose, kind: agent, depends_on: [merge], agent: refund-proposer, output_key: proposal}
      - id: approve-refund
        kind: approval
        depends_on: [propose]
        output_key: approval
        approval: {prompt: Review this refund., allow_modification: true, expires_seconds: 3600}
      - {id: issue-refund, kind: handler, depends_on: [approve-refund], handler: refunds.issue, output_key: result}
storage: {run_store: postgres, approval_store: postgres, postgres_dsn: env://ALGEN_AGENT_RUNTIME_POSTGRES_DSN}

Interactive sample for a support-desk project — switch views, click workflow nodes, and edit the execution form. Illustrative Algen-themed rendering; the shipped UI's styling may differ.

• 1Views — overview, workflow DAG, agents, providers, tools and MCP, knowledge, execution, and source.
• 2Validation — the page is built from validated settings, so references and secrets are already checked.
• 3Export — save the whole manifest as one self-contained HTML file.
• 4Workspace — the workflow canvas with a node inspector for each contract.
• 5Spec endpoint — the same data as JSON at /agent-ui/spec.

$ algen-agent-runtime ui --config agent.yaml --output agent-ui.html --open
# export-ui is an alias of ui; use '-' to write HTML to stdout
$ algen-agent-runtime export-ui -c config/agent.yaml -o -

$ algen-agent-runtime serve --config agent.yaml --ui
# GET /agent-ui        interactive page (alias: /ui)
# GET /agent-ui/spec   structured JSON manifest

api:
  agent_ui_enabled: true
  agent_ui_path: /agent-ui

Skills & prompts#

Runtime ships Agent Skills: SKILL.md instruction packs that teach coding agents in your IDE how to build on Runtime the right way — offline first, governed tools, env:// secrets, validated manifests, and Studio-importable projects. Copy the skills into your project, then start from a prompt below.

Available skills#

Add skills to your project#

1. Copy the skill foldersEach skill is a folder with a SKILL.md and a references/ directory it reads on demand — copy the whole folder, not just the file.
2. Place them where your agent looksYour coding agent loads a skill when its description matches the task. You can also name the skill in your prompt.
3. PromptCopy a prompt from the library below, replace the [placeholders], and send it in agent mode.

$ git clone --depth 1 https://github.com/AlgenAI/algen-agent-runtime.git /tmp/algen-runtime
$ mkdir -p .agents/skills
$ cp -R /tmp/algen-runtime/.agents/skills/algen-agent-builder /tmp/algen-runtime/.agents/skills/algen-agent-connector .agents/skills/
# extending Runtime itself? also copy algen-runtime-extension and algen-runtime-contributor

---
name: algen-agent-builder
description: Create or update an Algen-compatible single-agent or multi-agent project that uses Runtime manifests, governance, tests, and Studio-importable packaging.
---

# Build an Algen agent project

Start by choosing the smallest topology that fits: one agent for a single governed conversation, or
a Runtime `WorkflowManifest` for coordination. Scaffolding is available via the CLI:
`algen-agent-runtime new <name> [--template agent|approval|workflow]`. Read `references/project-shape.md`;
for a workflow, also read `references/workflows.md`. Use `$algen-agent-connector` when external tools,
safe starter tools (`algen_agent_runtime.tools.starter`), databases, retrieval, MCP, or remote APIs are part
of the request.

Prefer configuration for provider routing, policies, memory, retrieval, storage, telemetry, and
workflow topology. Keep only domain-specific payload builders, validators, schemas, predicates, and
deterministic handlers in the project's hook provider. Never implement a second scheduler or a
Studio-specific workflow dialect. For automated CI and headless evaluation, use non-interactive workflow
options (`--approve-all`, `--reject-all`, `--answers-file PATH`).

Produce an importable project with secret references, bounded execution, deterministic offline
tests, documented optional dependencies, and a small runnable entry point. A project intended for
Studio must keep its Runtime configuration and `WorkflowManifest` authoritative. Studio sees only
what the settings declare, never constructor arguments, so:

- Every name an agent uses (`enabled_tools`, `planning_strategy`, `response_composer`, `verification_policy.verifiers`,
  `context_builder`, `guardrail_policy.policies`, provider types) must come from the Runtime,
  the settings (`http_tools`,
  `mcp_servers`, `providers`, `retrieval`) or a plugin listed in `domain_plugins`. Register code
  components from a declared plugin, never through `build_container(additional_tools=...)`; see
  `docs/plugins.md`.
- Credentials only through `env://` references; list a plugin's variables in `PluginManifest.env`.
- If the project runs its own server, workers or approval flow, say plainly that Studio runs only
  the Runtime contract, not that code.
- `build_container` fails on any name no source registered and suggests the closest one; fix the
  name or its registration, never switch `runtime.component_check` to `warn` to hide it.
- A project that runs its own host (not Studio) checks with
  `algen-agent-runtime check agent.yaml --path src --profile standalone`, which leaves out the
  Studio-only warnings but keeps every error.
- Before calling a project Studio-importable, run `algen-agent-runtime check agent.yaml --path src`.
  It must report no errors; read every warning to the user, since each names code Studio will not
  run or cannot see. `algen-agent-runtime describe --path src` shows the full inventory, and
  `docs/studio-compatibility.md` lists what Studio can and cannot see.
- Write tools as typed functions with `@tool` or a `Toolkit` and a preset (`docs/tool-authoring.md`),
  and test each with `assert_tool_contract`.

An agent that makes many tool calls or changes state should use the Runtime's own guards rather than
rules in its instructions or plugin code: prechecks, refusal limits, the repeat guard and call
limits, the wrap-up notice and shortened older tool results. A tool that must act as the signed-in
user reads the caller's credentials from `ToolContext.credentials`. See "Tool-heavy and acting
agents" in `references/project-shape.md`.

Validate YAML by loading it through the current Runtime model rather than relying on syntax alone.
Run the project smoke test and relevant Runtime tests. Do not publish to a marketplace or deploy
unless the user explicitly requests that external action.

---
name: algen-agent-connector
description: Connect an Algen Runtime agent or workflow to typed tools, MCP, HTTP APIs, databases, retrieval stores, model providers, memory, persistence, or telemetry without bypassing governance.
---

# Connect an Algen agent

Identify the requested systems, data direction, side effects, credentials, network boundary,
tenancy, and expected failure behavior. Read the matching parts of `references/connectors.md` and
combine connectors only when the use case needs them.

Expose external actions as typed Runtime tools or workflow resources. Do not call a connector
directly from orchestration code to bypass policy, approvals, idempotency, audit events, budgets, or
telemetry. Use secret references in configuration and resolve values only at execution time.
When a tool acts as the signed-in user, forward the caller's credentials from
`ToolContext.credentials`; the host supplies them on every run and resume, and they are never
persisted. Remote MCP servers that need per-user sign-in use the Runtime's MCP OAuth, not a token
in an environment variable.

For each connection, declare least-privilege permissions, read/write behavior, idempotency, strict
schemas, timeout, retry policy, concurrency, result-size limit, and allowed destinations. Mark it on
the consuming workflow node with a `WorkflowResourceReference` so Studio can display the actual
topology.

Test with a deterministic fake or local fixture. Live credentials and paid services belong only in
explicit live tests. Document the required Runtime extra and environment variable names without
including secret values.

---
name: algen-runtime-extension
description: Add or review an Algen Agent Runtime extension such as a model provider, tool adapter, retrieval backend, persistence store, telemetry integration, or external-framework adapter.
---

# Extend Algen Agent Runtime

First identify the extension point and inspect its Protocol, registry, existing adapter, contract
tests, optional extra, and documentation. Read only the matching section of
`references/extension-points.md`.

Implement against Runtime contracts rather than leaking a vendor SDK into orchestration or public
state. Normalize vendor inputs, outputs, usage, errors, streaming behavior, and cancellation at the
adapter boundary. Keep the dependency optional and fail with an actionable installation message
when its extra is absent.

Treat all extension inputs as untrusted. Carry tenant and identity context, enforce permissions,
validate outbound destinations, classify side effects and idempotency, bound time and result size,
and prevent secrets from entering logs or persisted events.

Add deterministic contract tests without credentials. Put live integration tests behind the `live`
marker. Update the optional dependency extra, compatibility documentation, an importable example
when useful, and `CHANGELOG.md` for user-visible support.

---
name: algen-runtime-contributor
description: Implement or review contributions to Algen Agent Runtime while preserving its public API, provider neutrality, tenant isolation, optional dependencies, and repository boundary.
---

# Contribute to Algen Agent Runtime

Work from the Runtime repository root. Read `CONTRIBUTING.md` and the documentation most closely
related to the change before editing. Use `references/change-checklist.md` when planning or reviewing
a code change.

Keep reusable execution contracts, orchestration, governance, persistence, and integrations in
Runtime. Keep Studio UI, project management, marketplace, and product-specific behavior out of this
repository. Domain behavior belongs in an application hook provider, not in the Runtime executor.

Preserve these invariants:

- provider-neutral public contracts and typed boundaries;
- explicit tenant, user, permission, secret, and idempotency context;
- deterministic offline behavior and tests by default;
- optional provider, database, vector-store, telemetry, and framework dependencies;
- stable error codes and forward migrations for persisted data;
- secret-free configuration committed to source control.

Add the narrowest meaningful test and cover the relevant failure path. Update public documentation,
examples, and `CHANGELOG.md` for user-visible behavior. Run the repository quality gates before
finishing; report any gate that could not run and why. Provide a concise, well-structured Git commit
message summarizing the verified changes. Do not commit, push, publish, or open a pull
request unless the user explicitly requests it.

The skills bundled with Runtime — Copy takes the active SKILL.md

Prompt library#

Each prompt names the skill it relies on and keeps the first run offline on the mock provider. Replace the highlighted [placeholders] before sending.

Use the algen-agent-builder skill to create an Algen Agent Runtime project named [support-assistant] that [answers customer questions about our return policy].

- Scaffold it with algen-agent-runtime new [support-assistant] --template agent.
- Use the mock provider with the deterministic model so the first run needs no API keys. Add [OpenAI] as a second provider instance with its key as an env:// reference.
- Keep the default guardrails, set max_steps to [8], and set a budget of [20000] tokens and [$0.50] per run.
- Add an offline pytest smoke test and a short README.

Validate agent.yaml by loading it with load_settings, then run the tests.

Use the algen-agent-builder and algen-agent-connector skills to give the [support-assistant] agent a tool that [looks up an order by ID from https://api.example.com/orders].

- Define it as a ToolDefinition with strict input and output JSON Schemas, side_effect READ, a timeout, and a result-size limit.
- Read the base URL and token from env:// references; never hard-code secrets.
- Allow outbound traffic only to [api.example.com].
- Enable the tool on the agent and test it with a deterministic fake, not the live API.

Use the algen-agent-builder skill to create an approval workflow for [issuing refunds above $50].

- Scaffold it with --template approval.
- Nodes: an agent node that proposes the [refund], an approval node with allow_modification and a parameters_schema for [amount and reason], and a handler node that applies the change idempotently.
- Use rejection_policy skip_dependents and expires_seconds [3600].
- Support --approve-all, --reject-all, and --answers-file for headless runs, and add tests for approve, modify, and reject.

Use the algen-agent-builder skill to build a multi-agent workflow that [researches a company from several angles and writes a cited brief].

- A planner agent returns a bounded list of [3–5] sub-questions.
- A map_agent node runs one researcher agent per item with a concurrency limit.
- A join node combines the findings, then a writer agent produces the brief.
- Validate every node output with JSON Schema and keep domain logic in the hook provider.
- Run the whole workflow offline on the mock provider in tests.

Use the algen-agent-connector skill to add retrieval to [support-assistant] over [the Markdown files in ./knowledge].

- Index with tenant filters, treat retrieved text as untrusted, and require verified citations in answers.
- Use the in-memory vector store in tests and [pgvector] in production behind its optional extra.
- Add test cases where the answer must cite a source and one where it must decline.

Use the algen-agent-connector skill to connect [support-assistant] to the [inventory] MCP server at [https://mcp.example.com/mcp] over streamable_http.

- Declare it under mcp_servers with allowed_tools limited to [lookup_item and update_stock].
- Put the token in auth_token_ref as an env:// reference.
- Add tool_policies so [update_stock] is side_effect write and non_idempotent, which makes it require approval.
- Mark the server optional and test against a fake MCP server.

Use the algen-agent-connector skill to run our existing [LangGraph] agent in [app/graph.py] under Algen Agent Runtime.

- Register it explicitly through build_container(framework_adapters=...); do not import it from YAML.
- Propagate tenant, user, and session identity, and normalize streaming and cancellation.
- Document which tools and guardrails stay framework-owned and which Runtime governs.
- Add a credential-free test using a scripted or fake model.

Use the algen-agent-builder skill to add an offline evaluation suite to [support-assistant].

- Write [10] golden cases covering the most common requests and answers the agent must never give.
- Check expected phrases, forbidden content, tool calls, and citations.
- Run on the deterministic mock provider in CI and fail the build below a [100%] pass rate.

Use the algen-agent-builder and algen-agent-connector skills to review [this project] against the Algen Agent Runtime production checklist.

- Durable PostgreSQL and Redis stores with env:// DSNs.
- JWT authentication instead of development headers, with rate limits on.
- Outbound allowlists, timeouts, and telemetry with content capture off.
- Tests for approval resume and interrupted non-idempotent tools.

List the gaps first, then fix the ones inside this project.

Use the algen-runtime-extension skill to add a model provider adapter for [Provider X] to Algen Agent Runtime.

- Implement it against the Runtime provider contract and normalize requests, responses, streaming, usage, errors, and cancellation.
- Keep the SDK an optional extra that fails with an actionable install message.
- Add credential-free contract tests, put live tests behind the live marker, and update the docs and CHANGELOG.

Use the algen-runtime-contributor skill to implement [the change] in Algen Agent Runtime.

- Follow CONTRIBUTING.md and keep public contracts provider-neutral.
- Add the narrowest meaningful test, including the failure path.
- Update docs, examples, and CHANGELOG for user-visible behavior, and run the quality gates.

Do not commit or push until I ask.

Policies & budgets#

Governance is evaluated at explicit boundaries, not inferred from prompts. Input and output policies, model permissions, budgets, tool classifications, and human decisions remain separately auditable, with stable denial codes.

from algen_agent_runtime import MeterRefusedError

class CreditMeter:  # satisfies UsageMeter
    async def reserve(self, *, max_input_tokens: int, max_output_tokens: int) -> object:
        hold = await wallet.hold(max_input_tokens + max_output_tokens)
        if hold is None:
            raise MeterRefusedError("You have used this month's model allowance.")
        return hold

    async def settle(self, ticket: object, usage: TokenUsage) -> None:
        await wallet.charge(ticket, usage.input_tokens + usage.output_tokens)

    async def release(self, ticket: object) -> None:
        await wallet.cancel(ticket)

container = build_container(settings, usage_meter=CreditMeter())

from dataclasses import dataclass

from algen_agent_runtime import MeterCall, MeterRefusedError
from algen_agent_runtime.orchestration.container import build_container
from algen_agent_runtime.types.contracts import TokenUsage

# Credits per token, by model; anything else costs 1.
MODEL_WEIGHTS = {"gpt-4.1": 4.0, "gpt-4.1-mini": 1.0}


@dataclass(frozen=True)
class Hold:
    account: str
    call: MeterCall  # kept for settle, which receives only the ticket
    hold_id: str


class CreditMeter:  # satisfies UsageMeter
    def __init__(self, wallets) -> None:
        self._wallets = wallets

    async def reserve(
        self, *, max_input_tokens: int, max_output_tokens: int, call: MeterCall
    ) -> object:
        # Charge the workspace when the host passed one in RunRequest.metadata, else the tenant.
        account = call.metadata.get("account_id") or call.tenant_id or "unattributed"
        weight = MODEL_WEIGHTS.get(call.model, 1.0)
        hold_id = await self._wallets.hold(account, (max_input_tokens + max_output_tokens) * weight)
        if hold_id is None:
            raise MeterRefusedError("You have used this month's model allowance.")
        return Hold(account=account, call=call, hold_id=hold_id)

    async def settle(self, ticket: object, usage: TokenUsage) -> None:
        assert isinstance(ticket, Hold)
        weight = MODEL_WEIGHTS.get(ticket.call.model, 1.0)
        tokens = (usage.input_tokens + usage.output_tokens) * weight
        await self._wallets.charge(ticket.account, ticket.hold_id, tokens)

    async def release(self, ticket: object) -> None:
        assert isinstance(ticket, Hold)
        await self._wallets.cancel(ticket.account, ticket.hold_id)


container = build_container(settings, usage_meter=CreditMeter(wallets))

From 0.1.0a18 a deployment can add rules every agent runs, as signed policy bundles, and decide what each boundary does when a policy fails; see Policy bundles & fail modes.

Policy bundles & fail modes#

The policy engine runs at eleven boundaries. From 0.1.0a18 each boundary has an explicit fail mode for a policy that raises or times out, a deny always beats an approval requirement, and an operator can distribute rules every agent runs as an Ed25519-signed bundle verified at start-up.

Boundaries and fail modes#

When a policy raises, returns something other than a PolicyDecision, or runs past policies.evaluation_timeout_seconds, the boundary's fail mode decides. closed refuses the value as a deny would (reason_code: policy.error, a PolicyDeniedError); open skips only the failed policy and lets the others decide. A policy that raises PolicyDeniedError has decided: that is a denial in either mode.

policies:
  on_error: closed                 # closed (default) | open, for every boundary
  boundary_on_error:               # per-boundary overrides
    after_memory_write: open
  evaluation_timeout_seconds: 5    # per policy; unset (no limit) by default

Every boundary defaults to closed, which is what each already did (the run or call failed); what changes is the shape of the failure and that it is recorded. Each handled error writes a policy.error audit record (outcome fail_closed or fail_open), adds to the algen_agent_runtime.policy.errors counter and logs policy_error with the error's type, never its text; the run's policy.evaluated event carries fail_mode and error_count. Alert on any fail_open record. Fail modes apply to the built-in CompositePolicyEngine; guards, approvals, injection screening and query governance always refuse.

A deny wins#

At one boundary a deny from any policy now wins over an earlier policy's require_approval or require_clarification: the later policies still run, so a call a bundle denies is refused instead of first being put to an approver. A deny at plan_tool now refuses the call; before, only require_approval was honoured there and a denial waited until before_tool, after an approval could have been asked for.

Signed policy bundles#

A bundle is one YAML or JSON file of declarative rules. Its name, version, issued_at and expires_at are inside the signed bytes. Each bundle runs as the policy bundle:<name> for every agent, whatever its guardrail_policy, so an agent definition cannot opt out.

format: 1
name: acme-baseline
version: 7                          # an integer; raise it for every release
issued_at: 2026-10-29T00:00:00Z
expires_at: 2027-01-31T00:00:00Z    # optional
rules:
  deny_tools: ["payments.*", "admin.*"]        # fnmatch globs; refused at plan_tool and before_tool
  require_approval_tools: ["crm.export"]       # a person approves first, whatever the side effect
  deny_patterns:
    - name: project-codename
      pattern: "(?i)project\\s+nightingale"
      boundaries: [input, after_model, final_response]
  redact_patterns:
    - name: employee-id
      pattern: "EMP-\\d{6}"
      replacement: "[EMPLOYEE_ID]"
      boundaries: [after_tool, after_retrieval, final_response]

$ algen-agent-runtime policy keygen --private-key signing.pem --public-key signing.pub
$ algen-agent-runtime policy sign acme-baseline.yaml --key env://POLICY_SIGNING_KEY
$ algen-agent-runtime policy verify acme-baseline.yaml --trusted-key file://signing.pub --min-version 7

policies:
  require_signed: true
  trusted_keys:                      # Ed25519 public keys, env:// or file:// only
    - env://POLICY_PUBLIC_KEY
  bundles:
    - path: /etc/algen/policies/acme-baseline.yaml
      # signature: <path>.sig (the default)
      min_version: 7                 # refuse an older signed bundle put back in place
      # trusted_keys: [...]          # this bundle only

sign writes <bundle>.sig, a detached Ed25519 signature over the file's exact bytes; verify checks a bundle exactly as start-up does. Start-up refuses, and the container does not build, when require_signed is true and a bundle has no signature; when a signature does not verify against any trusted key (whatever require_signed says); when a bundle has expired, is issued more than five minutes in the future, or has a version below min_version; or when the file is invalid or two bundles share a name. With require_signed: false (the default) an unsigned bundle loads with a warning, for development. Each loaded bundle logs policy_bundle_loaded with its name, version, SHA-256 and key id. To rotate a key, add the new public key, sign with it, deploy, then remove the old one. CompositePolicyEngine.register(..., mandatory=True) adds a policy every agent runs from code.

Redaction and refused tool calls#

• Bearer tokens and card numbers. The secrets policy also redacts bearer tokens (Bearer <token> with a digit or separator in the token), and the pii policy redacts card numbers as [REDACTED_CARD]: digit runs with a card network's prefix and length that pass the Luhn check. As with any redaction of tool arguments, such a value in a tool call's arguments refuses the call at before_tool. Pass credentials as env:// references or caller credentials, never as argument values.
• UUIDs no longer refused. The pii policy no longer redacts digit runs inside UUIDs, hashes and other tokens as phone or Aadhaar numbers (an identifier must not touch a letter, digit, _ or -). Before, roughly one in sixty tool calls carrying a run, record or order UUID was refused at before_tool.
• Wider redaction. redact() (audit metadata, logs, conversation records) also redacts key=value credential assignments; approval requests redact bearer tokens and key=value credentials inside argument values; the text of an error a tool raised is redacted for credentials; and opt-in telemetry content is redacted for emails, phone, Aadhaar and card numbers, and no longer carries a reply's credentials before after_model redacts it.

Human approvals#

Approvals are persisted before control returns, so a process restart never loses a pending decision. They appear in two places:

• Tool approvals — a single-agent run reaches a side-effecting tool call, moves to awaiting_approval, and resumes with a decision.
• Approval nodes — a workflow pauses at an approval node, then continues, skips dependents, or proceeds with modified parameters.

Another system can decide them too. A deployed service starts its workflows with POST /v1/workflows/{name}/runs, reads a run with GET /v1/workflows/runs/{id}, and answers its approval step with POST /v1/workflows/runs/{id}/approval (approved, rejected or modified). With workflow_notifications set, the service posts a signed event to that system's webhook when a run waits, carrying the step's prompt and what to review, never the run's values.

From 0.1.0a16 a conversation turn shows them in the chat: the assistant message waits in awaiting_approval or awaiting_input with a pending action, and the user answers on the turn. See Conversation turns.

state = await executor.run(manifest, values, tenant_id="acme", user_id="jane")
if state.status is WorkflowStatus.AWAITING_APPROVAL:1
    print(state.pause["prompt"])
    state = await executor.decide_approval(
        manifest,
        state.id,
        tenant_id="acme",
        user_id="reviewer-7",2
        decision="modified",3
        modified_parameters={"change": "Enable credit for 30 days"},
        comment="Limited to 30 days per policy.",
    )

curl -s -X POST "http://127.0.0.1:8000/v1/runs/$RUN_ID/approval" \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: acme' -H 'X-User-ID: reviewer-7' -H 'X-Scopes: runs:write' \
  -d '{"decision": "approved", "modified_parameters": null}'
# 202 Accepted → {"run_id": "…", "status": "…"}

Resolving a paused workflow in Python, or a paused run over HTTP (sample)

• 1Pause — the persisted state carries the prompt and reviewable fields.
• 2Attribution — the deciding user is recorded with the decision.
• 3Decision — approved, modified (schema-validated edits), or rejected.

Side-effect operations#

Every side-effecting tool call is reserved in the tool-execution ledger under its idempotency key (<run_id>:<tool_call_id>) before it runs. A call that fails without a clear outcome (a timeout, or a connection dropped after the request left) is recorded indeterminate; a call the process stopped in the middle of stays started. Neither is ever retried by itself. From 0.1.0a17 an operator can find these calls, record what happened, ask the tool, or undo the effect, and an agent can wait for that decision.

From 0.1.0a19 a tool that refuses before sending anything raises ToolNotAttemptedError (since 0.1.0a18) or PolicyDeniedError, and the call is recorded failed, not indeterminate: nothing needs reconciling, and it can be retried. algen-agent-tools 0.2.0a7 marks a provider's definite rejection (a 4xx other than 408, a refused SMTP recipient) the same way; timeouts and 5xx stay indeterminate.

What happens to the run#

By default (tool_policy.on_indeterminate: on_error) an indeterminate call is handled like any failed call: the run fails, or with on_error: return_to_model the model hears that it failed. Settling the call later is record-keeping only; an ended run is never reopened.

agents:
  - name: crm-assistant
    tool_policy:
      on_indeterminate: pause   # default: on_error

With pause the run pauses in the new awaiting_reconciliation status (a paused status, RunStatus.AWAITING_RECONCILIATION) with a tool.reconciliation_required event and a pause_payload of kind: tool_reconciliation naming the tool, call and idempotency key, never the arguments. Settling the call continues the run: completed gives the model the recorded result (screened like any tool result), or a note that the call took effect when no result was recorded; failed gives it a ToolCallNotApplied tool error; a successful compensation gives it ToolCallCompensated.

A paused run keeps its remaining deadline and is not expired by the maintenance sweep; cancel it to give up. In a parallel batch the other calls are recorded first and the run pauses on the first unknown one. Read-only tools never pause a run, and a resumed run has no caller credentials, as after recovery. Workflow tool steps do not pause for reconciliation.

Operator routes#

Every route needs the new tools:reconcile scope and acts only within the caller's tenant; another tenant's key is 404. The caller's user id is recorded as the actor, so grant the scope only to operators. The decision routes answer {"outcome", "run_resumed", "execution"}, and "resume": false settles a call without continuing its waiting run. Responses never carry the result value, only has_result and result_reference, the error type and resolutions. From Python, runtime.reconciliation (ToolReconciliation) has list, get, resolve, auto_reconcile, compensate and resume with the same rules, and returns full records, results included.

Resolve, reconcile and compensate#

Rules#

• Compare-and-set. Each decision changes the ledger only if the status is still the one read, so of two concurrent decisions exactly one wins and the other gets 409. expected_status makes a request fail with 409 if the call changed since you looked.
• Stale started calls. A started call may still be running. It can be resolved or reconciled only after ToolReconciliation.stale_started_after (default 10 minutes) without change; before that the answer is 409. Filter the list with min_age_seconds.
• Late outcomes. The ledger's complete and fail change only a started record, so a call that finishes after an operator settled it cannot overwrite the decision; it is logged as tool_execution_late_outcome_ignored.
• Record. Each decision appends {action, previous_status, status, actor_id, reason, result_reference, at} to the record's resolutions.
• Re-execution. A call settled failed counts as not having happened: if a still-running run replays it, it runs again, as any failed call does.
• Retention also keeps runs with compensating or compensation_failed tool executions.

The Tool.reconcile hook#

A tool can tell the operator, and the Runtime, whether a call took effect by looking up its idempotency key in the external system:

from algen_agent_runtime.tools.contracts import ReconcileOutcome, ToolExecutionRecord


async def find_update(record: ToolExecutionRecord, context: ToolContext) -> ReconcileOutcome:
    change = await (await crm.client()).find_change(key=record.idempotency_key)
    if change is None:
        return ReconcileOutcome(status="unknown")   # or "failed" once the CRM says it never will
    if change.rejected:
        return ReconcileOutcome(status="failed", detail="rejected by the CRM")
    return ReconcileOutcome(status="completed", value=change.receipt(), result_reference=change.id)


async def undo_update(result: ToolResult, context: ToolContext) -> None:
    # result.value is None for an indeterminate call
    await (await crm.client()).revert_change(key=context.idempotency_key)


@crm.tool(write(approval=True), reconcile=find_update, compensation=undo_update)
async def update_owner(account_id: str, owner: str, context: ToolContext) -> Receipt:
    ...

• reconcile answers completed (with value, which must fit the output schema), failed (it did not and will not happen) or unknown. It must only read, since it may run more than once, and it runs within the tool's timeout. Keep detail short and free of arguments and secrets: it is stored and audited.
• Replay. When a recovered run replays a call that is still started or indeterminate, the executor asks the hook first (unless reconcile_on_replay=False): completed records the result and the run continues without running the tool again; failed fails the call without running it; unknown, an error or a timeout leaves the record, and the run fails or pauses as configured. The decision is recorded with actor runtime.
• @tool and build_tool take reconcile= and compensation=; Tool(definition, handler, compensation, reconcile=..., reconcile_on_replay=True) takes the same hooks. Both hooks get the call's ToolContext without caller credentials, and describe shows reconcile: true and compensation: true. Built-in HTTP API, email and MCP tools have no reconcile hook yet.

Compensation#

Compensation runs only when an operator asks for it. The Runtime never compensates by itself, not on run failure, cancellation or recovery: it cannot tell whether a failure makes earlier effects wrong, a failure seen during recovery may be transient, and undoing an indeterminate call can itself cause a side effect when the original never happened. The ledger moves to compensating (compare-and-set) before the handler runs, so one request runs it at most once and a concurrent request gets 409. Success records compensated; an exception records compensation_failed with the error type, and only that status may be compensated again. If the process stops while the handler runs, the call stays compensating and is never compensated again by itself: settle it with resolve. For an indeterminate call the handler gets ToolResult(value=None, metadata={"execution_status": "indeterminate"}), so it must cope with an effect that may never have happened; make it idempotent with the idempotency key.

Runbook#

1. Find the callsGET /v1/tool-executions, with min_age_seconds above the tool's timeout so calls still running are left out.
2. Ask the tool, if it can tellPOST …/reconcile. unknown means look yourself.
3. Or state the outcomePOST …/resolve with completed or failed, a reason, and expected_status set to what you read.
4. Undo it, if it should not standPOST …/compensate with a reason.
5. Continue a stuck runIf the Runtime stopped between settling a call and continuing its run, POST …/resume.

Events and audit records#

Events carry no arguments, results or reasons; reasons appear only in audit records and the ledger. Audit records name the operator as actor_id (runtime for replay-time reconciliation). The ledger is written before the run checkpoint, so a crash between the two can repeat tool.completed and tool.call: treat them as at-least-once and deduplicate by step_id.

MCP servers#

In 0.1.0a2 the MCP client is experimental: remote tools are normalized into Runtime definitions and wired from Python over stdio and legacy sse, with namespaced registration and env:// secret references. Declarative configuration arrives in 0.1.0a3.

mcp_servers:
  - name: local-files
    transport: stdio
    command: npx1
    args: [-y, "@modelcontextprotocol/server-filesystem", /workspace]
    allowed_tools: [read_file, list_directory]2
    required: true

  - name: inventory
    transport: streamable_http
    url: https://mcp.example.com/mcp
    auth_token_ref: env://MCP_INVENTORY_TOKEN3
    allowed_tools: [lookup_item, update_stock]
    tool_policies:
      update_stock:4
        side_effect: write
        idempotency: non_idempotent

storage:
  postgres_dsn: env://RUNTIME_POSTGRES_DSN
  mcp_oauth_token_store: postgres            # memory (default) or postgres
  mcp_oauth_encryption_key: env://MCP_TOKEN_KEY

mcp_servers:
  - name: linear
    transport: streamable_http
    url: https://mcp.linear.app/mcp
    auth:
      type: oauth
      client_id_ref: env://LINEAR_CLIENT_ID
      client_secret_ref: env://LINEAR_CLIENT_SECRET   # unset: a public client, PKCE alone
      scopes: [read, write]
      token_scope: user                       # one connection per user; tenant is the default
      redirect_uri: https://agents.example.com/v1/mcp/oauth/callback
      success_redirect_url: https://studio.example.com/settings/connections

{"error": {"type": "MCPNotConnected", "server": "linear",
           "message": "MCP server 'linear' is not connected for this user; ask the user to connect it, then try again"}}

mcp.auth_required → {"code": "mcp_not_connected", "server": "linear", "token_scope": "user",
                      "start_path": "/v1/mcp/servers/linear/oauth/start"}

Egress, sandbox & signing#

From 0.1.0a18 every outbound client the Runtime builds can go through one egress proxy with per-host TLS identities and pins, child processes can be confined, and plugin packages can be verified before any of their code is imported. The defaults change nothing.

Egress proxy#

network:
  egress_proxy:
    url: http://egress-proxy.internal:3128   # or env://EGRESS_PROXY_URL; no credentials here
    username: env://EGRESS_PROXY_USER        # optional, sent as Proxy-Authorization (Basic)
    password: env://EGRESS_PROXY_PASSWORD
    no_proxy: [localhost, 127.0.0.0/8, .svc.cluster.local]   # reached directly
    resolve_targets: true

• Covers core.http, http_tools, remote_tool, MCP HTTP transports and OAuth, OIDC discovery and JWKS, workflow notifications, HTTPModelService and the HTTP model providers. The S3 client, OTLP and Traccia exporters and vector-store SDKs keep their own proxy settings (normally HTTPS_PROXY).
• TLS end to end. https:// targets go through a CONNECT tunnel; http:// targets are forwarded.
• Checked first. Each target passes the allowlist and private-network checks before the proxy is contacted, and the proxied pool connects only to the proxy. Proxy credentials are env:// references and never appear in URLs, logs or errors.
• Limit. The proxy makes the final connection and resolves the name again, so DNS pinning protects only up to it: give the proxy its own egress policy. resolve_targets: false checks only the allowlist and IP literals, for a Runtime that cannot resolve external names.

mTLS, private CAs and pinning#

network:
  remotes:
    api.partner.example:                              # or "*.domain" for its subdomains
      ca_bundle: /etc/algen/partner-ca.pem            # replaces the default trust store
      client_certificate: env://PARTNER_CLIENT_CERT   # PEM text, or a file path
      client_key: env://PARTNER_CLIENT_KEY
      client_key_password: env://PARTNER_KEY_PASSWORD # only for an encrypted key
      pinned_sha256: ["5F:3A:...:9C"]                 # leaf certificate SHA-256

The settings apply to every client above, direct or through the proxy. Host name verification stays on; a pin mismatch closes the connection with PolicyDeniedError. Keys and certificates are file paths or env:// references (literal PEM is refused) and are never logged. Host code can build the same clients with create_safe_http_client(outbound=...) or create_outbound_http_client; a built container exposes container.outbound.

Subprocess sandboxing#

security.sandbox controls MCP stdio servers and core.subprocess; a stdio server's own sandbox replaces it for that server.

security:
  sandbox:
    required: true
    env_allowlist: [PATH, LANG]
    limits: {cpu_seconds: 600, open_files: 1024, file_size_bytes: 104857600}
    wrapper: [/usr/bin/bwrap,
              --ro-bind, /usr, /usr,
              --symlink, usr/lib, /lib,
              --symlink, usr/lib64, /lib64,
              --symlink, usr/bin, /bin,
              --ro-bind, /opt/mcp-servers, /opt/mcp-servers,
              --proc, /proc, --dev, /dev, --tmpfs, /tmp,
              --unshare-all, --die-with-parent, --new-session, --]

Limits and a scrubbed environment are not isolation: without a wrapper a child reads every file and reaches every host the Runtime's user can. See Operations · sandboxing for complete wrapper examples.

Plugin signing#

$ algen-agent-runtime plugin keygen signing-key.pem   # prints the public key
$ algen-agent-runtime plugin sign src/acme_plugins --publisher acme --key env://ACME_PLUGIN_SIGNING_KEY --name crm --version 1.2.0
$ algen-agent-runtime plugin verify acme_plugins.crm:CrmPlugin --config agent.yaml

security:
  trusted_plugin_prefixes: [acme_plugins]
plugins:
  trusted_publishers:
    acme: ["MCowBQYDK2VwAyEA..."]   # base64 raw Ed25519 public keys; several allow rotation
  require_signed: true

plugin sign writes algen-plugin-signature.json into the package: the publisher, the bound name and version, the package name and the SHA-256 of every file, so any changed, added or removed file fails verification. The package is located and verified before it is imported, for domain_plugins and workflow hook packages. With require_signed: true an unsigned package, or one from a publisher not in trusted_publishers, is refused even under a trusted prefix; without it, signatures from trusted publishers are still verified and unsigned plugins load as before. The signature does not cover dependencies or __pycache__ and cannot stop a file being replaced after verification: install plugin packages read-only. PluginManifest.signature is unused. See Operations · plugin signing.

Execution model#

The native runtime owns legal state transitions. Strategies can be replaced, but they cannot bypass the execution contract: input policy runs before planning, model routing follows capability discovery, side effects pass through the governed tool executor, and output verification is bounded. Explore every boundary in the architecture map.

State & persistence#

Ports keep execution semantics independent from infrastructure. In-memory adapters are the default for local use and deterministic tests; PostgreSQL and Redis cover durable records, checkpoints, leases, and expiring session state.

storage:
  run_store: postgres
  memory_store: redis1
  event_store: postgres
  audit_store: postgres
  approval_store: postgres
  artifact_store: postgres
  tool_execution_store: postgres
  conversation_store: postgres
  postgres_dsn: env://ALGEN_AGENT_RUNTIME_POSTGRES_DSN2
  redis_url: env://ALGEN_AGENT_RUNTIME_REDIS_URL
  initialize_schema: true
  postgres_min_pool_size: 2
  postgres_max_pool_size: 10

Durable stores (from examples/case_study_teaching_assistant)

• 1Per-store backends — mix PostgreSQL, Redis, and memory per concern.
• 2Connection secrets — DSNs are env:// references, never literals.

Artifacts move through pending_scan → available or quarantined with SHA-256 identity and retention; see Artifact lifecycle.

Limits, quotas & retention#

From 0.1.0a18 one run cannot make the model produce, or record, without bound; each tenant's stored artifacts and memory can be capped; and the remaining growing tables have retention windows.

Run limits#

A run that ends at a limit fails with run.failed reason: limit_exceeded and limit (model_calls, response_chars, events, or the existing step, token and cost limits, which now report the same way), a run.limit_exceeded audit record and the agent.run.limit_exceeded span attribute. Alert on it: a run that keeps reaching a limit is looping or being fed hostile input.

Storage quotas#

storage:
  quotas:
    default:                         # every tenant; unlimited when unset
      artifact_count: 10000
      artifact_bytes: 10737418240    # 10 GiB
      memory_items: 100000           # session memory messages
      memory_bytes: 1073741824
      learned_memory_items: 5000
      learned_memory_bytes: 52428800
    tenants:
      enterprise-tenant: {artifact_bytes: 107374182400}
      internal-tools: {memory_items: null}   # null lifts a limit for this tenant

• Enforced on write by the in-memory, PostgreSQL, S3 and (when a quota is set) Redis stores. A write past a limit writes nothing and raises QuotaExceededError; the API answers 413 with code: QUOTA_EXCEEDED, resource, dimension, limit and used. Retrying cannot succeed until the tenant deletes data or the quota is raised. Deletes are always allowed.
• Inside a run a full artifact quota fails the tool-result offload as a tool error, a full learned-memory quota fails the memory tool call, and a full session-memory quota keeps the answer but skips the turn's memory (memory.written with operation: skipped, a storage.quota_exceeded audit record).
• Usage. GET /v1/storage/usage (new scope usage:read) and container.storage_usage report the tenant's usage and limits. On PostgreSQL, migration 016's triggers keep algen_agent_runtime_tenant_usage current in the same transaction as every write, and a quota-checked write locks the tenant's row, so concurrent writes cannot overshoot. Redis quotas need a Redis that is not clustered.

Retention#

All are off by default and apply to PostgreSQL and in-memory stores, in batches like the existing purges; migration 016 adds the supporting indexes. Choose windows that cover incident investigation and compliance, and back up first. See Operations · run limits, storage quotas and retention.

Events & observability#

Every run emits an ordered stream of typed RunEvents carrying run, session, correlation, workflow, and OpenTelemetry trace identifiers. Stream them in-process, over HTTP as server-sent events, or persist them to a store.

One run's event stream (sample)

• 1Policy decisions — each boundary emits its own evidence.
• 2Verification — bounded repair is visible, not hidden.
• 3Terminal event — run.completed, run.failed, or run.cancelled ends the stream.

client = AlgenAgentRuntimeClient(container.runtime)
request = RunRequest(agent="support-assistant", input="Hello", tenant_id="acme", user_id="jane")

async for event in client.stream(request):
    print(event.sequence, event.type, event.data)

telemetry:
  enabled: true
  service_name: support-desk
  include_content: false
  max_content_chars: 16384
  traccia:
    enabled: true
    api_key: env://TRACCIA_API_KEY
    environment: production
    governance_enabled: true
    governance_fail_open: false

Streaming events in-process, and telemetry with the optional Traccia integration (sample)

Event types#

telemetry:
  traccia:
    enabled: true
    export_foreign_traces: false   # default: only traces the Runtime started
# true (or ALGEN_AGENT_RUNTIME__TELEMETRY__TRACCIA__EXPORT_FOREIGN_TRACES=true)
# sends everything as before, with runs as children of the request that started them

telemetry:
  otlp_metrics_endpoint: https://collector:4318/v1/metrics
  otlp_metrics_export_interval_seconds: 60   # default; 1 to 3600

Serve over HTTP#

The same container runs as a FastAPI service. Runs are accepted asynchronously and observed through status reads or an event stream.

$ algen-agent-runtime serve --config agent.yaml
$ curl -s http://127.0.0.1:8000/v1/runs -H 'Content-Type: application/json' -H 'X-Tenant-ID: acme' -H 'X-User-ID: jane' -H 'X-Scopes: runs:write runs:read' -d '{"agent": "support-assistant", "input": "Hello"}'
{"run_id": "…", "session_id": "…", "status": "…"}
$ curl -N http://127.0.0.1:8000/v1/runs/$RUN_ID/events -H 'X-Tenant-ID: acme' -H 'X-User-ID: jane' -H 'X-Scopes: runs:read'

Tenant-aware rate limits return 429 with Retry-After; oversized request bodies return 413, enforced on actual wire bytes.

From 0.1.0a18 a store outage answers 503 with Retry-After instead of 500 (see Store outages), and a write past a tenant's storage quota answers 413 with code: QUOTA_EXCEEDED (see Storage quotas).

from algen_agent_runtime.banner import print_startup_banner

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

Authentication#

api.auth_mode decides how the service knows who is calling. From 0.1.0a17 it can verify tokens from an OpenID Connect identity provider, revoke tokens before they expire, accept a client-certificate identity from a trusted proxy, and audit every failed sign-in.

OIDC issuers and JWKS#

api:
  host: 0.0.0.0
  auth_mode: oidc
  oidc:
    jwks_cache_ttl_seconds: 300            # how long fetched keys are used (30 to 86400)
    jwks_min_refresh_interval_seconds: 30  # at most one JWKS fetch per issuer per interval
    http_timeout_seconds: 5
    allow_private_networks: false          # true only for an in-cluster identity provider
    issuers:
      - issuer: https://login.example.com/realms/acme   # exact 'iss'
        # jwks_url: https://login.example.com/realms/acme/protocol/openid-connect/certs
        audiences: [algen-agent-runtime]
        algorithms: [RS256]                # RS*, PS*, ES*, EdDSA only
        leeway_seconds: 30                 # clock skew for exp/nbf/iat, at most 300
        max_token_lifetime_seconds: 900    # optional: refuse long-lived tokens
        required_claims: [azp]             # beyond exp, iss, aud and the subject
        claims:
          subject_claim: sub
          tenant_claim: tenant_id          # or fixed_tenant: acme
          allowed_tenants: []              # optional allowlist
          scope_claims: [scope, scp]
          role_claims: [realm_access.roles, groups]
          role_scopes:
            runtime-operators: [runs:read, runs:write, conversations:read]
            runtime-admins: [auth:revoke, tools:reconcile]

• Discovery. Without jwks_url the Runtime reads {issuer}/.well-known/openid-configuration, requires its issuer to equal the configured one, and fetches its jwks_uri.
• Egress. Discovery and JWKS fetches use the SSRF-safe client and reach only the issuer host, the jwks_url host and the issuer's additional_allowed_hosts. Private, loopback, link-local and metadata addresses are refused unless allow_private_networks: true; redirects are not followed; responses are capped at max_jwks_bytes (256 KiB); https is required unless allow_insecure_http: true (local test providers only).
• Caching and rotation. Keys are cached for jwks_cache_ttl_seconds. A token with an unknown kid triggers a refresh, at most one per jwks_min_refresh_interval_seconds per issuer, so random key ids cannot turn requests into identity-provider traffic. If a refresh fails the last good keys stay in use; if keys were never fetched the API answers 503. Publish a new key before signing with it, and keep the old one published until its tokens have expired.
• Algorithms. Only the issuer's algorithms are accepted; none and HS* are refused by configuration validation. The token's algorithm must also match the key type (RSA: RS*/PS*, EC: ES*, OKP: EdDSA) and the key's alg when the JWKS states one. Symmetric (oct) keys are ignored, and tokens must carry a kid.
• Claims. exp, iss, aud and the subject are required; nbf and iat are checked when present, all with leeway_seconds of skew. max_token_lifetime_seconds (60 to 86400) requires iat and refuses tokens that live longer.

Claims to tenant and scopes#

The subject claim becomes the user id. The tenant comes from fixed_tenant (one-tenant issuers; it takes precedence) or tenant_claim (default tenant_id), and allowed_tenants can limit it. A missing, empty or non-string tenant is refused: the tenant fails closed and is never defaulted. Scopes are the union of the scope_claims values (default scope and scp; a space-separated string or a list) and the scopes role_scopes grants for each value in role_claims (default roles and groups). A * in a token's own scope claim is dropped; grant the wildcard through role_scopes if you really need it. Claim names are looked up literally first, for namespaced claims such as https://example.com/tenant, then as dotted paths such as realm_access.roles.

Token revocation#

Short-lived access tokens (5 to 15 minutes, enforced with max_token_lifetime_seconds) are the main revocation control. For a token that must stop working sooner, turn on the check, for jwt and oidc:

api:
  token_revocation:
    enabled: true
    store: postgres     # 'memory' (default) is per process and lost on restart; postgres needs storage.postgres_dsn
    require_jti: false  # true refuses tokens without a jti

Each verified token is then checked, in one store lookup, against a tenant-scoped jti denylist and a per-subject “revoked before” cutoff (a token whose iat is at or before the cutoff, or that has no iat, is refused). A store outage fails closed with 503. Revoke with the auth:revoke scope, within the caller's own tenant:

Both return 404 while revocation is off. From Python use container.token_revocations (revoke_token, revoke_subject, state, purge_expired). The PostgreSQL store uses migration 013_token_revocation.sql, run on startup. The check costs one indexed lookup per request and makes the store a dependency of authentication.

Service identity from a trusted proxy#

When a TLS-terminating proxy verifies client certificates, it can pass the client's identity to the Runtime in a header. This is off by default and needs auth_mode: jwt or oidc.

api:
  trusted_proxy_identity:
    enabled: true
    header: x-client-cert-identity
    trusted_proxies: [10.0.0.0/24]       # CIDRs of the proxies, never 0.0.0.0/0
    identities:
      spiffe://acme/ns/jobs/sa/scheduler:
        tenant_id: acme
        user_id: svc-scheduler           # default: the identity string
        scopes: [runs:write, runs:read]

• CIDR rule. The header is honoured only when the request's direct TCP peer is inside trusted_proxies. A network that covers every address (prefix length 0, such as 0.0.0.0/0) is refused, and an enabled hook needs at least one proxy and one identity.
• Exact identities. Only a value listed in identities is accepted; any other value is refused. The same header from any other address is refused and audited as untrusted_proxy, even when the request also carries a valid bearer token. Requests without the header fall through to bearer authentication.
• Header. It may not be a header that already carries identity (authorization, cookie, x-tenant-id, x-forwarded-for and the like). The proxy must overwrite it on every request and never pass a client's value through.
• Peer address. algen-agent-runtime serve disables uvicorn's X-Forwarded-For rewriting while the hook is enabled; under another server, disable proxy-header rewriting there too. mTLS terminated by the Runtime itself is not mapped to principals.

Authentication audit#

api:
  authentication_audit:
    record_failures: true                 # false: no failure records; the metric and log remain
    record_success: false                 # true: one record per successful authentication
    max_failure_records_per_minute: 600   # per process; the excess is counted in auth.audit.suppressed

No record holds the token, its signature or any claim beyond the subject, and a subject is recorded only after the signature is verified (or for a trusted proxy's identity); an unverified token's issuer and kid are truncated to 256 characters. Clients get a generic answer: a rejected token is 401 invalid bearer token with WWW-Authenticate: Bearer error="invalid_token"; unavailable keys or revocation store are 503. The specific reason is only in the audit: missing_credentials, malformed_token, algorithm_not_allowed, unknown_issuer, missing_key_id, unknown_key, keys_unavailable, invalid_signature, expired, not_yet_valid, invalid_issued_at, invalid_audience, invalid_issuer, missing_claim, token_lifetime_exceeded, missing_subject, missing_tenant, tenant_not_allowed, missing_jti, revoked, revocation_unavailable, untrusted_proxy, invalid_service_identity, unknown_service_identity, invalid_token.

Readiness & lifecycle#

/health/live answers {"status": "ok"} while the process runs. From 0.1.0a16 /health/ready reports every dependency the service has, says why one is degraded, and fails only when a required one is down.

{
  "status": "degraded",
  "ready": true,
  "lifecycle": "ready",
  "providers": {"openai": true},
  "stores": {"PostgresDatabase": true},
  "dependencies": {
    "store.run": {"kind": "store", "required": true, "backend": "postgres", "status": "up"},
    "provider.openai": {"kind": "provider", "required": false, "status": "up"},
    "mcp.crm": {"kind": "mcp", "required": false, "status": "down", "reason": "ConnectError"},
    "telemetry.otlp": {"kind": "telemetry", "required": false, "status": "unknown", "reason": "not probeable"}
  },
  "degraded_dependencies": {"mcp.crm": "ConnectError"},
  "failing": []
}

providers and stores keep their earlier meaning. A dependency's status is up, down or unknown (it cannot be probed; it is reported and never fails readiness). Reasons are content-minimal: an exception type, probe failed, probe timed out, not registered, or a message of at most 160 characters with URLs, DSNs and credential-like values removed. Probes run concurrently, each bounded by probe_timeout_seconds.

runtime:
  readiness:
    model_providers: any          # any | all | none
    require_durable_stores: true  # every store.* and resource.* dependency
    required: []                  # for example [mcp.crm, retriever.docs]
    optional: []                  # for example [cache.redis]
    probe_timeout_seconds: 2      # 0 < value ≤ 30

Names are <kind>.<name> with kind one of store, cache, provider, retriever, mcp, telemetry or resource; algen-agent-runtime check rejects other forms.

Start and drain#

Container.lifecycle.phase is reported as lifecycle. Startup (Container.astart, run by the FastAPI lifespan) starts resources, discovers MCP tools, recovers incomplete agent runs and conversations, recovers the workflow service's interrupted runs, and starts the maintenance loop when maintenance.enabled. Shutdown (Container.aclose) moves to draining, so readiness fails at once, then stops the maintenance loop; drains the workflow service for shutdown_grace_seconds; drains conversations and agent runs with the same grace period; closes retrievers and resources; and moves to stopped. Interrupted agent runs keep a recoverable status and interrupted workflow runs keep their last checkpoint. See Service workflow lifecycle.

Production checklist#

Pre-alpha does not mean prototype, but deployment claims must stay narrow. Before serving external traffic, validate the complete operator boundary.

1. Threat-model the deploymentDefine trust boundaries for API clients, model providers, tool processes, MCP servers, stores, artifacts, and telemetry exporters.
2. Externalize durable stateConfigure production stores, migrations, backups, retention, reconciliation, and tenant-isolation verification.
3. Constrain every egress pathUse secret references, outbound allowlists, TLS verification, safe transports, request limits, and provider-specific timeouts.
4. Authenticate the serviceReplace development headers with JWT, configure CORS deliberately, and keep the Agent Manifest UI internal.
5. Prove recoveryExercise worker interruption, approval resume, duplicate delivery, tool indeterminacy, workflow fingerprint mismatch, and store degradation.

CLI#

The package installs one entry point, algen-agent-runtime. With no subcommand it runs serve.

API map#

The default composition root is intentionally singular. Public contracts stay provider-neutral; adapters live at the edges. Public APIs are experimental during 0.x — see API stability.

Troubleshooting#

Glossary#

Agent definition

A versioned agent: default model, instructions, tools, policies, and budget.

Approval node

A workflow node that pauses for an attributed human decision.

Audit event

An immutable evidence record of actor, action, outcome, and resource.

Capability narrowing

Effective capabilities are the intersection of adapter-reported and configured capabilities; widening fails safe.

Checkpoint

Persisted run or workflow state that makes execution recoverable.

Composition root

build_container: the one place where settings become wired runtime components.

env:// reference

A pointer to a secret in the environment, such as env://OPENAI_API_KEY, used instead of a literal.

Hook provider

Trusted Python that supplies named builders, handlers, and schemas to a workflow.

Idempotency

How safely a tool call can be repeated: idempotent, keyed, or non-idempotent.

Provider instance

A named deployment of a model adapter type, with its own health, limits, and cost accounting.

Run event

One typed, sequenced entry in a run's lifecycle stream.

Side effect

A tool's classification — none, read, write, external, or destructive.

Tenant

The isolation boundary carried on every request, store record, and event.

Workflow manifest

A versioned, fingerprinted DAG of nodes declared in YAML.

Deep dives#

Continue into focused design and operational guides from the repository documentation.