agent-workbench-fastapi

agent-workbench-fastapi

Thin streaming adapter for mounting a standalone Agent Workbench service in a FastAPI application without giving the Python process a Node or Postgres dependency.

pip install agent-workbench-fastapi

from contextlib import asynccontextmanager
from fastapi import FastAPI
from agent_workbench_fastapi import AgentWorkbenchProxy

workbench = AgentWorkbenchProxy("http://agent-workbench:8080/api/agent")

@asynccontextmanager
async def lifespan(_app: FastAPI):
    await workbench.verify_upstream()
    yield

app = FastAPI(lifespan=lifespan)
app.mount("/api/agent", workbench)

The proxy forwards only standard content negotiation, content, authentication, cookie, tracing, and idempotency headers by default. It does not forward client-supplied identity or tenant headers. The upstream Workbench service must verify the user credential, or the host must provide a resolve_headers callback that creates a trusted service-to-service identity assertion.

Request and response bodies are streamed. Long-running agent responses are not buffered by the adapter.

The adapter validates and caches the upstream service manifest before the first forwarded request. It returns agent_protocol_incompatible when the service is not Agent Workbench protocol v1, and agent_service_unavailable when it cannot be reached. Calling verify_upstream() during FastAPI lifespan makes a bad sidecar fail application startup instead of waiting for live traffic.

The adapter and TypeScript runtime have independent versions. Python releases use tags in the form agent-workbench-fastapi-vX.Y.Z and are published to PyPI. The Agent Workbench service itself can run beside the FastAPI application or elsewhere on the company's private network.