Blame for README.md

---
title: WAIL — Execution Control & Governance
emoji: 🛡️
colorFrom: blue
colorTo: gray
sdk: static
pinned: true
short_description: AI, Agent & MCP Execution Control & Governance Layer
---

<p align="center">
  <img src="https://raw.githubusercontent.com/wailinfra/wail-runtime/main/docs/images/wail-logo.png" alt="WAIL" width="650">
</p>

<p align="center">
  <strong>Runtime Control for AI, Agent & MCP Execution</strong>
</p>

<p align="center">
  <a href="https://wailinfra.com">Website</a> ·
  <a href="https://pypi.org/project/wail-runtime/">PyPI</a> ·
  <a href="docs/getting-started.md">Getting Started</a> ·
  <a href="docs/architecture.md">Architecture</a> ·
  <a href="docs/runtime-control.md">Runtime Control</a> ·
  <a href="docs/evidence-model.md">Evidence Model</a> ·
  <a href="docs/why-wail.md">Why WAIL</a> ·
  <a href="docs/telemetry.md">Telemetry</a>
</p>

**WAIL is an on-prem execution control and governance layer for AI models, agents, and MCP tools.**

An AI request can return HTTP 200 yet still behave poorly: latency rises beyond its baseline, streaming stalls, or a tool call degrades. Detecting a problem is not the same as deciding what to do next — or proving what actually happened.

WAIL wraps your existing clients and MCP sessions to observe execution, assess runtime degradation, and make supported **observe, retry, or reroute** decisions. Standard provider rerouting can apply to a **subsequent execution**. Separately, **Continuous Governance Assurance & Enforcement (CGAE)** governs authority changes **during active execution**, including intervention in affected in-progress model, agent, and MCP operations.

WAIL links observations, authorization and policy changes, decisions, enforcement actions, and verified outcomes through cryptographically signed evidence and an authoritative ledger.

**No gateway. No replacement agent framework.** Your application retains orchestration and business logic. Governance and audit workflows are supported **where enabled**. CGAE is a core WAIL capability that provides continuous governance control and enforcement throughout the execution lifecycle.

**Free Developer tier. No signup or credit card required. Python 3.12.**

```bash
pip install wail-runtime
```

---

## Quick Start

Wrap your existing AI client with WAIL.

```python
from openai import OpenAI
import wail

client = wail.wrap(OpenAI())
```

Use it exactly as you normally would.

```python
response = client.responses.create(
    model="gpt-4o-mini",
    input="Explain what WAIL does."
)

print(response.output_text)
```

After each request, WAIL prints a runtime summary.

```text
WAIL AI Runtime Control Layer
────────────────────────────────────────

Plan               Developer
Provider           openai
Model              gpt-4o-mini

Duration           2,220 ms
TTFT               1,981 ms
Throughput         3.97 tok/s
Mean Token Gap     4 ms

Active Signals     0
Runtime Severity   NONE
Risk Score         0.00
Dominant Surface   NONE

Decision           OBSERVE
Trace              SAVED · 01M1BQ593...
```

Every measured execution can also generate signed runtime evidence that includes:

- runtime observations
- execution assessment
- runtime decisions
- control actions
- execution outcome
- cryptographic integrity metadata

---

## Continuous Governance Assurance & Enforcement (CGAE)

**CGAE is a core WAIL capability, not a separate product, gateway, or execution authority.** It maintains governance control throughout the lifecycle of model, agent, and MCP execution — including changes that occur **after an execution has started**.

CGAE enforcement includes:

- Evaluating authorization, policy, and execution-authority changes during an active run, not only at initial dispatch.
- Intervening in affected in-progress model calls, agent operations, and MCP tool executions when authority changes require it.
- Blocking subsequent dispatches that are no longer authorized, including across provider and Agent/MCP execution chains.
- Distinguishing an actual, verified cancellation of remote work from merely stopping local observation or waiting.
- Linking authorization, changes, decisions, enforcement attempts, actual outcomes, and responsible authority through signed chronological evidence and the authoritative ledger.

**Runtime recovery and governance enforcement are distinct:** subsequent-execution provider rerouting does not limit CGAE intervention in an already-active execution. Evidence distinguishes an attempted intervention, a local stop, and independently verified remote cancellation.

---

## Architecture

