# 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:

```bash
uv sync
```

Create a local environment file:

```bash
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:

```bash
uv run uvicorn agent_lab.main:app --reload
```

Open the debug console:

```text
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:

```bash
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:

```bash
uv run pytest
```