Skip to content

OpenAI models for ADK agents

Supported in ADKGo v2.1.0Experimental

Experimental

The openaimodel package is experimental and its behavior may change or be removed in the future. We welcome your feedback!

You can use OpenAI models with ADK. How you connect depends on the language:

  • Go — native support: ADK Go provides a direct openaimodel package that implements the model.LLM interface, targeting the OpenAI Responses API or the Chat Completions API. Get started.
  • Python — via LiteLLM: ADK Python accesses OpenAI models (and many other providers) through the LiteLLM connector. See LiteLLM.

Get started

The openaimodel package provides a client for interacting with OpenAI's API. It implements the model.LLM interface and uses the OpenAI Responses API by default, or the Chat Completions API when ClientConfig.API selects it. The following code example shows a basic implementation for using OpenAI models in your agents:

import (
    "context"
    "log"

    "github.com/openai/openai-go/v3"
    "google.golang.org/adk/v2/agent/llmagent"
    "google.golang.org/adk/v2/model/openaimodel"
)

// Instantiate the model
llm, err := openaimodel.NewModel(context.Background(), openai.ChatModelGPT4oMini, &openaimodel.ClientConfig{})
if err != nil {
  log.Fatal(err)
}

// Create the agent
agent, err := llmagent.New(llmagent.Config{
  Name:        "openai_agent",
  Model:       llm,
  Instruction: "You are a helpful AI assistant.",
})
if err != nil {
  log.Fatal(err)
}

For a complete, runnable sample, see examples/openai/responses/ in the ADK Go repository.

Requires ADK Go v2.5.0 or later.

import (
    "context"
    "log"
    "os"

    "github.com/openai/openai-go/v3"
    "google.golang.org/adk/v2/agent/llmagent"
    "google.golang.org/adk/v2/model/openaimodel"
)

// Instantiate the model on the Chat Completions API
llm, err := openaimodel.NewModel(context.Background(), openai.ChatModelGPT4oMini, &openaimodel.ClientConfig{
  APIKey: os.Getenv("OPENAI_API_KEY"),
  API:    openaimodel.APIChatCompletions,
})
if err != nil {
  log.Fatal(err)
}

// Create the agent
agent, err := llmagent.New(llmagent.Config{
  Name:        "openai_agent",
  Model:       llm,
  Instruction: "You are a helpful AI assistant.",
})
if err != nil {
  log.Fatal(err)
}

For a complete, runnable sample, see examples/openai/completions/ in the ADK Go repository.

Chat Completions API

Supported in ADKGo v2.5.0Experimental

By default, openaimodel sends requests to the OpenAI Responses API (POST /v1/responses). Nearly every OpenAI-compatible provider implements the Chat Completions API (POST /v1/chat/completions), and some implement only that one. To use it, set the API field of ClientConfig to openaimodel.APIChatCompletions, as the Chat Completions API tab under Get started shows. Agents, tools, and the runner work the same way with either API.

Set the API key for other providers

To reach another OpenAI-compatible provider, set BaseURL to its endpoint and APIKey to its key. When APIKey is empty, the openai-go SDK falls back to the OPENAI_API_KEY environment variable and sends that key to BaseURL.

The two APIs support the same features, with these differences:

  • Generation settings: StopSequences, FrequencyPenalty, PresencePenalty, and Seed are sent to the Chat Completions API. The Responses API has no equivalent fields and returns an error for them.
  • Reasoning output: The Chat Completions API does not return reasoning text, so responses contain no thought parts, and ThinkingConfig.IncludeThoughts is ignored. Reasoning effort and reasoning-token counts work with both APIs.
  • Output token limit: MaxOutputTokens is sent as max_completion_tokens. Some compatible servers honor only the older max_tokens field, so the limit has no effect there.

Supported features

  • Text generation (streaming and non-streaming)
  • Function (tool) calling
  • Structured output via OutputSchema (JSON schema)
  • Reasoning models (e.g. o-series), including reasoning-token accounting
  • Token logprobs

Limitations

  • Text only — multimodal input (images, audio, files) is not supported.
  • Function tools only — built-in tools (Google Search, code execution, etc.) are not supported.
  • Structured output uses OpenAI strict mode — every field declared in an OutputSchema is treated as required.
  • Some GenerateContentConfig options return an error rather than being silently ignored: TopK, multiple candidates, request labels, and safety settings. The Responses API also rejects stop sequences, frequency/presence penalties, and seed, which the Chat Completions API supports.

Configuration options

The ClientConfig provides several options for configuring the client:

  • APIKey: Your OpenAI API key.
  • BaseURL: Custom endpoint URL, which can be useful for OpenAI-compatible endpoints.
  • HTTPClient: A custom *http.Client.
  • Options: Advanced openai-go request options ([]option.RequestOption).
  • API: The OpenAI API to call: openaimodel.APIResponses (the default) or openaimodel.APIChatCompletions. See Chat Completions API.

If APIKey or BaseURL are left empty, they will automatically fall back to the OPENAI_API_KEY and OPENAI_BASE_URL environment variables, handled by the default behavior of the underlying openai-go SDK.

OpenAI model authentication

When using OpenAI models, you must provide an API key to authenticate with the OpenAI API. The most direct way to provide this information is to use environment variables or an .env file.

The openaimodel package also supports OpenAI-compatible endpoints (such as local models served via Ollama, LM Studio, or vLLM) by configuring the base URL. If the endpoint does not serve the Responses API, also set API to openaimodel.APIChatCompletions, as described in Chat Completions API.

# .env configuration file
OPENAI_API_KEY="PASTE_YOUR_OPENAI_API_KEY_HERE"

# .env configuration file
OPENAI_API_KEY="api-key-if-required"
OPENAI_BASE_URL="http://localhost:11434/v1" # example: local Ollama endpoint