yaab.serve¶

FastAPI serving: /run, streaming SSE, A2A endpoints.

yaab.serve ¶

Serve agents over HTTP — a FastAPI app and an A2A-compatible server.

fastapi_server_app(agent) returns a ready-to-mount ASGI app exposing:

GET /.well-known/agent.json — the A2A Agent Card (discovery);
POST /run — run the agent (YAAB-native; background submits it as a task and returns 202 immediately);
GET /runs / GET /runs/{id} / POST /runs/{id}/cancel — the run lifecycle API (poll status, list, remotely cancel an in-flight run);
POST /a2a/tasks — A2A task submission (agent-to-agent);
GET /health — liveness.

With no extra wiring the app behaves exactly as before: an in-process registry holds runs, a background submission fires a task, and only an in-memory view is available. Passing durable backends makes the same endpoints production-grade:

run_store turns a background run into a durable queued row drained by an in-process :class:~yaab.runs.worker.RunWorker, so the run survives a restart and is visible (and cancellable) from any replica;
approval_store adds out-of-band human sign-off — list, approve, deny, and resume parked runs over HTTP;
trace_store persists each run's per-step timeline so a debugger can replay it with model/tool/token/cost/latency detail (/runs/{id}/events and /runs/{id}/trace);
run_checkpointer makes background runs fault-tolerant (resume from the last step after a crash) and is the seam approvals resume through;
cron_store adds durable schedules (/crons).

Every new parameter defaults to None (today's behavior, byte-for-byte). The new endpoints return a clean 404 when their backing store is not configured.

Authentication is pluggable via :mod:yaab.auth; the resolved identity flows into the run context and the audit log. FastAPI is an optional dependency, imported lazily so importing YAAB never requires a web stack.

fastapi_server_app ¶

fastapi_server_app(agent: Any, *, runner: Any | None = None, auth: AuthScheme | None = None, base_url: str = '', run_store: Any | None = None, approval_store: Any | None = None, trace_store: Any | None = None, run_checkpointer: Any | None = None, cron_store: Any | None = None, worker: Any | None = None) -> Any

Build a FastAPI app that serves agent (YAAB-native + A2A endpoints).

Parameters:

Name	Type	Description	Default
`agent`	`Any`	The agent to serve.	required
`runner`	`Any \| None`	An explicit :class:`~yaab.runner.Runner`; one is derived from the agent when omitted.	`None`
`auth`	`AuthScheme \| None`	Pluggable auth scheme (defaults to no auth).	`None`
`base_url`	`str`	Public base URL advertised on the agent card.	`''`
`run_store`	`Any \| None`	A durable run store. When set, a background `POST /run` becomes a durable queued row drained by an in-process worker, and the run lifecycle endpoints read/cancel through the store so a run survives a restart and is visible across replicas. `None` keeps the in-process registry (today's behavior).	`None`
`approval_store`	`Any \| None`	A durable approval store enabling the out-of-band sign-off endpoints (`/approvals*` and `/runs/{id}/resume`). The endpoints are absent/`404` without it.	`None`
`trace_store`	`Any \| None`	A durable per-run trace store enabling the history/trace endpoints (`/runs/{id}/events` and `/runs/{id}/trace`).	`None`
`run_checkpointer`	`Any \| None`	A checkpointer that makes background runs fault-tolerant and is the seam approvals resume through. When `None` and a durable `run_store` is configured, one is derived from the store's backend; the bare in-memory path stays zero-overhead.	`None`
`cron_store`	`Any \| None`	A durable schedule store enabling `/crons` and the worker's schedule ticks.	`None`
`worker`	`Any \| None`	Controls the in-process queue worker. `None` (default) builds one from the agent/store when a `run_store` is set. An explicit :class:`~yaab.runs.worker.RunWorker` is adopted as-is. Pass `worker=False` to disable the embedded worker — required for multi-replica deployments: run ONE external worker process (a standalone `RunWorker.run_forever()` loop, not embedded in each API replica) so several replicas don't each claim from the same queue. When a `run_store` is configured and the embedded worker is left enabled, this app is single-worker by design; scale the API tier horizontally only with `worker=False` plus a dedicated worker.	`None`

serve ¶

serve(agent: Any, *, host: str = '127.0.0.1', port: int = 8000, auth: AuthScheme | None = None, run_store: Any | None = None, approval_store: Any | None = None, trace_store: Any | None = None, run_checkpointer: Any | None = None, cron_store: Any | None = None) -> None

Run the agent's FastAPI app with uvicorn (blocking).

Durable backends (run_store/approval_store/trace_store/ run_checkpointer/cron_store) are forwarded so a production deployment gets durable background runs, out-of-band sign-off, and a persisted trace.