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

# Claude Agent SDK

> Use Claude Code and the Claude Agent SDK with Auriko's routing and cost optimization

Auriko routes Claude Code and Claude Agent SDK requests through multiple providers, giving you model choice, cost controls, and fallbacks.

<Note>
  Claude Code features work through Auriko: tool use, MCP servers, streaming, extended thinking, and prompt caching. Only LLM inference routes through Auriko; agentic operations (file I/O, bash, MCP) run locally.
</Note>

## Prerequisites

* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
* An [Auriko API key](https://auriko.ai/signup?redirectTo=%2Fdashboard%3Ftab%3Dapi-keys)

## Set up Claude Code

Add 3 environment variables to your shell profile (`~/.zshrc` or `~/.bashrc`):

```bash theme={null}
export ANTHROPIC_BASE_URL="https://api.auriko.ai"
export ANTHROPIC_AUTH_TOKEN="ak_live_..."  # from auriko.ai/dashboard
export ANTHROPIC_API_KEY=""
```

<Note>
  `ANTHROPIC_API_KEY=""` must be explicitly set to empty. If it contains a value, Claude Code uses it directly against Anthropic, bypassing Auriko.
</Note>

Reload your shell after saving:

```bash theme={null}
source ~/.zshrc   # or: source ~/.bashrc
```

## Verify setup

```bash theme={null}
claude -p "Say exactly: setup-ok" --model claude-haiku-4-5-20251001
```

Claude Code includes a system prompt on every request. The first request in a session costs more than follow-ups due to [prompt caching](/guides/prompt-caching).

## Use different models

You can pass an Auriko model ID with the `--model` flag:

```bash theme={null}
claude --model deepseek-v4-flash
claude --model gemini-2.5-flash
claude --model grok-4.3
```

Model IDs must be exact. Claude Code requires reasoning support from every model.

Models that don't support reasoning return a `400` error. Browse per-model capabilities in the [directory API](https://api.auriko.ai/v1/directory/models).

Available models include:

| Model                    | Author    | Context |
| ------------------------ | --------- | ------- |
| `claude-sonnet-4-6`      | Anthropic | 1M      |
| `claude-opus-4-6`        | Anthropic | 1M      |
| `claude-opus-4-7`        | Anthropic | 1M      |
| `deepseek-v4-flash`      | DeepSeek  | 1M      |
| `deepseek-v4-pro`        | DeepSeek  | 1M      |
| `gemini-2.5-flash`       | Google    | 1M      |
| `gemini-2.5-pro`         | Google    | 1M      |
| `gemini-3.1-pro-preview` | Google    | 1M      |
| `glm-5.1`                | Z.AI      | 200K    |
| `grok-4.3`               | xAI       | 1M      |
| `kimi-k2.5`              | Moonshot  | 262K    |
| `kimi-k2.6`              | Moonshot  | 262K    |
| `minimax-m2-7`           | MiniMax   | 205K    |
| `minimax-m2-7-highspeed` | MiniMax   | 205K    |
| `qwen-3.6-plus`          | Alibaba   | 1M      |

To list available models:

```bash theme={null}
curl -s -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  https://api.auriko.ai/v1/models | jq '.data[].id'
```

The `/model` picker in interactive sessions lists only Claude tier names (Opus, Sonnet, and Haiku). To switch to a non-Claude model mid-session, type the full ID: `/model deepseek-v4-flash`.

You can override which model each tier maps to:

```bash theme={null}
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-7"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
```

Add these to your shell profile alongside the other environment variables.

## Set up Claude Agent SDK

The Claude Agent SDK is Python-only. For TypeScript, use the Anthropic SDK directly (see below).

The Claude Agent SDK spawns Claude Code as a subprocess. Pass Auriko credentials through `ClaudeAgentOptions.env`:

```python theme={null}
import os
from claude_agent_sdk import ClaudeAgentOptions, query

options = ClaudeAgentOptions(
    model="sonnet",
    system_prompt="You are a code review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    env={
        "ANTHROPIC_BASE_URL": "https://api.auriko.ai",
        "ANTHROPIC_AUTH_TOKEN": os.environ["AURIKO_API_KEY"],
        "ANTHROPIC_API_KEY": "",
    },
)

async for message in query(prompt="Review main.py for bugs", options=options):
    print(message)
```

<Note>
  To prevent filesystem settings from overriding your `env` values, pass `setting_sources=[]` in options.
</Note>

## Use the Anthropic SDK directly

You can point the Anthropic SDK at Auriko's API:

<CodeGroup>
  ```python Python Auriko theme={null}
  import os
  import anthropic

  client = anthropic.Anthropic(
      base_url="https://api.auriko.ai",
      api_key=os.environ["AURIKO_API_KEY"],
  )

  response = client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello"}],
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  import Anthropic from "@anthropic-ai/sdk";

  const client = new Anthropic({
      baseURL: "https://api.auriko.ai",
      apiKey: process.env.AURIKO_API_KEY,
  });

  const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      messages: [{ role: "user", content: "Hello" }],
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/messages \
    -H "x-api-key: $AURIKO_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```
</CodeGroup>

## Configure routing

Add a `gateway` object to the request body:

<CodeGroup>
  ```python Python Auriko theme={null}
  response = client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello"}],
      extra_body={
          "gateway": {
              "routing": {"optimize": "cost"},
          },
      },
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      messages: [{ role: "user", content: "Hello" }],
      // @ts-expect-error -- gateway is an Auriko extension, not in Anthropic SDK types
      gateway: {
          routing: { optimize: "cost" },
      },
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/messages \
    -H "x-api-key: $AURIKO_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello"}],
      "gateway": {"routing": {"optimize": "cost"}}
    }'
  ```
</CodeGroup>

For Claude Code, configure routing at the workspace level in the [Auriko dashboard](https://auriko.ai/dashboard). See [routing options](/guides/routing-options) for details.

## Troubleshoot

| Symptom                                          | Cause                                                                                  | Fix                                                              |
| ------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| "model may not exist or you may not have access" | Model ID isn't exact (e.g., `claude-haiku-4-5` instead of `claude-haiku-4-5-20251001`) | Use the full model ID from `GET /v1/models`                      |
| Requests go to Anthropic directly, not Auriko    | `ANTHROPIC_API_KEY` contains a value                                                   | Set `ANTHROPIC_API_KEY=""` (empty string, not unset)             |
| "Invalid API Key" or auth errors                 | Cached Anthropic OAuth credentials                                                     | Run `claude auth logout`, then verify env vars are set           |
| Requests hang or timeout                         | `ANTHROPIC_BASE_URL` includes `/v1`                                                    | Use `https://api.auriko.ai` only                                 |
| "does not support reasoning/extended thinking"   | Claude Code requires reasoning support but this model doesn't have it                  | Use a reasoning-capable model (see "Use different models" above) |
| `apiKeySource: none` in session events           | Claude Code doesn't classify `ANTHROPIC_AUTH_TOKEN` as a key source                    | Expected behavior. Requests authenticate correctly               |