![WAIL Architecture](https://raw.githubusercontent.com/wailinfra/wail-runtime/main/docs/images/overview-architecture.png)

WAIL operates around the execution path rather than replacing it.

For direct model execution, WAIL observes and controls provider requests.

For agent and MCP execution, WAIL can represent the active workload as an **Agent Run** containing connected agent, model, and MCP tool execution units.

Delegation, call, and join relationships preserve how execution moved through the run.

---

## What WAIL Does

- **Detect Runtime Issues** — Observe AI execution and identify abnormal latency, streaming behavior, errors, timeouts, tool failures, and other runtime degradation.
- **Assess Execution Health** — Determine how serious a runtime issue is and whether it justifies intervention.
- **Evaluate Alternatives** — Compare observed models, providers, or configured recovery paths when another execution path may be needed.
- **Control Runtime Execution** — Retry or reroute when runtime conditions and policy justify intervention; otherwise preserve the application's current execution path.
- **Track Agent Execution** — Represent agent, model, and MCP tool activity as connected execution units within an Agent Run.
- **Track Execution Relationships** — Preserve delegation, call, and join relationships across multi-agent execution.
- **Apply MCP Runtime Recovery** — Observe MCP tool execution and apply configured retry or reroute behavior when runtime control requires it.
- **Verify Recovery** — Preserve the relationship between the execution that produced a recovery decision and the execution where recovery was applied, including the resulting recovery state.
- **Record What Happened** — Produce signed, verifiable runtime and Agent Run evidence for observations, decisions, actions, execution relationships, and outcomes.
- **Support Governance** — Preserve structured incident and execution records for governance, audit, and compliance workflows where enabled.

### Runtime Control Loop

```text
Runtime measurements
        ↓
Baseline + anomaly detection
        ↓
Risk / severity evaluation
        ↓
Candidate scoring
        ↓
Runtime decision
        ↓
Intervention when required
        ↓
Recovery application / verification
        ↓
Signed execution evidence
```

WAIL does not route requests simply because another model, provider, or execution target scores better.

Candidate evaluation informs runtime control; intervention remains driven by observed runtime conditions and control policy.

---

## Agent & MCP Execution

WAIL extends its execution model across existing agent orchestration and MCP sessions without becoming the orchestrator itself.

A WAIL Agent Run can preserve:

- agent execution units
- model execution units
- MCP tool execution units
- delegation relationships
- model/tool call relationships
- fan-in and join relationships
- underlying execution trace IDs
- run status
- run-level runtime intelligence where applicable
- runtime recovery and recovery-verification evidence where applicable
- cryptographic integrity metadata

A simplified execution graph can look like this:

```text
Coordinator Agent
        │
        ├── delegates ──> Research Agent
        │                       │
        │                       ├── calls ──> Model
        │                       │
        │                       └── calls ──> MCP Tool
        │
        ├── delegates ──> Verification Agent
        │                       │
        │                       ├── calls ──> Model
        │                       │
        │                       └── calls ──> MCP Tool
        │
        └──────────── joins ────────────┐
                                        ▼
                                  Synthesis Agent
```

The application remains responsible for orchestration and business logic.

WAIL records and evaluates the runtime execution around it.

### Agent & MCP Runtime Output

WAIL preserves runtime visibility at both the **individual execution level** and the **Agent Run level**.

An MCP tool execution is observed as its own runtime execution:

```text
WAIL AI Runtime Control Layer · 20:37:41
────────────────────────────────────────

Plan              Pro
Execution Type    MCP Tool
Agent             runtime_worker_agent
Tool              wail_probe

Duration          106 ms
TTFT              --
Throughput        --
Mean Token Gap    --

Active Signals    0
Runtime Severity  NONE
Risk Score        0.00
Dominant Surface  NONE

Decision          OBSERVE
Trace             SAVED · 01M46J933...
```

The complete multi-agent execution is also represented as an Agent Run:

```text
WAIL AI Runtime Control Layer · 20:37:42
────────────────────────────────────────

Plan             Developer
Execution Type   Agent Run
Run              run_222738885...

Agent Units      2
Model Units      1
MCP Tool Units   1
Relations        3

Status           COMPLETED
Signed Evidence  SAVED
```

This gives WAIL two connected levels of evidence:

```text
Individual Execution
    │
    ├── Model Trace
    └── MCP Tool Trace
            │
            ▼
        Agent Run
            │
            ├── Agent Units
            ├── Model Units
            ├── MCP Tool Units
            ├── Relations
            └── Signed Evidence
```

Individual model and MCP tool executions remain independently traceable, while the Agent Run preserves how those executions were connected as a single execution graph.

---

## MCP Integration

WAIL wraps an existing MCP client session rather than replacing the MCP transport or server.

```python
from wail.mcp.adapter import wrap_mcp

mcp_client = wrap_mcp(
    session,
    transport="stdio",
    service="mcp",
    env="production",
)
```

Here, `session` is an already initialized MCP `ClientSession`.

Tool calls continue through the wrapped MCP client:

```python
result = await mcp_client.call_tool(
    "inspect_repository",
    arguments={"path": "."},
)
```

When the call occurs inside an active WAIL execution context, WAIL can preserve the MCP operation as a tool execution unit and associate its trace with the active Agent Run.

### MCP Recovery Routes

A backup MCP tool can be configured as an alternate runtime path:

```python
mcp_client = wrap_mcp(
    session,
    transport="stdio",
    routes={
        "primary_tool": "backup_tool",
    },
    service="mcp",
    env="production",
)
```

When runtime conditions naturally produce a supported recovery decision, WAIL can apply the recovery on the subsequent execution and preserve evidence linking the source execution to the applied recovery.

---

## Agent Run

WAIL creates an execution boundary around existing agent orchestration:

```python
import wail

with wail.execution_run(
    attributes={
        "orchestration": "coordinator_worker",
    }
) as run:
    run_id = run.run_id
```

Agent Runs do not replace the application's orchestration model.

They provide an execution boundary for connecting agent, model, and MCP tool activity into a common runtime graph and evidence record.

Within a run, WAIL can preserve relationships including:

```text
Coordinator
    │
    └── delegates ──> Worker
                          │
                          ├── calls ──> Model
                          │
                          └── calls ──> MCP Tool
```

More complex executions can also preserve fan-out and fan-in relationships:

```text
Coordinator
    │
    ├── delegates ──> Agent A ──┐
    ├── delegates ──> Agent B ──┼── joins ──> Synthesis Agent
    └── delegates ──> Agent C ──┘
```

Model and MCP tool executions associated with these agent units retain their individual runtime traces while also becoming part of the Agent Run graph.

For complete working examples, see:

- [multi_agent_mcp_evidence.py](https://github.com/wailinfra/wail-runtime/blob/main/examples/multi_agent_mcp_evidence.py)
- [multi_agent_runtime_recovery_evidence.py](https://github.com/wailinfra/wail-runtime/blob/main/examples/multi_agent_runtime_recovery_evidence.py)

---

## Runtime Recovery

WAIL distinguishes between a **recovery decision**, its later **application**, and verification of the resulting execution.

For supported runtime recovery paths:

```text
Execution N
    │
    ▼
Runtime degradation / failure
    │
    ▼
WAIL runtime decision
RETRY or REROUTE
    │
    ▼
Execution N+1
    │
    ▼
Recovery application
    │
    ▼
Recovery verification
    │
    ▼
Signed evidence
```

A recovery decision is therefore not treated as proof that recovery actually happened.

WAIL can preserve:

- the source run
- the source execution trace
- the selected recovery action
- the execution where recovery was applied
- the applied execution trace
- whether the recovery action was actually executed
- the resulting recovery state

This allows the evidence chain to distinguish:

```text
Decision produced
        ≠
Recovery applied
        ≠
Recovery verified
```

---

## Signed Agent Evidence

Completed Agent Runs can produce signed Agent Run evidence that preserves the connected execution rather than reducing the run to unrelated request logs.

Depending on execution state and available capabilities, Agent Run evidence can include:

- run identity and status
- agent execution units
- model execution units
- MCP tool execution units
- execution relationships
- underlying model and tool trace IDs
- run-level execution intelligence
- runtime recovery state
- recovery application and verification state
- evidence hash
- public-key fingerprint
- RSA-PSS-SHA256 signature

This evidence complements WAIL's per-execution runtime artifacts.

Individual model and tool executions remain traceable while the Agent Run preserves how those executions were related.

---


---

## Supported Providers

| Provider | Runtime Detection | Runtime Control | Runtime Evidence |
|----------|:-----------------:|:---------------:|:----------------:|
| OpenAI | ✅ | ✅ | ✅ |
| Anthropic | ✅ | ✅ | ✅ |
| Google Gemini | ✅ | ✅ | ✅ |
| OpenRouter | ✅ | ✅ | ✅ |
| Ollama | ✅ | ✅ | ✅ |
| OpenAI-compatible Local LLMs | ✅ | ✅ | ✅ |

The runtime evidence model remains consistent across all supported providers.

Agent and MCP execution support operates around these runtime integrations; MCP itself is an execution interface rather than an AI model provider.

---

## CLI

Inspect and verify runtime artifacts directly from the command line.

```bash
wail traces incidents

wail trace show <TRACE_ID>

wail verify <ARTIFACT_FILE>
```

---

## Documentation

Learn more about WAIL:

- [Getting Started](https://github.com/wailinfra/wail-runtime/blob/main/docs/getting-started.md)
- [Why WAIL](https://github.com/wailinfra/wail-runtime/blob/main/docs/why-wail.md)
- [Architecture](https://github.com/wailinfra/wail-runtime/blob/main/docs/architecture.md)
- [Runtime Control](https://github.com/wailinfra/wail-runtime/blob/main/docs/runtime-control.md)
- [Runtime Evidence Model](https://github.com/wailinfra/wail-runtime/blob/main/docs/evidence-model.md)
- [Provider Integration](https://github.com/wailinfra/wail-runtime/blob/main/docs/provider-integration.md)
- [Runtime Artifact Reference](https://github.com/wailinfra/wail-runtime/blob/main/docs/artifact-reference.md)
- [CLI Reference](https://github.com/wailinfra/wail-runtime/blob/main/docs/CLI.md)
- [Telemetry](https://github.com/wailinfra/wail-runtime/blob/main/docs/telemetry.md)