openai-responses

Will be used to build the Authorization header, like so: Authorization: Bearer $api_key

Default: env.OPENAI_API_KEY

The base URL for the API.

Default: https://api.openai.com/v1

Additional headers to send with the request.

Example:

1
client<llm> MyResponsesClient {
2
  provider openai-responses
3
  options {
4
    api_key env.MY_OPENAI_KEY
5
    model "gpt-4.1"
6
    headers {
7
      "X-My-Header" "my-value"
8
    }
9
  }
10
}

Override the response format type. When using openai-responses provider, this defaults to "openai-responses".

You can also use the standard openai provider with client_response_type: "openai-responses" to format the response as a openai-responses response.

Example:

1
client<llm> StandardOpenAIWithResponses {
2
  provider openai
3
  options {
4
    api_key env.MY_OPENAI_KEY
5
    model "gpt-4.1"
6
    client_response_type "openai-responses"
7
  }
8
}

The role to use if the role is not in the allowed_roles. Default: "user" usually, but some models like OpenAI’s gpt-4o will use "system"

Picked the first role in allowed_roles if not “user”, otherwise “user”.

Which roles should we forward to the API? Default: ["system", "user", "assistant"] usually, but some models like OpenAI’s o1-mini will use ["user", "assistant"]

When building prompts, any role not in this list will be set to the default_role.

Which role metadata should we forward to the API? Default: []

For example you can set this to ["foo", "bar"] to forward the cache policy to the API.

If you do not set allowed_role_metadata, we will not forward any role metadata to the API even if it is set in the prompt.

Then in your prompt you can use something like:

1
client<llm> Foo {
2
  provider openai
3
  options {
4
    allowed_role_metadata: ["foo", "bar"]
5
  }
6
}
7
8
client<llm> FooWithout {
9
  provider openai
10
  options {
11
  }
12
}
13
template_string Foo() #"
14
  {{ _.role('user', foo={"type": "ephemeral"}, bar="1", cat=True) }}
15
  This will be have foo and bar, but not cat metadata. But only for Foo, not FooWithout.
16
  {{ _.role('user') }}
17
  This will have none of the role metadata for Foo or FooWithout.
18
"#

You can use the playground to see the raw curl request to see what is being sent to the API.

Controls the amount of reasoning effort the model should use.

Example:

1
client<llm> HighReasoningClient {
2
  provider openai-responses
3
  options {
4
    model "o4-mini"
5
    reasoning {
6
      effort "high"
7
    }
8
  }
9
}

Most models support the Responses API, some of the most popular models are:

See OpenAI’s Responses API documentation for the latest available models.

Tools that the model can use during reasoning. Supports function calling and web search.

Example with web search:

1
client<llm> WebSearchClient {
2
  provider openai-responses
3
  options {
4
    model "gpt-4.1"
5
    tools [
6
      {
7
        type "web_search_preview"
8
      }
9
    ]
10
  }
11
}