Vertex AI adapter

[JPFrancoia]

Hi all, I would like to give this adapter to the community. Here is some context:
Google provides the Gemini developer API, which I believe most people are familiar with. This API requires an API key. There is an official adapter for this API (the gemini one). However people might not be able to use it in an enterprise setting, because of licensing, compliance, security, etc. For example, if a team works with a GCP project, you can't really create an API key per person (well you could, but then you must ensure that person A can't see person B's API key). You also can't create just one common API key, because then you can't track usage per person.

Google's answer to these problems is to use Vertex AI. They have a page explaining the difference between Gemini Developer API and Vertex AI. With Vertex AI, users can login with their user credentials, no need for an API key.

The two APIs are actually very similar, so the vertex AI adapter is largely inspired from the gemini one.

local log = require("codecompanion.utils.log")
local openai = require("codecompanion.adapters.openai")

---@class Gemini.Adapter: CodeCompanion.Adapter
return {
  name = "vertex",
  formatted_name = "Vertex AI",
  roles = {
    llm = "assistant",
    user = "user",
  },
  opts = {
    stream = true,
    tools = true,
  },
  features = {
    text = true,
    tokens = true,
    vision = true,
  },
  -- Availability of models: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations
  -- url = "https://${region}-aiplatform.googleapis.com/v1/projects/${project_id}/locations/${region}/endpoints/openapi/chat/completions",
  url = "https://aiplatform.googleapis.com/v1/projects/${project_id}/locations/global/endpoints/openapi/chat/completions",
  env = {
    project_id = "YOUR_PROJECT_ID",
    api_key = "VERTEX_API_KEY",
  },
  headers = {
    Authorization = "Bearer ${api_key}",
    ["Content-Type"] = "application/json",
  },
  handlers = {
    --- Use the OpenAI adapter for the bulk of the work
    setup = function(self)
      return openai.handlers.setup(self)
    end,
    tokens = function(self, data)
      return openai.handlers.tokens(self, data)
    end,
    form_parameters = function(self, params, messages)
      return openai.handlers.form_parameters(self, params, messages)
    end,
    form_tools = function(self, tools)
      return openai.handlers.form_tools(self, tools)
    end,
    form_messages = function(self, messages)
      return openai.handlers.form_messages(self, messages)
    end,
    chat_output = function(self, data, tools)
      return openai.handlers.chat_output(self, data, tools)
    end,
    tools = {
      format_tool_calls = function(self, tools)
        return openai.handlers.tools.format_tool_calls(self, tools)
      end,
      output_response = function(self, tool_call, output)
        return openai.handlers.tools.output_response(self, tool_call, output)
      end,
    },
    inline_output = function(self, data, context)
      return openai.handlers.inline_output(self, data, context)
    end,
    on_exit = function(self, data)
      return openai.handlers.on_exit(self, data)
    end,
  },
  schema = {
    ---@type CodeCompanion.Schema
    model = {
      order = 1,
      mapping = "parameters",
      type = "enum",
      desc = "The model that will complete your prompt. See https://ai.google.dev/gemini-api/docs/models/gemini#model-variations for additional details and options.",
      default = "google/gemini-2.0-flash",
      choices = {
        ["google/gemini-2.5-pro-preview-06-05"] = { opts = { can_reason = true, has_vision = true } },
        ["google/gemini-2.5-flash-preview-05-20"] = { opts = { can_reason = true, has_vision = true } },
        ["google/gemini-2.0-flash"] = { opts = { has_vision = true } },
        ["google/gemini-2.0-flash-lite"] = { opts = { has_vision = true } },
        ["google/gemini-1.5-pro"] = { opts = { has_vision = true } },
        ["google/gemini-1.5-flash"] = { opts = { has_vision = true } },
      },
    },
    ---@type CodeCompanion.Schema
    max_tokens = {
      order = 2,
      mapping = "parameters",
      type = "integer",
      optional = true,
      default = nil,
      desc = "The maximum number of tokens to include in a response candidate. Note: The default value varies by model",
      validate = function(n)
        return n > 0, "Must be greater than 0"
      end,
    },
    ---@type CodeCompanion.Schema
    temperature = {
      order = 3,
      mapping = "parameters",
      type = "number",
      optional = true,
      default = nil,
      desc = "Controls the randomness of the output.",
      validate = function(n)
        return n >= 0 and n <= 2, "Must be between 0 and 2"
      end,
    },
    ---@type CodeCompanion.Schema
    top_p = {
      order = 4,
      mapping = "parameters",
      type = "integer",
      optional = true,
      default = nil,
      desc = "The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability.",
      validate = function(n)
        return n > 0, "Must be greater than 0"
      end,
    },
    ---@type CodeCompanion.Schema
    reasoning_effort = {
      order = 5,
      mapping = "parameters",
      type = "string",
      optional = true,
      condition = function(self)
        local model = self.schema.model.default
        if type(model) == "function" then
          model = model()
        end
        if self.schema.model.choices[model] and self.schema.model.choices[model].opts then
          return self.schema.model.choices[model].opts.can_reason
        end
      end,
      default = "medium",
      desc = "Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.",
      choices = {
        "high",
        "medium",
        "low",
        "none",
      },
    },
  },
}

