> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryzuko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents Setup

> Configure the AI agent that runs inside the NestJS backend.

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](/setup/backend))
* An OpenAI or Anthropic API key

***

## Environment variables

Add these to `apps/backend/.env`:

```env theme={null}
# ── 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
```

<Tip>
  `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`.
</Tip>

***

## Model format

The `AGENT_MODEL` variable uses `provider/model` format:

| Value                         | Provider  | Model             |
| ----------------------------- | --------- | ----------------- |
| `openai/gpt-4.1`              | OpenAI    | GPT-4.1           |
| `openai/gpt-4o`               | OpenAI    | GPT-4o            |
| `anthropic/claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
| `anthropic/claude-opus-4-6`   | Anthropic | Claude Opus 4.6   |

***

## Start the backend

The agent starts with the backend — no extra step needed:

```bash theme={null}
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](/concepts/sandbox) for filesystem and shell tools. For local development no extra setup is needed (`SPRITES_ENABLED=false`). For production, see [Sandbox Setup](/setup/sandbox).

***

## Tracing with LangSmith (optional)

To trace agent runs visually:

```env theme={null}
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your-langsmith-api-key
LANGSMITH_PROJECT=zuko
```

Sign up at [smith.langchain.com](https://smith.langchain.com) to get an API key.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent doesn't respond in chat">
    * 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
  </Accordion>

  <Accordion title="'invalid selectedModelId' error at startup">
    `AGENT_MODEL` must use the `provider/model` format, e.g. `openai/gpt-4.1`. A
    plain model name like `gpt-4o` is not valid.
  </Accordion>

  <Accordion title="Anthropic model not working">
    Set `ANTHROPIC_API_KEY` in `apps/backend/.env`. The `OPENAI_API_KEY` is only
    needed for OpenAI models.
  </Accordion>

  <Accordion title="Agent turns get stuck or don't stream">
    * 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.
  </Accordion>
</AccordionGroup>