vertex-ai

The base URL for the API.

Default: inferred from the project_id and location using the following format:

https://{LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/{LOCATION}/publishers/google/models/

If the location is global, the base URL will be:

https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/google/models/

Can be used in lieu of the project_id and location fields, to manually set the request URL.

The Google Cloud project ID hosting the Vertex AI service you want to call.

Default: inferred from the provided credentials (see Authentication).

Vertex requires you to specify the location you want to serve your models from. Some models may only be available in certain locations.

Common locations include:

• us-central1
• us-west1
• us-east1
• us-south1

See the Vertex AI docs for all locations and supported models.

This field supports any of 3 formats:

• A string containing service account credentials in JSON format.
• Path to a file containing service account credentials in JSON format.
• A JSON object containing service account credentials.

See Authentication and Debugging for more information.

Default: env.GOOGLE_APPLICATION_CREDENTIALS

1
client<llm> Vertex {
2
  provider vertex-ai
3
  options {
4
    model gemini-2.5-pro
5
    location us-central1
6
    // credentials can be a block string containing service account credentials in JSON format
7
    credentials #"
8
      {
9
        "type": "service_account",
10
        "project_id": "my-project-id",
11
        "private_key_id": "string",
12
        "private_key": "-----BEGIN PRIVATE KEY-----string\n-----END PRIVATE KEY-----\n",
13
        "client_email": "john_doe@gmail.com",
14
        "client_id": "123456",
15
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
16
        "token_uri": "https://oauth2.googleapis.com/token",
17
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
18
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/...",
19
        "universe_domain": "googleapis.com"
20
      }
21
    "#
22
  }
23
}

1
client<llm> Vertex {
2
  provider vertex-ai
3
  options {
4
    model gemini-2.5-pro
5
    location us-central1
6
    credentials "path/to/credentials.json"
7
  }
8
}

1
client<llm> Vertex {
2
  provider vertex-ai
3
  options {
4
    model gemini-2.5-pro
5
    location us-central1
6
    // credentials can be a block string containing service account credentials in JSON format
7
    credentials {
8
      type "service_account",
9
      project_id "my-project-id",
10
      private_key_id "string",
11
      private_key "-----BEGIN PRIVATE KEY-----string\n-----END PRIVATE KEY-----\n",
12
      client_email "john_doe@gmail.com",
13
      client_id "123456",
14
      auth_uri "https://accounts.google.com/o/oauth2/auth",
15
      token_uri "https://oauth2.googleapis.com/token",
16
      auth_provider_x509_cert_url "https://www.googleapis.com/oauth2/v1/certs",
17
      client_x509_cert_url "https://www.googleapis.com/robot/v1/metadata/...",
18
      universe_domain "googleapis.com"
19
    }
20
  }
21
}

A string containing service account credentials in JSON format.

See Authentication and Debugging for more information.

Default: env.GOOGLE_APPLICATION_CREDENTIALS_CONTENT

1
client<llm> Vertex {
2
  provider vertex-ai
3
  options {
4
    model gemini-2.5-pro
5
    location us-central1
6
    // credentials_content is a block string containing service account credentials in JSON format
7
    credentials_content #"
8
      {
9
        "type": "service_account",
10
        "project_id": "my-project-id",
11
        "private_key_id": "string",
12
        "private_key": "-----BEGIN PRIVATE KEY-----string\n-----END PRIVATE KEY-----\n",
13
        "client_email": "john_doe@gmail.com",
14
        "client_id": "123456",
15
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
16
        "token_uri": "https://oauth2.googleapis.com/token",
17
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
18
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/...",
19
        "universe_domain": "googleapis.com"
20
      }
21
    "#
22
  }
23
}

The Google model to use for the request.

See the Google Model Docs for the latest models.

Additional headers to send with the request.

Example:

1
client<llm> MyClient {
2
  provider vertex-ai
3
  options {
4
    model gemini-2.5-pro
5
    project_id my-project-id
6
    location us-central1
7
    // Additional headers
8
    headers {
9
      "X-My-Header" "my-value"
10
    }
11
  }
12
}

