Skip to main content
This page is the go-forward deployment path for AgentFlow. It covers the two local modes engineers need on day one, then the production contract for migrations, readiness, tenant prewarm, and observability.
There is no agentflow db upgrade command in the backend repo. Use the Make targets and Python scripts below.

​
Local full stack

Use this path for agent chat, conversations, artifacts, tools, knowledge bases, and any tenant-backed route. It starts PostgreSQL, Redis, and the hot-reload API through Docker Compose. 
git clone https://github.com/SynclyUS/agentflow.git
cd agentflow

uv sync --locked
cp .env.sample .env
Edit .env for local Docker: 
OPENAI_API_KEY=sk-proj-...
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/agentflow
DEV_AUTH_BYPASS=true
DEV_TENANT_NAME=agentflow
DEV_USER_ID=local-dev
TENANT=agentflow
TENANT_NAMES=agentflow
PREWARM_TENANTS=agentflow
Then start the stack and run migrations: 
make dev-db
make db-migrate-docker
make health
make doctor
The development API listens on http://localhost:8001. OpenAPI is available at http://localhost:8001/docs. Smoke-test the running app: 
curl http://localhost:8001/health
curl http://localhost:8001/ready
curl http://localhost:8001/api/v1/agents
DEV_AUTH_BYPASS=true is local-only. It lets the backend bind requests to DEV_TENANT_NAME and DEV_USER_ID when no bearer token is sent.

​
Health/docs-only mode

Use this mode only when you want to verify imports, inspect /docs, or confirm the process starts without a database. It is not an agent runtime. 
uv sync --locked
AGENTFLOW_ALLOW_NO_DATABASE=true uv run python -m uvicorn main:app --reload --port 8000
Smoke-test: 
curl http://localhost:8000/health
open http://localhost:8000/docs
Tenant-backed routes such as POST /api/v1/agent/{id}/chat require PostgreSQL, migrations, and either Auth0 or explicit local dev bypass.

​
Docker vs host database URLs

Use the Compose service hostname from inside Docker: 
postgresql://postgres:postgres@postgres:5432/agentflow
Use localhost for commands that run on your laptop: 
postgresql://postgres:postgres@localhost:5432/agentflow
If .env contains the Docker URL, prefer Docker-aware commands such as make db-migrate-docker. If you run Python scripts directly from the host, override the URL for that command: 
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/agentflow \
  uv run python scripts/db_migrate.py

​
Database migrations

Single-database local migration: 
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/agentflow \
  uv run python scripts/db_migrate.py
Tenant-aware migration runner: 
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/agentflow \
TENANT=agentflow \
  uv run python scripts/migrate_tenants.py
Docker local migration: 
make db-migrate-docker
Production deploys should run tenant-aware migrations before routing traffic to the new application image. Keep schema changes backward-compatible when a deploy spans multiple replicas.

​
Readiness and health

AgentFlow exposes two infrastructure probes:
ProbeUse forChecks
GET /healthLivenessProcess is running and memory is within threshold.
GET /readyReadinessDatabase connectivity and tenant-backed serving readiness.
Load balancers, ECS service checks, and post-migration smoke tests should use /ready. Use /health only to decide whether the process is alive.

​
Production environment

Start with these required variables: 
ENVIRONMENT=production
DATABASE_URL=postgresql://user:pass@db-host:5432/agentflow
OPENAI_API_KEY=sk-...
REDIS_URL=redis://redis:6379/0
CORS_ALLOWED_ORIGINS=https://app.yourcompany.com
ENCRYPTION_KEY=64_hex_characters
LOG_LEVEL=INFO
Add tenant and auth configuration: 
TENANT_NAMES=tenant_a,tenant_b
PREWARM_TENANTS=tenant_a,tenant_b

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://api.yourcompany.com
AUTH0_ISSUER=https://your-tenant.auth0.com/
AUTH0_M2M_AUDIENCE=https://api.yourcompany.com
AUTH0_M2M_ISSUER=https://your-tenant.auth0.com/
AUTH0_M2M_REQUIRED_SCOPE=agentflow:m2m
For single-tenant production, set TENANT and PREWARM_TENANTS to the same tenant key. For multi-tenant deployments, set TENANT_NAMES or provide the tenant registry integration used by scripts/migrate_tenants.py.

​
Deployment contract

Use this order in CI/CD:
  1. Build and publish the new image.
  2. Register the migration task definition with the new image and environment.
  3. Run tenant-aware migrations.
  4. Deploy or roll the API service.
  5. Smoke-test /health, /ready, and an authenticated /api/v1 route.
Example smoke checks: 
curl https://api.example.com/health
curl https://api.example.com/ready
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/api/v1/agents

​
First-request latency

Set PREWARM_TENANTS for tenants that should be bootstrapped at startup: 
PREWARM_TENANTS=tenant_a,tenant_b
Prewarming runs tenant bootstrap and warms agent/tool registry state before the first user request. Without it, the first request for a tenant can pay bootstrap cost in the request path.

​
Observability

AgentFlow supports integration with observability platforms for:
  • Distributed tracing across agent, tool, and sub-agent executions.
  • LLM metrics for token usage, latency, and cost tracking per model.
  • Structured logging with execution, tenant, and request context.
  • Readiness signals through /ready and deployment smoke checks.
Datadog LLM Observability uses: 
DD_TRACE_ENABLED=true
DD_LLMOBS_ENABLED=true
DD_LLMOBS_ML_APP=agentflow-prod
Keep DD_LLMOBS_ML_APP lowercase. See Configuration for the broader environment matrix.