Skip to main content
The AI agent runs in-process inside the NestJS backend (apps/backend/src/agent/). There is no separate service to start — it activates automatically when a user sends a chat message. All agent configuration is done via environment variables in apps/backend/.env.

​
Prerequisites

  • Backend running (see Backend Setup)
  • An OpenAI or Anthropic API key

​
Environment variables

Add these to apps/backend/.env: 
# ── Model ─────────────────────────────────────────────────────────────────────

# Format: "<provider>/<model>"
# Supported providers: openai, anthropic
AGENT_MODEL=openai/gpt-4.1

# ── OpenAI ────────────────────────────────────────────────────────────────────
OPENAI_API_KEY=sk-...

# ── Anthropic (only needed if using anthropic/* models) ───────────────────────
# ANTHROPIC_API_KEY=sk-ant-...

# ── Tracing (optional) ────────────────────────────────────────────────────────
LANGSMITH_TRACING=false
LANGSMITH_API_KEY=
LANGSMITH_PROJECT=zuko
AGENT_MODEL defaults to openai/gpt-4.1 if not set. To switch to Claude, set AGENT_MODEL=anthropic/claude-sonnet-4-5 and add ANTHROPIC_API_KEY.

​
Model format

The AGENT_MODEL variable uses provider/model format:
ValueProviderModel
openai/gpt-4.1OpenAIGPT-4.1
openai/gpt-4oOpenAIGPT-4o
anthropic/claude-sonnet-4-5AnthropicClaude Sonnet 4.5
anthropic/claude-opus-4-6AnthropicClaude Opus 4.6

​
Start the backend

The agent starts with the backend — no extra step needed: 
bun nx run @zuko/backend:serve
Once running, open Zuko in the browser, create a chat, and send a message to verify the agent responds.

​
Sandbox configuration

The agent uses a sandbox for filesystem and shell tools. For local development no extra setup is needed (SPRITES_ENABLED=false). For production, see Sandbox Setup.

​
Tracing with LangSmith (optional)

To trace agent runs visually: 
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your-langsmith-api-key
LANGSMITH_PROJECT=zuko
Sign up at smith.langchain.com to get an API key.

​
Troubleshooting

  • Confirm OPENAI_API_KEY (or ANTHROPIC_API_KEY) is set in apps/backend/.env
  • Check the backend logs for errors from AgentService or ChatController
  • Ensure the database is running and migrations are applied — the agent uses LangGraph checkpointing backed by PostgreSQL
AGENT_MODEL must use the provider/model format, e.g. openai/gpt-4.1. A plain model name like gpt-4o is not valid.
Set ANTHROPIC_API_KEY in apps/backend/.env. The OPENAI_API_KEY is only needed for OpenAI models.
  • Check for AbortError in logs — a previous run may still be active. Call POST /api/v1/chat/stop to cancel it.
  • Verify FRONTEND_URL and TRUSTED_ORIGINS in apps/backend/.env are correct, as SSE responses may be blocked by CORS.