> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-ai/connect-with-ai/openai-model-connector.md).
# OpenAI Model Connector
Configure OpenAI model access for Harness Worker Agents with API keys, AWS, GCP, or Azure cloud provider connectors, or LiteLLM endpoints
The OpenAI Model Connector defines the model endpoint and default model for your [Worker Agents](/harness-platform/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent.md). You can connect directly to OpenAI or use an OpenAI-compatible endpoint through a hosted LiteLLM proxy.
For cloud provider authentication, reference an existing AWS, GCP, or Azure connector to obtain credentials using its configured IAM role, OpenID Connect (OIDC), or other supported authentication method.
***
### What you will learn in this topic
By the end of this topic, you will be able to:
* [Understand which OpenAI models the connector supports](#supported-models).
* [Configure reasoning effort levels for cost and latency tradeoffs](#reasoning-effort-levels).
* [Configure authentication, the default model, and reasoning effort](#connector-configuration).
* [Use cloud provider connectors with IAM roles or OIDC](#cloud-provider-authentication).
* [Configure a LiteLLM endpoint and the Worker Agent backend](#litellm-connector-configuration).
* [Use the Harness-managed connector if you do not have model access](#harness-managed-connector).
***
### Before you begin
Before you configure the OpenAI Model Connector, ensure you have the following:
* **Harness AI enabled**: Harness AI must be active for your account. Go to [Overview](/harness-platform/use-harness-ai/harness-ai.md#enable-ai) for more information on activating Harness AI.
* **Model access**: Access to the models you intend to use through OpenAI, your cloud provider, or a hosted LiteLLM server.
* **Authentication credentials**: For API key authentication, store your OpenAI or LiteLLM API key as a [Harness text secret](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md). For **Cloud Provider**, configure an AWS, GCP, or Azure connector with the roles and permissions needed for model access.
* **Cloud connector access**: When you use **Cloud Provider**, you must have permission to use the referenced cloud provider connector.
* **Connector permissions**: Permission to create and manage connectors in your Harness project. Go to [RBAC in Harness](/harness-platform/3.0/harness-platform-resources/platform-access-control/rbac-in-harness.md) for more information on permissions.
***
### Supported models
For direct OpenAI access, the OpenAI Model Connector supports **GPT-5.5** with configurable reasoning effort.
For LiteLLM, use the exact model name configured on your LiteLLM server. For example, if your deployment exposes a model as `gpt-4o`, enter `gpt-4o` as the connector model name.
***
### Reasoning effort levels
The reasoning effort level controls how much reasoning the model applies before responding, trading latency and cost against depth. Set the reasoning effort level on the connector configuration form based on your task complexity requirements.
| Effort level | Description |
| ------------ | ---------------------------------------------------- |
| `low` | Fastest, lowest-cost responses for simple tasks |
| `medium` | Balanced reasoning and latency for most tasks |
| `high` | Deeper reasoning for complex tasks |
| `xhigh` | Maximum reasoning depth for the most demanding tasks |
***
### Connector configuration
Choose API key or cloud provider authentication, then configure your endpoint and default model.
| Authentication method | Configuration |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key | Reference an OpenAI or LiteLLM API key stored as a Harness secret. |
| **Cloud Provider** | Reference an existing **AWS Connector**, **GCP Connector**, or **Azure Connector** to obtain credentials through its configured authentication method, including IAM roles or OIDC. |
For cloud credentials, go to [Cloud provider authentication](#cloud-provider-authentication). For a proxy endpoint, go to [LiteLLM connector configuration](#litellm-connector-configuration) to configure the URL, API key, and model name.
For direct OpenAI API key access, set the following:
* **Authentication**: Provide an OpenAI API key. Reference the key from a [Harness secret](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md) rather than entering it in plain text.
* **Model Name**: Select the default model (GPT-5.5) the agent uses at runtime.
* **Reasoning Effort**: Select the default effort level (`low`, `medium`, `high`, or `xhigh`).
***
### Cloud provider authentication
Use **Cloud Provider** authentication to obtain credentials through an existing Harness cloud provider connector. Configure IAM roles, OIDC federation, or other supported credentials on that connector before referencing it from the OpenAI connector.
Use the setup guide for your cloud provider:
| Cloud provider selection | Credential setup |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AWS Connector** | Go to [Add an AWS connector](/harness-platform/use-harness-platform/connectors/cloud-providers/add-aws-connector.md) to configure IAM role or OIDC authentication. |
| **GCP Connector** | Go to [Connect to Google Cloud Platform](/harness-platform/use-harness-platform/connectors/cloud-providers/connect-to-google-cloud-platform-gcp.md) to configure inherited delegate credentials or OIDC authentication. |
| **Azure Connector** | Go to [Add a Microsoft Azure connector](/harness-platform/use-harness-platform/connectors/cloud-providers/add-a-microsoft-azure-connector.md) to configure managed identity or OIDC authentication. |
The referenced connector must have the cloud permissions required to access your selected model.
To configure the OpenAI connector:
1. In **Authentication**, select **Cloud Provider**.
2. In **Select Cloud Provider**, choose **AWS Connector**, **GCP Connector**, or **Azure Connector**.
3. In **Connector**, select the existing Harness connector for that provider.
4. Configure the endpoint and **Model Name** for your selected provider.
5. Complete the connectivity setup and connection test, then save the connector.
After you save it, select this connector as the **Model Provider** in your Worker Agent.
***
### LiteLLM connector configuration
LiteLLM provides an OpenAI-compatible API for the models configured on your server. Worker Agents send requests to that API, and LiteLLM normalizes the requests and routes them to the configured model provider.
Before you create the connector, prepare the following:
* **Hosted LiteLLM server**: The server URL must be reachable from your Worker Agent execution environment.
* **Configured models**: The models you intend to use must be configured on the LiteLLM server.
* **LiteLLM API key**: The key must have access to those models. Store it as a Harness text secret in your account.
To configure the connector:
1. In **Connectors**, create an **OpenAI** connector.
2. In **URL**, enter your hosted LiteLLM URL with `/v1` appended. For example, use `https://litellm.example.com/v1` for a server hosted at `https://litellm.example.com`.
3. In **API Key**, select the Harness secret containing your LiteLLM API key.
4. In **Model Name**, enter the exact model name configured on the LiteLLM server, such as `gpt-4o`.
5. Complete the connector setup and save it.
{% hint style="info" %}
**Local server URLs**
For a LiteLLM server at `http://localhost:4000`, the API URL is `http://localhost:4000/v1`. Use this only when the server is reachable at that address from the execution environment. A Worker Agent running on Harness Cloud cannot reach a LiteLLM server on your laptop through `localhost`.
{% endhint %}
### Use the LiteLLM connector in a Worker Agent
After you save the connector, create or edit a Worker Agent.
1. In the **Visual** tab, enter the agent **Name**.
2. Enter the agent **Instructions**.
3. Select any MCP connectors the agent needs.
4. For **Model Provider**, select the OpenAI connector you configured for LiteLLM.
5. Review and save the agent.
6. Open the **YAML** tab and set `with.backend` to `openai` under `agent`.
7. Save the updated agent.
{% hint style="warning" %}
**Set the OpenAI backend explicitly**
The LiteLLM setup currently requires `agent.with.backend: openai`. Set this value manually in the agent YAML so the agent uses the OpenAI-compatible API exposed by LiteLLM.
{% endhint %}
The following minimal agent definition shows the backend setting. Replace `litellm_model` with your LiteLLM model connector identifier. When you update an existing agent, keep its prompt, connectors, and inputs:
```yaml
agent:
uses: harnessAI@1.0.0
with:
prompt: Respond with a short greeting.
connector: litellm_model
backend: openai
```
Go to [Worker Agents](/harness-platform/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent.md) to review agent creation and pipeline setup.
***
### Next steps
* [Worker Agents](/harness-platform/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent.md): Create and configure agents that use this connector.
* [Anthropic Model Connector](/harness-platform/use-harness-ai/connect-with-ai/anthropic-model-connector.md): Configure Claude as your model provider.
{% @harness-feedback/feedback module="harness-ai" pagePath="harness-ai/use-harness-ai/connect-with-ai/openai-model-connector" %}