AI model provider configuration

akka.javasdk.agent.additional-model-request-headers = [
  "X-Custom-Header:value",
  "X-Custom-Header-2:value-2",
]

akka.javasdk.agent.openai.additional-model-request-headers = ["X-Custom-Header:value"]

ADDITIONAL_MODEL_REQUEST_HEADERS_0="Authorization:Bearer mytoken"
ADDITIONAL_MODEL_REQUEST_HEADERS_1="X-Custom-Header:value"

ADDITIONAL_ANTHROPIC_REQUEST_HEADERS_0="Authorization:Bearer mytoken"

ModelProvider.openAi()
    .withApiKey(System.getenv("OPENAI_API_KEY"))
    .withAdditionalModelRequestHeaders(
        List.of(RawHeader.create("Authorization", "Bearer mygatewaytoken")));

ModelProvider.fromConfig()
    .withAdditionalModelRequestHeaders(
        List.of(RawHeader.create("X-Tenant", tenantId)));

# Configuration for Anthropic's large language models
akka.javasdk.agent.anthropic {
  # The provider name, must be "anthropic"
  provider = "anthropic"
  # The API key for authentication with Anthropic's API
  api-key = ""
  # Environment variable override for the API key
  api-key = ${?ANTHROPIC_API_KEY}
  # The name of the model to use, e.g. "claude-2" or "claude-instant-1"
  model-name = ""
  # Optional base URL override for the Anthropic API
  base-url = ""
  # Controls randomness in the model's output (0.0 to 1.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  top-p = NaN
  # Top-k sampling parameter (-1 to disable).
  # Top-k sampling limits text generation to only the k most probable
  # tokens at each step, discarding all other possibilities regardless
  # of their probability. It provides a simpler way to control randomness,
  # smaller k values (like 10) produce more focused outputs while larger
  # values (like 50) allow for more diversity.
  top-k = -1
  # Maximum number of tokens to generate (-1 for model default)
  max-tokens = -1
  # Fail the request if connecting to the model API takes longer than this
  connection-timeout = 15s
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # A maximum number of tokens to spend on thinking, use 0 to disable thinking
  thinking-budget-tokens = 0
  # Enable prompt caching of the last system message (reduces cost and latency for repeated
  # system prompts). Disabled by default. See the Anthropic prompt caching documentation.
  cache-system-messages = false
  # Enable prompt caching of the last tool definition (reduces cost and latency for repeated
  # tool specifications). Disabled by default.
  cache-tools = false
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_ANTHROPIC_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

# Configuration for Azure OpenAI large language models
akka.javasdk.agent.azure-openai {
  # The provider name, must be "azure-openai"
  provider = "azure-openai"
  # The endpoint of the Azure OpenAI resource, e.g. "https://my-resource.openai.azure.com"
  endpoint = ""
  # The name of the Azure OpenAI deployment to use
  deployment-name = ""
  # The API key for authentication with the Azure OpenAI resource
  api-key = ""
  # Environment variable override for the API key
  api-key = ${?AZURE_OPENAI_API_KEY}
  # Controls randomness in the model's output (0.0 to 1.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0).
  top-p = NaN
  # Maximum number of tokens to generate (-1 for model default)
  max-tokens = -1
  # Maximum number of completion tokens to generate (-1 for model default)
  max-completion-tokens = -1
  # Penalizes repeated tokens based on their frequency in the text so far (-2.0 to 2.0)
  frequency-penalty = NaN
  # Penalizes tokens that have already appeared in the text (-2.0 to 2.0)
  presence-penalty = NaN
  # Seed for deterministic sampling, for reproducible outputs (-1 for unset)
  seed = -1
  # Sequences where the model will stop generating further tokens
  stop = []
  # Reasoning effort level for o-series models ("low", "medium", "high", "" for unset)
  reasoning-effort = ""
  # Azure OpenAI API service version override (e.g. "2024-02-15-preview", "" for default)
  service-version = ""
  # Fail the request if connecting to the model API takes longer than this
  connection-timeout = 15s
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_AZURE_OPENAI_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

# Configuration for large language models from Amazon Bedrock https://aws.amazon.com/bedrock
akka.javasdk.agent.bedrock {
  # The provider name, must be "bedrock"
  provider = "bedrock"
  # The region to be used, e.g. "us-east-1"
  region = ""
  # The Bedrock model id, e.g. "ai21.jamba-1-5-large-v1:0"
  model-id = ""
  # Return thinking can be enabled
  return-thinking = false
  # Send thinking can be enabled
  send-thinking = false
  # Max output tokens
  max-output-tokens = -1
  # Reasoning token budget
  reasoning-token-budget = -1
  additional-model-request-fields {
    # additional-key = "additional value"
  }
  # The access token for authentication with the Bedrock API
  access-token = ""
  # Controls randomness in the model's output (0.0 to 1.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  top-p = NaN
  # Maximum number of tokens to generate (-1 for model default)
  max-tokens = -1
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # Enable prompt caching for Anthropic Claude or Amazon Nova models by selecting where the
  # cache point is placed. Valid values: "", "after-system", "after-user-message", "after-tools".
  # Empty disables prompt caching (default). See the AWS Bedrock prompt caching documentation.
  prompt-caching = ""
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_BEDROCK_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

# Configuration for Google's Gemini AI large language models
akka.javasdk.agent.googleai-gemini {
  # The provider name, must be "googleai-gemini"
  provider = "googleai-gemini"
  # The API key for authentication with Google AI Gemini's API
  api-key = ""
  # Optional base URL override for the Gemini API
  base-url = ""
  # Environment variable override for the API key
  api-key = ${?GOOGLE_AI_GEMINI_API_KEY}
  # The name of the model to use, e.g. "gemini-2.5-flash", "gemini-2.5-pro", etc
  # The full list is at https://ai.google.dev/gemini-api/docs/models - select a model to find its "Model code"
  model-name = ""
  # Controls randomness in the model's output (0.0 to 1.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  top-p = NaN
  # Maximum number of tokens to generate (-1 for model default)
  max-output-tokens = -1
  # Fail the request if connecting to the model API takes longer than this
  connection-timeout = 15s
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # A budget of tokens to spend on thinking for Gemini 2.5 models, set to "none" for other models
  # Can be -1 for dynamic budget, 0 for disabled, a positive value to define an upper limit for tokens spent on thinking.
  # See https://ai.google.dev/gemini-api/docs/thinking#set-budget for details
  thinking-budget = "none"
  # Control thinking for Gemini 3 models, exact values depend on the specific model chosen, must be empty for 2.5 models
  # See Google Gemini docs for more details: https://ai.google.dev/gemini-api/docs/thinking#thinking-levels
  thinking-level = ""
  # Defines the level for media resolution: https://ai.google.dev/gemini-api/docs/media-resolution
  # Possible values: MEDIA_RESOLUTION_UNSPECIFIED, MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH, MEDIA_RESOLUTION_ULTRA_HIGH
  media-resolution = "MEDIA_RESOLUTION_UNSPECIFIED"
  # Media resolution for individual media objects (like images) within your request
  media-resolution-per-part-enabled = false
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_GOOGLE_AI_GEMINI_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

# Configuration for large language models from HuggingFace https://huggingface.co
akka.javasdk.agent.hugging-face {
  # The provider name, must be "hugging-face"
  provider = "hugging-face"
  # The access token for authentication with the Hugging Face API
  access-token = ""
  # The Hugging face model id, e.g. "microsoft/Phi-3.5-mini-instruct"
  model-id = ""
  # Optional base URL override for the Hugging Face API
  base-url = ""
  # Controls randomness in the model's output (0.0 to 1.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  top-p = NaN
  # Maximum number of tokens to generate (-1 for model default)
  max-new-tokens = -1
  # Fail the request if connecting to the model API takes longer than this
  connection-timeout = 15s
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # Enable thinking, only supported for some models. Make sure the chosen model supports thinking before enabling.
  thinking = false
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_HUGGING_FACE_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

# Configuration for Local AI large language models
akka.javasdk.agent.local-ai {
  # The provider name, must be "local-ai"
  provider = "local-ai"
  # server base url
  base-url = "http://localhost:8080/v1"
  # One of the models installed in the Ollama server
  model-name = ""
  # Controls randomness in the model's output (0.0 to 1.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  top-p = NaN
  # Maximum number of tokens to generate (-1 for model default)
  max-tokens = -1
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_LOCAL_AI_REQUEST_HEADERS[]}
}

# Configuration for large language models from Mistral AI https://mistral.ai
akka.javasdk.agent.mistral-ai {
  # The provider name, must be "mistral-ai"
  provider = "mistral-ai"
  # The API key for authentication with Mistral AI's API
  api-key = ""
  api-key = ${?MISTRAL_AI_API_KEY}
  # The Mistral model name, e.g. "mistral-large-latest"
  model-name = ""
  # Optional base URL override for the Mistral AI API
  base-url = ""
  # Controls randomness in the model's output (0.0 to 1.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  top-p = NaN
  # Maximum number of tokens to generate (-1 for model default)
  max-tokens = -1
  # When enabled, a safety prompt is injected in front of all conversations
  safe-prompt = false
  # Random seed for deterministic sampling (-1 for none)
  random-seed = -1
  # Penalty for frequent tokens (NaN for model default)
  frequency-penalty = NaN
  # Penalty for repeated topics (NaN for model default)
  presence-penalty = NaN
  # Stop sequences at which the model stops generating
  stop-sequences = []
  # Enable thinking, only supported for some models. Make sure the chosen model supports thinking before enabling.
  thinking = false
  # Fail the request if connecting to the model API takes longer than this
  connection-timeout = 15s
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_MISTRAL_AI_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

# Configuration for Ollama large language models
akka.javasdk.agent.ollama {
  # The provider name, must be "ollama"
  provider = "ollama"
  # Ollama server base url
  base-url = "http://localhost:11434"
  # One of the models installed in the Ollama server
  model-name = ""
  # Controls randomness in the model's output (0.0 to 1.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  top-p = NaN
  # Fail the request if connecting to the model API takes longer than this
  connection-timeout = 15s
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # Enable thinking, only supported for some models. Make sure the chosen model supports thinking before enabling.
  think = false
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_OLLAMA_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

# Configuration for OpenAI's large language models
akka.javasdk.agent.openai {
  # The provider name, must be "openai"
  provider = "openai"
  # The API key for authentication with OpenAI's API
  api-key = ""
  # Environment variable override for the API key
  api-key = ${?OPENAI_API_KEY}
  # The name of the model to use, e.g. "gpt-4" or "gpt-3.5-turbo"
  model-name = ""
  # Optional base URL override for the OpenAI API
  base-url = ""
  # Controls randomness in the model's output (0.0 to 1.0)
  # Not supported by GPT-5.
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  # Not supported by GPT-5.
  top-p = NaN
  # Maximum number of tokens to generate (-1 for model default)
  # Not supported by GPT-5, use max-completion-tokens instead.
  max-tokens = -1
  # Maximum number of tokens to generate (-1 for model default)
  max-completion-tokens = -1
  # Fail the request if connecting to the model API takes longer than this
  connection-timeout = 15s
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # Enable thinking, only supported for deepseek. Make sure the chosen model supports thinking before enabling.
  thinking = false
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_OPENAI_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

# Configuration for large language models from Google Cloud Vertex AI https://cloud.google.com/vertex-ai
akka.javasdk.agent.vertex-ai {
  # The provider name, must be "vertex-ai"
  provider = "vertex-ai"
  # The Vertex AI model name, e.g. "gemini-2.0-flash-001"
  model-name = ""
  # The API key for authentication with Vertex AI
  # If using this, the project-id and location must be empty.
  api-key = ""
  api-key = ${?VERTEX_AI_API_KEY}
  # The Google Cloud project ID
  # If defining a project-id, location should also be defined. The api-key must be empty and credentials provided through GOOGLE_APPLICATION_CREDENTIALS
  project-id = ""
  # The Google Cloud region, e.g. "us-central1"
  location = ""
  # Optional base URL override for the Vertex AI API
  base-url = ""
  # Optional API version override, if left undefined beta API versions are used, set to for example "v1" to use a stable API version
  api-version = ""
  # Controls randomness in the model's output (0.0 to 2.0)
  temperature = NaN
  # Nucleus sampling parameter (0.0 to 1.0). Controls text generation by
  # only considering the most likely tokens whose cumulative probability
  # exceeds the threshold value. It helps balance between diversity and
  # quality of outputs—lower values (like 0.3) produce more focused,
  # predictable text while higher values (like 0.9) allow more creativity
  # and variation.
  top-p = NaN
  # Tokens to spend on thinking (0 to disable thinking)
  thinking-budget = 0
  # Maximum number of tokens to generate (-1 for model default)
  max-output-tokens = -1
  # Fail the request if connecting to the model API takes longer than this
  connection-timeout = 15s
  # Fail the request if getting a response from the model API takes longer than this
  response-timeout = 1m
  # Retry this many times if the request to the model fails
  max-retries = 2
  # Additional HTTP headers to include in each request to the model API.
  # Inherits from akka.javasdk.agent.additional-model-request-headers by default.
  additional-model-request-headers = ${akka.javasdk.agent.additional-model-request-headers}
  additional-model-request-headers = ${?ADDITIONAL_VERTEX_AI_REQUEST_HEADERS[]}
  # Send the agent id and flow id as HTTP headers with each request to the model API.
  # Inherits from akka.javasdk.agent.identity-headers by default.
  identity-headers = ${akka.javasdk.agent.identity-headers}
}

akka.javasdk {
  agent {
    model-provider = my-provider

    my-provider {
      # fully qualified class name of the provider implementation
      provider = "com.example.application.MyModelProvider"
      # additional settings
      model-name = "gpt-4o-mini"
      api-key = ""
      api-key = ${?MY_PROVIDER_API_KEY}
    }
  }
}

public class MyModelProvider implements ModelProvider.Custom {

  private final String modelName;

  public MyModelProvider(Config config) { (1)
    modelName = config.getString("model-name");
    //TODO model provider initialization based on injected config
  }

  @Override
  public String modelName() {
    return modelName;
  }

  @Override
  public Object createChatModel() { (2)
    //TODO return ChatModel implementation
    return null;
  }

  @Override
  public Object createStreamingChatModel() { (3)
    //TODO return StreamingChatModel implementation
    return null;
  }
}