[OpenAI](https://platform.openai.com/docs/overview) is an AI research and deployment company that provides a suite of powerful language models. The Strands Agents SDK implements an OpenAI provider, allowing you to run agents against any OpenAI or OpenAI-compatible model.

## Installation

OpenAI is configured as an optional dependency in Strands Agents. To install, run:

(( tab "Python" ))
```bash
pip install 'strands-agents[openai]' strands-agents-tools
```
(( /tab "Python" ))

(( tab "TypeScript" ))
```bash
npm install @strands-agents/sdk openai
```
(( /tab "TypeScript" ))

## Usage

After installing dependencies, you can import and initialize the Strands Agents’ OpenAI provider as follows:

(( tab "Python" ))
```python
from strands import Agent
from strands.models.openai import OpenAIModel
from strands_tools import calculator

model = OpenAIModel(
    client_args={
        "api_key": "<KEY>",
    },
    # **model_config
    model_id="gpt-4o",
    params={
        "max_tokens": 1000,
        "temperature": 0.7,
    }
)

agent = Agent(model=model, tools=[calculator])
response = agent("What is 2+2")
print(response)
```
(( /tab "Python" ))

(( tab "TypeScript" ))
```typescript
import { Agent } from '@strands-agents/sdk'
import { OpenAIModel } from '@strands-agents/sdk/models/openai'

const model = new OpenAIModel({
  api: 'chat',
  apiKey: process.env.OPENAI_API_KEY || '<KEY>',
  modelId: 'gpt-5.4',
  maxTokens: 1000,
  temperature: 0.7,
})

const agent = new Agent({ model })
const response = await agent.invoke('What is 2+2')
console.log(response)
```
(( /tab "TypeScript" ))

To connect to a custom OpenAI-compatible server:

(( tab "Python" ))
```python
model = OpenAIModel(
    client_args={
      "api_key": "<KEY>",
      "base_url": "<URL>",
    },
    ...
)
```
(( /tab "Python" ))

(( tab "TypeScript" ))
```typescript
const model = new OpenAIModel({
  api: 'chat',
  apiKey: '<KEY>',
  clientConfig: {
    baseURL: '<URL>',
  },
  modelId: 'gpt-5.4',
})

const agent = new Agent({ model })
const response = await agent.invoke('Hello!')
```
(( /tab "TypeScript" ))

## Configuration

### Client Configuration

(( tab "Python" ))
The `client_args` configure the underlying OpenAI client. For a complete list of available arguments, please refer to the OpenAI [source](https://github.com/openai/openai-python).
(( /tab "Python" ))

(( tab "TypeScript" ))
The `clientConfig` configures the underlying OpenAI client. For a complete list of available options, please refer to the [OpenAI TypeScript documentation](https://github.com/openai/openai-node).
(( /tab "TypeScript" ))

### Model Configuration

The model configuration sets parameters for inference:

(( tab "Python" ))
| Parameter | Description | Example | Options |
| --- | --- | --- | --- |
| `model_id` | ID of a model to use | `gpt-4o` | [reference](https://platform.openai.com/docs/models) |
| `params` | Model specific parameters | `{"max_tokens": 1000, "temperature": 0.7}` | [reference](https://platform.openai.com/docs/api-reference/chat/create) |
(( /tab "Python" ))

(( tab "TypeScript" ))
| Parameter | Description | Example | Options |
| --- | --- | --- | --- |
| `modelId` | ID of a model to use | `gpt-5.4` | [reference](https://platform.openai.com/docs/models) |
| `maxTokens` | Maximum tokens to generate | `1000` | [reference](https://platform.openai.com/docs/api-reference/chat/create) |
| `temperature` | Controls randomness (0-2) | `0.7` | [reference](https://platform.openai.com/docs/api-reference/chat/create) |
| `topP` | Nucleus sampling (0-1) | `0.9` | [reference](https://platform.openai.com/docs/api-reference/chat/create) |
| `frequencyPenalty` | Reduces repetition (-2.0 to 2.0) | `0.5` | [reference](https://platform.openai.com/docs/api-reference/chat/create) |
| `presencePenalty` | Encourages new topics (-2.0 to 2.0) | `0.5` | [reference](https://platform.openai.com/docs/api-reference/chat/create) |
| `params` | Additional parameters not listed above | `{ stop: ["END"] }` | [reference](https://platform.openai.com/docs/api-reference/chat/create) |
(( /tab "TypeScript" ))

## Troubleshooting

(( tab "Python" ))
**Module Not Found**

If you encounter the error `ModuleNotFoundError: No module named 'openai'`, this means you haven’t installed the `openai` dependency in your environment. To fix, run `pip install 'strands-agents[openai]'`.

**GPT-OSS Tool Calling Fails on Non-Managed Endpoints**

If you are running GPT-OSS on an endpoint that isn’t a managed inference provider and you see errors like `Unexpected token ... while expecting start token ...` during tool calling, your endpoint likely doesn’t have the correct stop tokens configured.

As an immediate workaround, pass the GPT-OSS stop sequences explicitly via `params`:

```python
model = OpenAIModel(
    client_args={
        "api_key": "<KEY>",
        "base_url": "http://localhost:8000/v1",
    },
    model_id="<MODEL_ID>",
    params={"stop": ["<|call|>", "<|return|>", "<|end|>"]}
)
```

See the [OpenAI Harmony message format](https://cookbook.openai.com/articles/openai-harmony#message-format) for details on GPT-OSS stop tokens.
(( /tab "Python" ))

(( tab "TypeScript" ))
**Authentication Errors**

If you encounter authentication errors, ensure your OpenAI API key is properly configured. Set the `OPENAI_API_KEY` environment variable or pass it via the `apiKey` parameter in the model configuration.

**GPT-OSS Tool Calling Fails on Non-Managed Endpoints**

If you are running GPT-OSS on an endpoint that isn’t a managed inference provider and you see errors like `Unexpected token ... while expecting start token ...` during tool calling, your endpoint likely doesn’t have the correct stop tokens configured.

As an immediate workaround, pass the GPT-OSS stop sequences explicitly via `params`:

```typescript
import { OpenAIModel } from '@strands-agents/sdk/models/openai'

const model = new OpenAIModel({
  api: 'chat',
  apiKey: '<KEY>',
  clientConfig: {
    baseURL: 'http://localhost:8000/v1',
  },
  modelId: '<MODEL_ID>',
  params: { stop: ['<|call|>', '<|return|>', '<|end|>'] },
})
```

See the [OpenAI Harmony message format](https://cookbook.openai.com/articles/openai-harmony#message-format) for details on GPT-OSS stop tokens.
(( /tab "TypeScript" ))

## Advanced Features

### Structured Output

OpenAI models support structured output through their native tool calling capabilities. Pass a schema to the agent, and Strands converts it to OpenAI’s function calling format and validates the response.

(( tab "Python" ))
Define a Pydantic model and pass it to `agent.structured_output()`:

```python
from pydantic import BaseModel, Field
from strands import Agent
from strands.models.openai import OpenAIModel

class PersonInfo(BaseModel):
    """Extract person information from text."""
    name: str = Field(description="Full name of the person")
    age: int = Field(description="Age in years")
    occupation: str = Field(description="Job or profession")

model = OpenAIModel(
    client_args={"api_key": "<KEY>"},
    model_id="gpt-4o",
)

agent = Agent(model=model)

result = agent.structured_output(
    PersonInfo,
    "John Smith is a 30-year-old software engineer working at a tech startup."
)

print(f"Name: {result.name}")      # "John Smith"
print(f"Age: {result.age}")        # 30
print(f"Job: {result.occupation}") # "software engineer"
```
(( /tab "Python" ))

(( tab "TypeScript" ))
Define a Zod schema and pass it as `structuredOutputSchema`. Validated output is on `result.structuredOutput`:

```typescript
import { Agent } from '@strands-agents/sdk'
import { OpenAIModel } from '@strands-agents/sdk/models/openai'
import { z } from 'zod'

const PersonInfo = z.object({
  name: z.string().describe('Full name of the person'),
  age: z.number().describe('Age in years'),
  occupation: z.string().describe('Job or profession'),
})

const model = new OpenAIModel({
  api: 'chat',
  apiKey: process.env.OPENAI_API_KEY || '<KEY>',
  modelId: 'gpt-4o',
})

const agent = new Agent({ model, structuredOutputSchema: PersonInfo })

const result = await agent.invoke(
  'John Smith is a 30-year-old software engineer working at a tech startup.'
)

const person = result.structuredOutput as z.infer<typeof PersonInfo>
console.log(`Name: ${person.name}`) // "John Smith"
console.log(`Age: ${person.age}`) // 30
console.log(`Job: ${person.occupation}`) // "software engineer"
```
(( /tab "TypeScript" ))

For schema patterns, error handling, and per-invocation overrides, see [Structured Output](/docs/user-guide/concepts/agents/structured-output/index.md).

### Custom client

Users can pass their own custom OpenAI client to the OpenAIModel for Strands Agents to use directly. Users are responsible for handling the lifecycle (e.g., closing) of the client.

(( tab "Python" ))
```python
from strands import Agent
from strands.models.openai import OpenAIModel
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key= "<KEY>",
)

agent = Agent(
    model = OpenAIModel(
        model_id="gpt-4o-mini-2024-07-18",
        client=client
    )
)

async def chat(prompt: str):
    result = await agent.invoke_async(prompt)
    print(result)

async def main():
    await chat("What is 2+2")
    await chat("What is 2*2")
    # close the client
    client.close()

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

(( tab "TypeScript" ))
```ts
// Custom client capability is not yet supported in the TypeScript SDK
```
(( /tab "TypeScript" ))

## References

-   [Python API](/docs/api/python/strands.models.model)
-   [OpenAI](https://platform.openai.com/docs/overview)

## Related pages

- [Writer](/docs/user-guide/concepts/model-providers/writer/index.md) (2 shared tags)
- [LiteLLM](/docs/user-guide/concepts/model-providers/litellm/index.md) (1 shared tag)
- [Structured Output](/docs/user-guide/concepts/agents/structured-output/index.md) (1 shared tag)
- [Google](/docs/user-guide/concepts/model-providers/google/index.md) (1 shared tag)
- [Vercel](/docs/user-guide/concepts/model-providers/vercel/index.md) (1 shared tag)
- [Anthropic](/docs/user-guide/concepts/model-providers/anthropic/index.md) (1 shared tag)
- [Multimodal Correctness Evaluator](/docs/user-guide/evals-sdk/evaluators/multimodal_correctness_evaluator/index.md) (1 shared tag)
- [Multimodal Faithfulness Evaluator](/docs/user-guide/evals-sdk/evaluators/multimodal_faithfulness_evaluator/index.md) (1 shared tag)
- [Multimodal Instruction Following Evaluator](/docs/user-guide/evals-sdk/evaluators/multimodal_instruction_following_evaluator/index.md) (1 shared tag)
- [Multimodal Output Evaluator](/docs/user-guide/evals-sdk/evaluators/multimodal_output_evaluator/index.md) (1 shared tag)


## Implementation

### Python

- [harness-sdk/strands-py/src/strands/models/openai.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai.py)

### TypeScript

- [harness-sdk/strands-ts/src/models/openai/model.ts](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/openai/model.ts)