Build, simulate and test LLM agents. The Agent-Lab reference app, ready to run.
10K+
Build agents. Simulate them. Ship them with confidence.
bsantanna/agent-lab is the reference application of Agent-Lab — a cloud-native framework for building, simulating and testing LLM agents on FastAPI, LangGraph and PostgreSQL. RAG, browser automation, voice, vision and multi-agent supervisors, served through a REST API and an MCP server, in a single image.
Agent-Lab reads its configuration and API keys from HashiCorp Vault:
docker run -d --name agent-lab -p 8000:8000 \
-e VAULT_URL=http://vault:8200 \
-e VAULT_TOKEN=... \
bsantanna/agent-lab:v1.17.12
Check that it's up, then explore the API:
curl http://localhost:8000/status/liveness
Interactive API docs live at http://localhost:8000/docs.
Agent-Lab works alongside PostgreSQL with pgvector, Redis and Vault. The fastest way to get all of it is the project template, which scaffolds an app with a ready-made compose.yml:
uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter
cd <your-project> && docker compose up --build -d
The Setup guide covers development and Kubernetes.
| Variable | Default | Purpose |
|---|---|---|
VAULT_URL, VAULT_TOKEN | — | Where configuration and secrets are read from. |
VAULT_ENGINE_PATH | secret | KV v2 mount point. |
VAULT_SECRET_PATH | app_secrets | Secret path. See the secret payload. |
VAULT_K8S_ROLE | — | Authenticate to Vault with the pod's Kubernetes service account. |
DOCKER | — | Use the bundled Compose config instead of Vault (expects hosts postgres, redis, vault, headless-shell). |
PORT | 8000 | HTTP port. |
WORKERS | 1 | Uvicorn worker processes. |
Full reference: Configuration.
Every release is signed with Sigstore Cosign, using GitHub's OIDC identity. Verify before you deploy:
cosign verify bsantanna/agent-lab:v1.17.12 \
--certificate-identity-regexp 'https://github.com/btech-software/agent-lab/.github/workflows/docker-image.yml@refs/tags/v.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
| Runtime | Python 3.12, slim, digest-pinned |
| Server | FastAPI on Uvicorn, port 8000 |
| Media | Static ffmpeg for voice and video agents |
| User | Runs as the unprivileged agent-lab user |
| Tag | Meaning |
|---|---|
vX.Y.Z | A semantic version release, e.g. v1.17.12. Matches the PyPI package and Helm chart. |
Multi-architecture: linux/amd64 and linux/arm64.
github.com/btech-software/agent-lab · MIT License
Content type
Image
Digest
sha256:ea2200612…
Size
251 Bytes
Last updated
9 days ago
docker pull bsantanna/agent-lab:sha256-d97d5dc4118fba90708069489dea4163fdb650c3df0b9a3d670b097b4f6987fa.sig