agent-lab

Agent Lab

Agent Lab is a FastAPI debug console for chat agents and event agents. It uses an OpenAI Chat Completions compatible streaming endpoint, a WebSocket debug route, and a direct async runtime/event flow for local investigation.

Setup

Install dependencies with uv:

uv sync

Create a local environment file:

cp .env.example .env

Set these values in .env before running real LLM calls:

• AGENT_LAB_OPENAI_API_KEY: required API key for the compatible provider.
• AGENT_LAB_OPENAI_BASE_URL: provider /v1 root, for example https://api.openai.com/v1.
• AGENT_LAB_OPENAI_DEFAULT_MODEL: backend default model when a request leaves model blank.
• AGENT_LAB_OPENAI_INCLUDE_USAGE: set false if the compatible provider rejects stream_options.include_usage.
• AGENT_LAB_REQUEST_TIMEOUT_SECONDS: HTTP timeout for streamed model calls.

Do not commit real secrets. Keep .env local.

Run Locally

Start the FastAPI app:

uv run uvicorn agent_lab.main:app --reload

Open the debug console:

http://127.0.0.1:8000

The app exposes GET /health, GET /, and WebSocket /ws/debug.

WebSocket Smoke Test

With the server running and .env configured, send one debug request:

uv run python scripts/ws_smoke.py \
  --message "Debug this agent handoff path."

The script connects to ws://127.0.0.1:8000/ws/debug, sends a valid DebugRunRequest, and prints each server message as compact JSON. Use --model to override the backend default model, --disable-handoff-note to run without the default handoff_note tool, or --url to target a different server.

Tests

Run the full test suite:

uv run pytest