Containerized web service platform for building and orchestrating agentic workflows.
agent-lab provides a Go-based web service architecture for developing intelligent agentic workflows. Built on the foundation of:
- go-agents - LLM integration core
- go-agents-orchestration - Workflow patterns
- document-context - Document processing
agent-lab/
├── cmd/
│ ├── server/ # HTTP server entry point and composition
│ ├── migrate/ # Database migration CLI
│ └── seed/ # Database seeding CLI
├── internal/ # Private packages
│ ├── api/ # API module composition
│ ├── config/ # Configuration management
│ ├── providers/ # Provider domain (LLM configurations)
│ ├── agents/ # Agents domain (LLM agents)
│ ├── documents/ # Documents domain (file upload/management)
│ ├── images/ # Images domain (document rendering)
│ ├── profiles/ # Profiles domain (workflow configuration)
│ └── workflows/ # Workflows domain (execution infrastructure)
├── workflows/ # Workflow definitions
│ ├── summarize/ # Text summarization workflow
│ ├── reasoning/ # Multi-step reasoning workflow
│ └── classify/ # Document classification workflow
├── pkg/ # Public packages
│ ├── database/ # Database connection management
│ ├── decode/ # Type-safe map decoding
│ ├── handlers/ # HTTP response utilities
│ ├── lifecycle/ # Startup/shutdown coordination
│ ├── middleware/ # HTTP middleware (CORS, Logger, etc.)
│ ├── module/ # Modular HTTP routing
│ ├── openapi/ # OpenAPI spec utilities
│ ├── pagination/ # Pagination utilities
│ ├── query/ # SQL query builder
│ ├── repository/ # Database helpers
│ ├── routes/ # Route registration
│ ├── runtime/ # Server infrastructure (lifecycle, database, storage)
│ ├── storage/ # Blob storage abstraction
│ └── web/ # Web template utilities
├── web/ # Web modules
│ ├── app/ # Main web application
│ └── scalar/ # Scalar OpenAPI UI
├── tests/ # Black-box tests
├── compose/ # Docker Compose files
└── config.toml # Base configuration
# Start PostgreSQL docker compose -f compose/postgres.yml up -d # Run database migrations go run ./cmd/migrate -dsn "postgres://agent_lab:agent_lab@localhost:5432/agent_lab?sslmode=disable" -up # Seed database go run ./cmd/seed -dsn "postgres://agent_lab:agent_lab@localhost:5432/agent_lab?sslmode=disable" -all # Build and run server go build -o bin/server ./cmd/server ./bin/server # Health check (liveness) curl http://localhost:8080/healthz # Readiness check (subsystems operational) curl http://localhost:8080/readyz # API documentation (Scalar UI) open http://localhost:8080/scalar/ # Web application open http://localhost:8080/app/
Common tasks are available via Make:
make dev # Build web assets + run server make build # Production build (web + Go binary) make web # Build web assets only make run # Run server only make test # Run tests make vet # Run go vet make clean # Remove build artifacts
Configuration loads from config.toml with optional environment-specific overlays (config.{env}.toml) and environment variable overrides.
Set SERVICE_ENV to load an overlay:
SERVICE_ENV=dev ./bin/server # Loads config.dev.tomlSee config.toml for available settings.
# Run all tests go test ./tests/... -v # Run with coverage go test ./tests/... -cover
All endpoints are documented in the interactive Scalar UI at http://localhost:8080/scalar/.
| Domain | Prefix | Description |
|---|---|---|
| Providers | /api/providers |
LLM provider configurations (Ollama, Azure, etc.) |
| Agents | /api/agents |
Agent definitions with execution endpoints (Chat, Vision, Tools, Embed) |
| Documents | /api/documents |
Document upload and management |
| Images | /api/images |
Document page rendering with enhancement filters |
| Profiles | /api/profiles |
Workflow stage configurations for A/B testing |
| Workflows | /api/workflows |
Workflow execution with SSE streaming |
Getting Started Order: Providers → Agents → (Documents → Images for document workflows) → Profiles → Workflows
agent-lab includes sample workflows that demonstrate live agent integration. Test these via the Scalar API documentation at http://localhost:8080/scalar/.
- Ensure the server is running
- Create an agent profile via
POST /api/agents(or use an existing one) - Note the agent's UUID for use in workflow params
List registered workflows:
GET /api/workflows
Single-node workflow that summarizes input text using an AI agent.
Endpoint: POST /api/workflows/summarize/execute
Request Body (for Scalar interface):
{
"params": {
"agent_id": "<AGENT_UUID>",
"text": "The quick brown fox jumps over the lazy dog. This sentence contains every letter of the alphabet and is commonly used for typing practice."
}
}Optional Parameters:
system_prompt- Override the default summarization prompttoken- Runtime API token override
Multi-node workflow that performs step-by-step reasoning: analyze → reason → conclude.
Endpoint: POST /api/workflows/reasoning/execute
Request Body (for Scalar interface):
{
"params": {
"agent_id": "<AGENT_UUID>",
"problem": "If all roses are flowers and some flowers fade quickly, can we conclude that some roses fade quickly?"
}
}Optional Parameters:
analyze_system_prompt- Override the analyze node promptreason_system_prompt- Override the reason node promptconclude_system_prompt- Override the conclude node prompttoken- Runtime API token override
Multi-stage document classification workflow that analyzes PDF documents:
- Init - Loads document, renders page images
- Detect - Parallel vision analysis to identify markings on each page
- Enhance - Re-renders low-clarity pages with adjusted filters
- Classify - Determines document classification based on detected markings
- Score - Calculates confidence score with weighted factors
Endpoint: POST /api/workflows/classify/execute
Prerequisites:
- Upload a document via
POST /api/documents - Create or seed a workflow profile (
POST /api/profilesor usego run ./cmd/seed -all) - Have a vision-capable agent configured
Request Body (for Scalar interface):
{
"params": {
"document_id": "<DOCUMENT_UUID>",
"token": "<API_TOKEN>"
}
}Optional Parameters:
profile_id- Use a specific profile instead of the defaulttoken- API token for vision-capable LLM providers (e.g., Azure)
List all runs:
GET /api/workflows/runs
Get a specific run:
GET /api/workflows/runs/{run_id}
View execution stages (for multi-node workflows):
GET /api/workflows/runs/{run_id}/stages
View routing decisions:
GET /api/workflows/runs/{run_id}/decisions
- PROJECT.md - Project roadmap and milestones
- SNIPPETS.md - Execution snippets for terminal
- .claude/CLAUDE.md - Development context and skill index
- .claude/skills/ - Domain-specific patterns (on-demand)
All rights reserved.