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

# Use Modellix LLM with the Claude Agent SDK

> Point the Claude Agent SDK at Modellix with ANTHROPIC_BASE_URL (no /v1), a Modellix API key, and anthropic/... model IDs.

Use the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) against the Modellix LLM gateway. The SDK drives the same Claude Code agent loop and speaks the Anthropic Messages API. Point it at Modellix the same way as [Claude Code](/llm/agent/claude-code): `ANTHROPIC_BASE_URL` without `/v1`, plus a Modellix API key.

<Note>
  This page covers **LLM text** only (`https://llm.modellix.ai`).

  The Agent SDK targets **Anthropic-compatible** endpoints, not OpenAI Chat Completions. Do not set `OPENAI_BASE_URL` or `https://llm.modellix.ai/v1` for this SDK. Use `https://llm.modellix.ai` and `anthropic/...` model IDs. See [Models & Pricing](/llm/overview#models-and-pricing).
</Note>

## Set Up the Claude Agent SDK

<Steps>
  <Step title="Install the SDK">
    Python:

    ```bash theme={null}
    pip install claude-agent-sdk
    ```

    TypeScript:

    ```bash theme={null}
    npm install @anthropic-ai/claude-agent-sdk
    ```

    Both packages typically bundle a Claude Code binary. If your install skips optional/native binaries, [install Claude Code](https://code.claude.com/docs/en/setup) and ensure it is on `PATH` (or set the SDK path option for your language).
  </Step>

  <Step title="Set Credentials">
    Create a Modellix API key in the [console](https://modellix.ai/console/api-key), then export:

    ```bash theme={null}
    export ANTHROPIC_API_KEY="mdlx-xxxxxxxx"
    export ANTHROPIC_BASE_URL="https://llm.modellix.ai"
    ```

    | Setting              | Value                                                            |
    | -------------------- | ---------------------------------------------------------------- |
    | `ANTHROPIC_API_KEY`  | Modellix API Key (sent as `x-api-key`)                           |
    | `ANTHROPIC_BASE_URL` | `https://llm.modellix.ai` (**without** `/v1`)                    |
    | Model                | Prefer `anthropic/...` (for example `anthropic/claude-sonnet-5`) |

    <Warning>
      Do not append `/v1` to `ANTHROPIC_BASE_URL`. The Claude Code binary / Anthropic client appends `/v1/messages` itself. Missing this rule commonly causes wrong-path or 404 errors.
    </Warning>

    If the client expects Bearer auth, use `ANTHROPIC_AUTH_TOKEN` instead of `ANTHROPIC_API_KEY`. Do not set both to different values.

    The SDK does not load `.env` files automatically. Export variables in the shell that runs your agent, or pass them through `ClaudeAgentOptions.env` (see next step).
  </Step>

  <Step title="Run a Query Against Modellix">
    The Python/TypeScript SDK spawns Claude Code and forwards environment variables. Set Modellix credentials in the process environment, or merge them into `options.env` so the subprocess always receives them.

    <CodeGroup>
      ```python Python theme={null}
      import asyncio
      from claude_agent_sdk import (
          AssistantMessage,
          ClaudeAgentOptions,
          ResultMessage,
          query,
      )

      async def main() -> None:
          async for message in query(
              prompt="Summarize this directory in one sentence.",
              options=ClaudeAgentOptions(
                  model="anthropic/claude-sonnet-5",
                  allowed_tools=["Read", "Glob"],
                  permission_mode="acceptEdits",
                  env={
                      "ANTHROPIC_API_KEY": "mdlx-xxxxxxxx",
                      "ANTHROPIC_BASE_URL": "https://llm.modellix.ai",
                  },
              ),
          ):
              if isinstance(message, AssistantMessage):
                  for block in message.content:
                      if hasattr(block, "text"):
                          print(block.text)
              elif isinstance(message, ResultMessage):
                  print(f"Done: {message.subtype}")

      asyncio.run(main())
      ```

      ```typescript TypeScript theme={null}
      import { query } from "@anthropic-ai/claude-agent-sdk";

      for await (const message of query({
        prompt: "Summarize this directory in one sentence.",
        options: {
          model: "anthropic/claude-sonnet-5",
          allowedTools: ["Read", "Glob"],
          permissionMode: "acceptEdits",
          env: {
            ANTHROPIC_API_KEY: "mdlx-xxxxxxxx",
            ANTHROPIC_BASE_URL: "https://llm.modellix.ai",
          },
        },
      })) {
        if (message.type === "assistant" && message.message?.content) {
          for (const block of message.message.content) {
            if ("text" in block) {
              console.log(block.text);
            }
          }
        } else if (message.type === "result") {
          console.log(`Done: ${message.subtype}`);
        }
      }
      ```
    </CodeGroup>

    Use an exact Modellix Model ID. Bare Anthropic Console names (for example `claude-sonnet-4-6`) are not Modellix catalog IDs.

    <Tip>
      You can omit `env` in code if `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` are already exported in the parent process. For production agents, prefer explicit `options.env` (or a secrets manager) so the subprocess does not depend on ambient shell state.
    </Tip>
  </Step>

  <Step title="Optional: Persist Like Claude Code">
    For interactive Claude Code and Agent SDK processes that inherit user settings, you can also persist the same values in `~/.claude/settings.json`:

    ```json theme={null}
    {
      "env": {
        "ANTHROPIC_BASE_URL": "https://llm.modellix.ai",
        "ANTHROPIC_API_KEY": "mdlx-xxxxxxxx"
      }
    }
    ```

    Details match the [Claude Code](/llm/agent/claude-code) guide. Prefer `options.env` when you need the Agent SDK process to be self-contained.
  </Step>
</Steps>

## Troubleshooting

| Symptom                 | Check                                                                       |
| ----------------------- | --------------------------------------------------------------------------- |
| API key not found / 401 | `ANTHROPIC_API_KEY` is a valid Modellix key in the process or `options.env` |
| 404 / wrong path        | `ANTHROPIC_BASE_URL` is `https://llm.modellix.ai` with **no** `/v1`         |
| Model not found         | Model is `anthropic/...` (full Modellix ID), not a bare Console name        |
| Still hitting Anthropic | Base URL is Modellix; no conflicting `ANTHROPIC_BASE_URL` elsewhere         |
| OpenAI-style 404s       | This SDK is not Chat Completions — do not use `https://llm.modellix.ai/v1`  |

## Related

* [Claude Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview) — capabilities and when to use the SDK
* [Claude Agent SDK quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart) — install, auth, first agent
* [Claude Code](/llm/agent/claude-code) — same `ANTHROPIC_BASE_URL` pattern for the CLI
* [Anthropic SDK](/llm/sdk/anthropic-sdk) — Messages protocol without the agent harness
* [OpenAI Agents SDK](/llm/sdk/openai-agents) — Chat Completions agent path on `/v1`
* [Models & Pricing](/llm/overview#models-and-pricing) — Model IDs and rates
* [Create message](/llm/messages) — OpenAPI reference