Wyrd docs v0.4.1 Use with your coding agent Reference GitHub

Connect / ASGI apps

ASGI apps

Add WyrdMiddleware to any ASGI app, such as FastAPI, Starlette, Django, or Litestar. It starts Wyrd when your app starts, wraps each request in its own Run, and sends queued evidence when your app stops.

What you capture

  • One Run per HTTP request or WebSocket connection. Every verdict and row the request produces shares that Run’s run_id.
  • Spans your OpenTelemetry instrumentation records inside the Run, tagged with its wyrd.run_id and wyrd.card_uid.

Before you start

Install

bash
uv add "wyrd-ai[otel]==0.4.1" uvicorn

Add your framework too, such as uv add fastapi. Then pull the Service into the app’s directory, at build or deploy time rather than when the app starts:

bash
uv run wyrd pull --kind Service --name support-reply --version 1.0.0 --output-dir .wyrd-bundle

Usage

Each app loads the pulled Service, adds the middleware, and reads the request’s Run in its handler:

app.py python
"""A FastAPI app that verifies each support answer it receives under its own Run.

It serves the Quickstart's ``support-reply`` Service, pulled once at deploy time:

    wyrd pull --kind Service --name support-reply --version 1.0.0 
      --output-dir .wyrd-bundle
    uv run uvicorn app:app
"""

from __future__ import annotations

import asyncio

from fastapi import FastAPI, Request
from pydantic import BaseModel
from wyrd.integrations.asgi import RUN_SCOPE_KEY, WyrdMiddleware
from wyrd.state import WyrdState

# Load the pulled Service; this reads local files only.
state = WyrdState.from_path(".wyrd-bundle")

app = FastAPI()
# Start the state with the app, drain it at shutdown, and open one Run per request.
app.add_middleware(WyrdMiddleware, state=state)


class Reply(BaseModel):
    answer: str


@app.post("/replies")
async def check_reply(reply: Reply, request: Request) -> dict[str, str]:
    # This request's Run, opened by the middleware.
    run = request.scope[RUN_SCOPE_KEY]
    # Verification waits for the verdict, so it runs off the event loop.
    result = await asyncio.to_thread(run.observe.verify, "no-refund-promise", answer=reply.answer)
    return {"run_id": run.run_id, "verdict": result.verdict}
bash
uv run uvicorn app:app

What the middleware does:

WhenIt
The app startsStarts Wyrd’s writer and telemetry, before your app’s own startup. If either fails, the app does not start.
A request arrivesOpens a Run of the Service, puts it at request.scope["wyrd.run"], and runs your handler inside it.
The app stopsWaits for your app’s own shutdown, then sends every queued row and span.

The middleware verifies nothing by itself. Your handler decides what to verify and records it on the request’s Run.

Verify it worked

In a second terminal, send an answer that breaks the requirement:

bash
curl -s localhost:8000/replies -H 'content-type: application/json' -d '{"answer": "You have a guaranteed refund."}'

The reply names the request’s Run and a failed verdict. A second request returns a different run_id.

If it fails

You seeFix
Startup fails with WYRD_SDK_409_TELEMETRY_PROVIDER_EXISTSYour app installs its own tracer provider: pass telemetry=False and add wyrd.otel.span_exporter(client) to that provider
Startup fails with an ImportError naming otelInstall wyrd-ai[otel], or pass telemetry=False
WYRD_SDK_400_BIFROST_NOT_STARTED when the app recordsThe server runs without lifespan: leave Uvicorn’s --lifespan at auto or set it to on
WYRD_SDK_404_UNKNOWN_ALIAS on every requestalias returned a name the bundle does not have

Advanced

Choose the component per request

By default each Run observes the Service. To observe one of its components instead, pass alias, a function from the request’s ASGI scope to a component alias, or None for the Service:

python
def by_path(scope):
    return "agent" if scope["path"].startswith("/agent/") else None


app.add_middleware(WyrdMiddleware, state=state, alias=by_path)

An alias the bundle lacks fails the request before your handler runs.

WebSockets

A WebSocket connection is one Run for its whole life, so every message on it shares one run_id. To judge each turn of a conversation separately and the conversation as a whole, pass a group_id to verify, as in the grouped recipe.

Your own OpenTelemetry instrumentation

Add WyrdMiddleware after OpenTelemetry’s ASGI or framework instrumentation, so Wyrd’s middleware is outermost and the instrumentation’s spans start inside the Run. The middleware creates no spans of its own. If your app owns its tracer provider, pass telemetry=False: the app installs, exports, and flushes that provider, and calls wyrd.otel.install_run_correlation(provider) once to tag spans with the Run.

Gunicorn

Run Gunicorn with Uvicorn workers:

bash
uv add gunicorn
uv run gunicorn app:app --workers 2 --worker-class uvicorn.workers.UvicornWorker

Each worker starts and drains its own writer. Lifespan must stay enabled; without it nothing starts and nothing drains.

A graceful stop (SIGTERM) drains every worker. A worker killed with SIGKILL, one that exceeds --graceful-timeout, or a failed drain can lose queued rows.

Reference

WyrdMiddleware(app, *, state, telemetry=True, alias=None), from wyrd.integrations.asgi:

ArgumentMeaning
appThe ASGI app to wrap; add_middleware passes it.
stateA loaded WyrdState. The middleware never declares or registers anything.
telemetryWhether startup calls state.start_telemetry(). Default True.
aliasFunction from the ASGI scope to the component alias each Run observes. Default: the Service.

RUN_SCOPE_KEY is "wyrd.run", the scope key that holds the request’s Run. Other ASGI connection types pass through unchanged.

Next

Runs and evidence explains what a Run records and how long it is kept.

Last updated