Query string parameters appended to the request URL.

Example (use a Vertex API Key with Express Mode):

1
client<llm> MyClient {
2
  provider vertex-ai
3
  options {
4
    model gemini-2.5-pro
5
    project_id my-project-id
6
    location us-central1
7
    query_params {
8
      key env.VERTEX_API_KEY
9
    }
10
  }
11
}

When using an API key, omit credentials and set project_id explicitly.

The role to use if the role is not in the allowed_roles. Default: "user" usually, but some models like OpenAI’s gpt-5 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.

A mapping to transform role names before sending to the API. Default: {} (no remapping)

For google-ai provider, the default is: { "assistant": "model" }

This allows you to use standard role names in your prompts (like “user”, “assistant”, “system”) but send different role names to the API. The remapping happens after role validation and default role assignment.

Example:

1
{
2
  "user": "human",
3
  "assistant": "ai",
4
}

With this configuration, {{ _.role("user") }} in your prompt will result in a message with role “human” being sent to the API.

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.

Whether the internal LLM client should use the streaming API. Default: true

Then in your prompt you can use something like:

1
client<llm> MyClientWithoutStreaming {
2
  provider anthropic
3
  options {
4
    model claude-3-5-haiku-20241022
5
    api_key env.ANTHROPIC_API_KEY
6
    max_tokens 1000
7
    supports_streaming false
8
  }
9
}
10
11
function MyFunction() -> string {
12
  client MyClientWithoutStreaming
13
  prompt #"Write a short story"#
14
}

1
# This will be streamed from your python code perspective, 
2
# but under the hood it will call the non-streaming HTTP API
3
# and then return a streamable response with a single event
4
b.stream.MyFunction()
5
6
# This will work exactly the same as before
7
b.MyFunction()

Which finish reasons are allowed? Default: null

Will raise a BamlClientFinishReasonError if the finish reason is not in the allow list. See Exceptions for more details.

Note, only one of finish_reason_allow_list or finish_reason_deny_list can be set.

For example you can set this to ["stop"] to only allow the stop finish reason, all other finish reasons (e.g. length) will treated as failures that PREVENT fallbacks and retries (similar to parsing errors).

Then in your code you can use something like:

1
client<llm> MyClient {
2
  provider "openai"
3
  options {
4
    model "gpt-5-mini"
5
    api_key env.OPENAI_API_KEY
6
    // Finish reason allow list will only allow the stop finish reason
7
    finish_reason_allow_list ["stop"]
8
  }
9
}

Which finish reasons are denied? Default: null

Will raise a BamlClientFinishReasonError if the finish reason is in the deny list. See Exceptions for more details.

Note, only one of finish_reason_allow_list or finish_reason_deny_list can be set.

For example you can set this to ["length"] to stop the function from continuing if the finish reason is length. (e.g. LLM was cut off because it was too long).

Then in your code you can use something like:

1
client<llm> MyClient {
2
  provider "openai"
3
  options {
4
    model "gpt-5-mini"
5
    api_key env.OPENAI_API_KEY
6
    // Finish reason deny list will allow all finish reasons except length
7
    finish_reason_deny_list ["length"]
8
  }
9
}

Safety settings to apply to the request. You can stack different safety settings with a new safetySettings header for each one. See the Google Vertex API Request Docs for more information on what safety settings can be set.

1
client<llm> MyClient {
2
  provider vertex-ai
3
  options {
4
    model gemini-2.5-pro
5
    project_id my-project-id
6
    location us-central1
7
8
    safetySettings {
9
      category HARM_CATEGORY_HATE_SPEECH
10
      threshold BLOCK_LOW_AND_ABOVE
11
      method SEVERITY
12
    }
13
  }
14
}

Generation configurations to apply to the request. See the Google Vertex API Request Docs for more information on what properties can be set.

1
client<llm> MyClient {
2
  provider vertex-ai
3
  options {
4
    model gemini-2.5-pro
5
    project_id my-project-id
6
    location us-central1
7
8
    generationConfig {
9
      maxOutputTokens 100
10
      temperature 1
11
    }
12
  }
13
}