Configuration example:

    {
        "olimorris/codecompanion.nvim",
        dependencies = {
            "nvim-lua/plenary.nvim", "nvim-treesitter/nvim-treesitter",
            "j-hui/fidget.nvim"
        },
        opts = {
            adapters = {
                copilot = function()
                    return require("codecompanion.adapters").extend("copilot", {
                        schema = {model = {default = "claude-sonnet-4"}}
                    })
                end,

                vertex = function()
                    return require("codecompanion.adapters").extend("vertex", {
                    env = {
                        project_id = "project_name_here",
                        api_key = "cmd: gcloud auth application-default print-access-token",
                    },
                    schema = {model = {default = "google/gemini-2.5-pro-preview-06-05"}}
                })
                end
            },
            strategies = {
                chat = {adapter = "vertex"},
                inline = {adapter = "vertex"},
            },
-- truncated

I also found out a few things:

• Model availability depends on region. See here to know which model is available in which region: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations
• There is a global endpoint, and there are regional endpoints. See here for explanations

The global endpoint is formatted like this:

https://aiplatform.googleapis.com/v1/projects/${project_id}/locations/global/endpoints/openapi/chat/completions

The regional endpoints are formatted like this:

https://${region}-aiplatform.googleapis.com/v1/projects/${project_id}/locations/${region}/endpoints/openapi/chat/completions

I hope this saves someone else's time, cheers!

[jinzhongjia]

I think this might be merged into codecompanion as pr?

[olimorris]

Nope as per #800

[olimorris]

Love this @JPFrancoia and thanks for sharing!

[lyonsun]

Hi, I have a stupid question. I followed the exact instruction above, saved the adapter code to .config/nvim/lua/codecompanion/adapters/vertex/init.lua, and changed project_name_here in the config file to my GCP project id, but I am still getting this error:

[ERROR] 2025-06-16 16:27:30
Error: [{
  "error": {
    "code": 401,
    "message": "Request is missing required authentication credential. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "CREDENTIALS_MISSING",
        "domain": "googleapis.com",
        "metadata": {
          "method": "google.cloud.aiplatform.v1.PredictionService.ChatCompletions",
          "service": "aiplatform.googleapis.com"
        }
      }
    ]
  }
}
]

I am assuming the cmd: gcloud auth application-default print-access-token line is not doing what it supposes to, can you help?

[JPFrancoia]

Hey, have you tried running gcloud auth application-default print-access-token in your terminal? Are you getting an access token back? If not, start there

[lyonsun]

Yeah, that worked fine. I got it working finally by replacing the google prefix in the model choices array with vertex_ai:

      choices = {
        ["vertex_ai/gemini-2.5-pro-preview-06-05"] = { opts = { can_reason = true, has_vision = true } },
        ["vertex_ai/gemini-2.5-flash-preview-05-20"] = { opts = { can_reason = true, has_vision = true } },
        ["vertex_ai/gemini-2.0-flash"] = { opts = { has_vision = true } },
        ["vertex_ai/gemini-2.0-flash-lite"] = { opts = { has_vision = true } },
        ["vertex_ai/gemini-1.5-pro"] = { opts = { has_vision = true } },
        ["vertex_ai/gemini-1.5-flash"] = { opts = { has_vision = true } },
      },

[JPFrancoia]

Interesting, and good to know. I had to add the google/ in front of the model name (compared to the gemini adapter) to get it working. Glad you managed anyway!

[fredrikaverpil]

This works for the regional URL! 🎉

Below, I'm enabling both the built in gemini adapter and a new vertex adapter. The latter builds off the built-in gemini adapter.

opts = {
  adapters = {
    vertex = function()
      return require("codecompanion.adapters").extend("gemini", {
        url = "https://${location}-aiplatform.googleapis.com/v1/projects/${project_id}/locations/${location}/endpoints/openapi/chat/completions",
        env = {
          project_id = os.getenv("GOOGLE_CLOUD_PROJECT"),
          location = os.getenv("GOOGLE_CLOUD_LOCATION"),
          api_key = "cmd: gcloud auth application-default print-access-token",
        },
        schema = {
          model = {
            default = "google/gemini-2.5-pro",
          },
	      choices = {
	        ["google/gemini-2.5-pro"] = { opts = { can_reason = true, has_vision = true } },
	        ["google/gemini-2.5-flash"] = { opts = { can_reason = true, has_vision = true } },
	      },
        },
      })
    end,

    gemini = function()
      return require("codecompanion.adapters").extend("gemini", {
        env = {
          api_key = "API KEY HERE",
        },
        schema = {
          model = {
            default = "gemini-2.5-pro",
          },
	      choices = {
	        ["gemini-2.5-pro"] = { opts = { can_reason = true, has_vision = true } },
	        ["gemini-2.5-flash"] = { opts = { can_reason = true, has_vision = true } },
	      },
        },
      })
    end,
  },
}

I'm not sure what's up with the vertex_ai prefix, but this Vertex/OpenAI API documentation shows python examples of using the google prefix, which works for me.

[lyonsun]

@fredrikaverpil You were right, the prefix didn't matter much, both vertex_ai and google would work (tested this again by calling the API endpoint through Bruno).

It seems my original issue was derived by something else. Not sure if the same happens to you, that error message pops out when trying to switch to a different vertex provider.

[fredrikaverpil]

The example in the original post works for me, but I get this error after a couple of minutes idle time in codecompanion, when using vertex:

Error: [{
  "error": {
    "code": 401,
    "message": "Request is missing required authentication credential. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "CREDENTIALS_MISSING",
        "domain": "googleapis.com",
        "metadata": {
          "method": "google.cloud.aiplatform.v1.PredictionService.ChatCompletions",
          "service": "aiplatform.googleapis.com"
        }
      }
    ]
  }
}
]

Is this something you have also encountered, and any idea to mitigate?
The only workaround I've found is to restart Neovim and start a new conversation...