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

​
Start the backend

The agent starts with the backend — no extra step needed:
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:
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.