> ## 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 OpenAI Agents SDK

> Point the OpenAI Agents SDK at Modellix with AsyncOpenAI base_url, Chat Completions, and provider/name model IDs.

Use the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) against the Modellix LLM gateway. The SDK accepts a custom OpenAI client (`base_url` + API key), so you can run agents on Chat Completions at [`POST /v1/chat/completions`](/llm/chat-completions) — the same gateway shape as the [OpenAI SDK](/llm/sdk/openai-sdk).

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

  Modellix model IDs are `provider/name` (for example `openai/gpt-5.5`). Pass that **full** string to the model layer. Prefer `OpenAIChatCompletionsModel` (or `MultiProvider` with `openai_prefix_mode="model_id"`) so the SDK does not strip the `openai/` prefix before calling Modellix. See [Models & Pricing](/llm/overview#models-and-pricing).
</Note>

## Set Up the Agents SDK

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

    ```bash theme={null}
    pip install openai-agents
    ```

    TypeScript:

    ```bash theme={null}
    npm install @openai/agents openai
    ```
  </Step>

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

    ```bash theme={null}
    export OPENAI_API_KEY="mdlx-xxxxxxxx"
    export OPENAI_BASE_URL="https://llm.modellix.ai/v1"
    ```

    | Setting           | Value                                         |
    | ----------------- | --------------------------------------------- |
    | `OPENAI_API_KEY`  | Modellix API Key (not an OpenAI platform key) |
    | `OPENAI_BASE_URL` | `https://llm.modellix.ai/v1` (include `/v1`)  |
    | Model             | Exact Modellix Model ID (`provider/name`)     |

    <Warning>
      OpenAI Tracing exports to OpenAI's platform. A Modellix key cannot upload traces. Disable tracing, or keep model traffic on Modellix and set a separate OpenAI tracing key.
    </Warning>
  </Step>

  <Step title="Create a Client and Agent (Recommended)">
    Build an `AsyncOpenAI` / `OpenAI` client pointed at Modellix, wrap it in `OpenAIChatCompletionsModel` with a literal Modellix Model ID, and disable tracing unless you have a separate OpenAI tracing key.

    <CodeGroup>
      ```python Python theme={null}
      import asyncio
      from openai import AsyncOpenAI
      from agents import (
          Agent,
          OpenAIChatCompletionsModel,
          Runner,
          set_tracing_disabled,
      )

      set_tracing_disabled(True)

      client = AsyncOpenAI(
          base_url="https://llm.modellix.ai/v1",
          api_key="mdlx-xxxxxxxx",  # or rely on OPENAI_API_KEY
      )

      agent = Agent(
          name="Assistant",
          instructions="You are a concise coding assistant.",
          model=OpenAIChatCompletionsModel(
              model="openai/gpt-5.5",
              openai_client=client,
          ),
      )

      async def main() -> None:
          result = await Runner.run(agent, "Say hello in one short sentence.")
          print(result.final_output)

      if __name__ == "__main__":
          asyncio.run(main())
      ```

      ```typescript TypeScript theme={null}
      import { OpenAI } from "openai";
      import {
        Agent,
        OpenAIChatCompletionsModel,
        Runner,
        setTracingDisabled,
      } from "@openai/agents";

      setTracingDisabled(true);

      const client = new OpenAI({
        baseURL: "https://llm.modellix.ai/v1",
        apiKey: process.env.OPENAI_API_KEY ?? "mdlx-xxxxxxxx",
      });

      const agent = new Agent({
        name: "Assistant",
        instructions: "You are a concise coding assistant.",
        model: new OpenAIChatCompletionsModel(client, "openai/gpt-5.5"),
      });

      const result = await Runner.run(agent, "Say hello in one short sentence.");
      console.log(result.finalOutput);
      ```
    </CodeGroup>

    Change the model string to any catalog ID (`anthropic/claude-sonnet-5`, `google/gemini-3.6-flash`, and so on). Traffic still uses Chat Completions on `https://llm.modellix.ai/v1`.
  </Step>

  <Step title="Optional: Global Default Client">
    To make Modellix the process-wide default without wrapping every agent:

    <CodeGroup>
      ```python Python theme={null}
      from openai import AsyncOpenAI
      from agents import (
          set_default_openai_api,
          set_default_openai_client,
          set_tracing_disabled,
      )

      set_tracing_disabled(True)
      set_default_openai_api("chat_completions")
      set_default_openai_client(
          AsyncOpenAI(
              base_url="https://llm.modellix.ai/v1",
              api_key="mdlx-xxxxxxxx",
          ),
          use_for_tracing=False,
      )
      ```

      ```typescript TypeScript theme={null}
      import { OpenAI } from "openai";
      import {
        setDefaultOpenAIClient,
        setOpenAIAPI,
        setTracingDisabled,
      } from "@openai/agents";

      setTracingDisabled(true);
      setOpenAIAPI("chat_completions");
      setDefaultOpenAIClient(
        new OpenAI({
          baseURL: "https://llm.modellix.ai/v1",
          apiKey: process.env.OPENAI_API_KEY ?? "mdlx-xxxxxxxx",
        }),
      );
      ```
    </CodeGroup>

    Then assign models carefully. String IDs like `openai/gpt-5.5` can be rewritten by the default OpenAI provider (it may drop the `openai/` prefix). Prefer `OpenAIChatCompletionsModel` with the full Modellix ID, or a `MultiProvider` with `openai_prefix_mode="model_id"` (Python) so the gateway receives `openai/gpt-5.5` unchanged. See [Agents SDK models](https://openai.github.io/openai-agents-python/models/).
  </Step>

  <Step title="Optional: Responses API">
    Modellix also exposes [`POST /v1/responses`](/llm/responses). The SDK defaults to Responses for OpenAI-hosted traffic. On a compatible gateway, start with Chat Completions (`set_default_openai_api("chat_completions")` / `setOpenAIAPI("chat_completions")`) unless you have verified Responses + tools for your agent loop.

    Keep `base_url` as `https://llm.modellix.ai/v1` for both shapes. Do not use the Anthropic host without `/v1` here — that path is for the [Anthropic SDK](/llm/sdk/anthropic-sdk) and [Claude Code](/llm/agent/claude-code).
  </Step>
</Steps>

## Troubleshooting

| Symptom                    | Check                                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| 401 / auth errors          | Key is a valid Modellix API key                                                             |
| Model not found / 404      | Full ID like `openai/gpt-5.5` reaches Modellix; avoid provider prefix stripping             |
| Wrong path                 | `base_url` is `https://llm.modellix.ai/v1` (include `/v1`)                                  |
| Tracing / export errors    | `set_tracing_disabled(True)` or a separate OpenAI tracing key with `use_for_tracing=False`  |
| Tools / Responses failures | Switch to Chat Completions (`OpenAIChatCompletionsModel` or `chat_completions` default API) |

## Related

* [OpenAI Agents SDK — Models](https://openai.github.io/openai-agents-python/models/) — custom clients and Chat Completions
* [OpenAI Agents SDK — Configuration](https://openai.github.io/openai-agents-python/config/) — `OPENAI_BASE_URL`, tracing, API shape
* [OpenAI platform — Agents models](https://developers.openai.com/api/docs/guides/agents/models) — model selection overview
* [OpenAI SDK](/llm/sdk/openai-sdk) — same `/v1` gateway without the Agents runtime
* [LangChain](/llm/framework/langchain) — another Chat Completions client path
* [Models & Pricing](/llm/overview#models-and-pricing) — Model IDs and rates
* [LLM API guide](/llm/api/api) — protocols and curl examples