Runtime Control for AI, Agent & MCP Execution
Website ยท PyPI ยท Getting Started ยท Architecture ยท Runtime Control ยท Evidence Model ยท Why WAIL ยท Telemetry
**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 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