Google Vertex AI
Run Coeffection's AI in your own Google Cloud project. Coeffection makes a service account for your workspace, and you give that account one role in your project. Coeffection uses it to call Gemini on Google Vertex AI for your workspace. This guide covers setup, what the grant lets Coeffection do, and what to do when something goes wrong.
Who this is for#
Google Vertex AI is part of HIPAA mode. HIPAA mode is turned on by Coeffection on request. Contact us to discuss your requirements. Once it is on, every AI feature in the workspace runs in your own cloud account: Google Vertex AI in your Google Cloud project, Amazon Bedrock in your AWS account, or both. Anthropic, OpenAI and the Gemini API are turned off.
The BAA with Google Cloud is yours. You sign it with Google, for your own organization. Coeffection does not sign a BAA with Google for you, and it never runs Gemini on its own Google account for your workspace. You pay Google Cloud directly for what the AI uses.
If the AI Assistant page has no Google Vertex AI card, HIPAA mode is not on for your workspace. Contact Coeffection support.
What runs on Google Vertex AI#
Google Vertex AI runs Gemini models. Which AI features use it depends on which clouds you connect and on the model you pick for each task. This table shows where each task starts when both Amazon Bedrock and Google Vertex AI are connected and nobody has picked a model.
| Task | Starts on |
|---|---|
| Grace | Amazon Bedrock |
| Daily brief | Google Vertex AI |
| Field brief | Google Vertex AI |
| Lead enrich | Google Vertex AI |
| Clay discovery | Amazon Bedrock |
| Web search | Off for now |
- With one cloud connected, each task runs on that cloud, if the cloud has a model for it.
- You can pick a model on either cloud for a task. See Choose models for each task.
- Lead enrich covers Lead Inbox AI research, which runs on Google Vertex AI without live web search, and enrichment that writes into your records, which is off. See Live web search is off.
- If a call to a cloud fails, the feature says so. Coeffection does not send the request to the other cloud, or to another provider, instead.
Before you start#
- HIPAA mode is on for your workspace.
- A Google Cloud project you control, with billing turned on. AI requests run in that project, so your own agreement with Google Cloud (the Google Cloud BAA) is the one that applies to them. Google decides which products that agreement covers. Check Google Cloud's HIPAA page for Vertex AI and for the models you use. Coeffection can't do this for you.
- A Google Cloud user who can turn on APIs and change IAM roles in that project, such as an Owner.
- A Coeffection role with the permission to manage Google Vertex AI (
integrations_vertex:manage). The Owner and Admin roles have it. You can give it to another role on the Roles page. Without it you can't change the connection or see the service account email.
Set it up#
Go to Admin Settings → Integrations → AI Assistant and open the Settings tab. While HIPAA mode is on, a banner reads “HIPAA mode: AI runs only in your AWS or Google Cloud account.” A setup checklist follows it: Connect Amazon Bedrock, Connect Google Vertex AI and Pick models. You need at least one cloud. The Google Vertex AI card sits below the Amazon Bedrock card. It holds four steps: your project, the setup command, the BAA and the test.
Step 1 of 4: Enter your project and region
The first part of the card is headed Your Google Cloud project. Choose the Google Cloud project and region where Vertex AI runs.
- Enter the project ID in Google Cloud project ID. The field says “The project ID, for example acme-health-prod. Not the project name or number.” In the Google Cloud console, open the project picker at the top of the page. The ID is shown beside the project's name.
- A project ID has 6 to 30 lowercase letters, digits and hyphens. It starts with a letter and does not end with a hyphen. The Set up button stays disabled until the ID fits.
- Choose a Region. The menu lists the regions below, each with its name and code. It starts on Global. The card says “Global lets Google process a request in any location. To choose a United States region instead, pick one from the list. Not every model is available in every region.”
| Region | Code |
|---|---|
| Global (Google picks the location) | global |
| US Central (Iowa) | us-central1 |
| US East (South Carolina) | us-east1 |
| US East (N. Virginia) | us-east4 |
| US West (Oregon) | us-west1 |
Select Set up. Coeffection makes a service account for your workspace. While it does, the card says “Preparing your Coeffection service account…” Running setup again never makes a second service account. If the setup was cut off, the card offers Resume setup. If a request failed, the button reads Retry.
Not every model is offered in every region. Coeffection's default Gemini model is available on Google's global endpoint. In a United States region it may not be, and then you pick a model that region offers for each task (see Choose models for each task). Check that the model you want is available in the region you choose.
Step 2 of 4: Run the setup command
When the service account is ready, the card shows a block headed Setup command. It lists your Project ID and the Service account email, and holds the command with both filled in. The card says “Run this in Google Cloud Shell. It turns on the Vertex AI API in your project and gives Coeffection's service account the Vertex AI User role.”
- Select Copy. If your browser blocks it, the card says “Copy failed. Please select the command and copy it by hand.”
- Select Open Cloud Shell. Google Cloud Shell opens in a new tab. The link is a plain one, with nothing from Coeffection in it. Sign in with a Google Cloud user who can turn on APIs and change IAM roles in your project.
- Paste the command and press Enter. If Cloud Shell asks you to authorize it, allow it.
- Go back to Coeffection.
This is the command with its two placeholders. The card shows it with your values in place of PROJECT_ID and SERVICE_ACCOUNT_EMAIL.
gcloud services enable aiplatform.googleapis.com --project='PROJECT_ID' && \
gcloud projects add-iam-policy-binding 'PROJECT_ID' \
--member='serviceAccount:SERVICE_ACCOUNT_EMAIL' \
--role='roles/aiplatform.user' --condition=None- The first line turns on the Vertex AI API in your project. The second gives your workspace's service account the role
roles/aiplatform.user(Vertex AI User) in your project. - Coeffection checks the project ID and the email before it builds the command, and puts each value in single quotes, so a value can't change what the command does. If a value fails the check, the card shows no command.
--condition=Nonestops gcloud asking which condition to use when your project already has conditional role bindings.- The service account email changes only when you rotate the service account. Run the command again after a rotation.
Prefer the Google Cloud console? You can do the same two things by hand. The card lists these steps too.
- Open the Google Cloud console and choose your project.
- Turn on the Vertex AI API: in APIs & Services, find the Vertex AI API and select Enable.
- Go to IAM and choose “Grant access”.
- Paste the service account email shown on the card into “New principals”.
- Choose the role “Vertex AI User” and save.
- Go back to Coeffection.
Step 3 of 4: Confirm the BAA
The last part of the card is headed Business Associate Agreement. Your organization signs the BAA with Google Cloud itself. The card links to Google Cloud's HIPAA page, where you can read how.
- Tick “Our organization has a BAA with Google Cloud” and select Save. The Save button stays disabled until the box is ticked.
- Coeffection records that you said so, and when. It does not check your agreement with Google. The card then says “BAA acknowledged on” and the date.
- The test does not run until the BAA is confirmed. It says “Confirm that your organization has a BAA with Google Cloud, then test the connection.”
- The BAA stays recorded when you rotate the service account or change the region. Changing the project, and Disconnect, clear it.
Step 4 of 4: Test the connection
Select Test connection. Coeffection makes a short-lived access token for your workspace's service account, sends one small test request to Gemini on Google Vertex AI in your project and region, and checks which models the region offers. The request is a fixed prompt. It holds no customer data. The test takes a few seconds.
- If the test passes, it says “Google Vertex AI is connected.” The card then shows a line like
Connected · acme-health-prod · global · last tested 5 minutes ago. Use Re-test whenever you want to check again. - If the test fails, the card shows why. For some failures it adds a link to the fix. The card also offers Re-test and Disconnect, and keeps the setup command in view. See Troubleshooting.
- A test that fails because Google or Coeffection was briefly busy, or because the network failed, does not turn off a connection that had already passed. The card shows “Last test:” and the reason, and stays connected.
Organization policy: Domain restricted sharing#
This is a known blocker in larger Google Cloud organizations. If the setup command fails, or the test says “Your Google Cloud organization blocks outside service accounts. Ask your Google admin to allow Coeffection, then re-test.”, your organization probably uses the “Domain restricted sharing” policy.
The policy (the constraint is iam.allowedPolicyMemberDomains) lets only people and service accounts from your organization's own domains hold a role in its projects. Coeffection's service account is outside your organization, so Google refuses to give it a role. The command may fail with an error such as “One or more users named in the policy do not belong to a permitted customer, perhaps due to an organization policy.” Google can change that wording.
C0xxxxxxx. It is the customer ID of Coeffection's Google account, not a domain name.What your Google admin needs to do
- Sign in to the Google Cloud console as a user with the Organization Policy Administrator role (
roles/orgpolicy.policyAdmin). - Open IAM & Admin → Organization Policies and select the policy named Domain restricted sharing (
iam.allowedPolicyMemberDomains). - Choose Manage policy. Add Coeffection's Google customer ID to the allowed values. Keep the values that are already there.
- Save. Google can take a few minutes to apply the change.
Your admin can set this for the whole organization, for a folder, or only for the project that runs Vertex AI. Any of them works for Coeffection.
Then come back to Coeffection:
- Run the setup command again, in Cloud Shell, if it failed the first time.
- Select Test connection or Re-test.
What the grant lets Coeffection do#
The setup gives Coeffection one thing in your project: one role for one service account. Coeffection asks for no other role, and for none at the organization or folder level.
Who can use it
- Only the service account Coeffection made for your workspace. Its name starts with
vx-. Its email is in the setup command block of the card. Only people who can manage the connection see it. - Every workspace has its own service account. Google has no External ID to tell workspaces apart, so this is what does: you grant the role to your workspace's account only. Another Coeffection workspace has a different account, so Google refuses it in your project, even if someone types your project ID.
- Coeffection's own broker identity has no role in your project. Its only link to your project is that it can make short-lived access tokens for your workspace's service account.
- No key file is made for your workspace's service account, and you never paste a secret into Coeffection. The project ID and the region are all you give it.
What it is for
- The role is Vertex AI User (
roles/aiplatform.user). It is a Vertex AI role. Coeffection uses it to call Gemini models for your workspace's AI features, in your project and region. - You can see exactly what the role includes in the IAM page of your project, and in Google Cloud's role reference.
- To end Coeffection's access at any time, remove the role from the service account in your project. See Disconnect.
Limits Coeffection adds
- Coeffection uses the endpoint of the region you chose, and only the regions in the table above. The default is Google's global endpoint, where Google may process a request in any location. If you need requests processed in the United States, choose a United States region, and a model that region offers.
- Coeffection makes no promise about where Google processes or stores a request. Check Google Cloud's documentation and your agreement with Google for the location you choose.
- An access token lasts up to an hour. Coeffection makes a new one when it needs one.
- Anthropic, OpenAI and the Gemini API are off in HIPAA mode. While it is on, Gemini models run only through Google Vertex AI, in your project, with no API key.
Choose models for each task#
Below the connection cards, the AI Assistant page has a list headed AI models. It lists each AI task with the model it uses. Each task shows a Default or Chosen badge.
- Each task's list holds the models of every connected cloud. They are grouped under “Amazon Bedrock” and “Google Vertex AI”, and each model is tagged “AWS” or “Google”. A pick saves the cloud and the model together.
- Google Vertex AI lists the Gemini text models your region offers. If there are none, it says “No Gemini models are available in this region.”
- Pick another model for a task, or select Reset to defaults.
- If you disconnect a cloud, the picks on it are kept. The row shows the pick read-only, with a note that ends “Reconnect or pick another.” Meanwhile the task runs on the other cloud, if it is connected.
- A task that is off says “Off on Google Vertex AI until web grounding is confirmed.”
Live web search is off#
For now there is no live web search on Google Vertex AI. Lead Inbox AI research still runs, from the AI model's own knowledge. Each result carries a note that says “No live web search in HIPAA mode. This research comes from the AI model only.” It shows no sources.
- Live web search stays off until Coeffection confirms that Web Grounding for Enterprise is on Google Cloud's list of products covered by its BAA. Coeffection turns it on only after that.
- The web search task is off. Features that write enrichment into your records stay off too. They would write values that came from the model alone.
- Coeffection never falls back to the Gemini API, Anthropic or another web search provider.
Troubleshooting#
When a test fails, the card shows the reason and, for some failures, a link to the fix. AI features show the same words when a request fails. Find the message below.
| Message | What it means | What to do |
|---|---|---|
| “Coeffection's service account can't use Vertex AI in your Google Cloud project. Run the setup command again, then re-test.” | Google refused the request because the service account has no Vertex AI role in your project. The command may not have been run, may have been run in another project, or may have been run for an older service account. The email changes when you rotate. | Select Go to the setup command on the card. Check that the project ID is the project where you ran it, and run the current command again. In IAM, the principal should be your workspace's service account with the role Vertex AI User. Wait a minute, then select Re-test. If it is still refused, read the organization policy section. |
| “The Vertex AI API is off in your Google Cloud project. Run the setup command again, then re-test.” | The Vertex AI API is not turned on in your project. | Run the setup command again. It turns the API on. Or turn on the Vertex AI API in APIs & Services. Then select Re-test. |
| “Billing is off for your Google Cloud project. Turn it on, then re-test.” | Billing is not turned on for the project, and Vertex AI needs it. | Link a billing account to the project in the Google Cloud console, then select Re-test. The card links to Google Cloud billing help. |
| “Your Google Cloud organization blocks outside service accounts. Ask your Google admin to allow Coeffection, then re-test.” | Your organization's Domain restricted sharing policy refuses a service account from outside the organization. | Ask your Google admin to allow Coeffection's Google customer ID. The steps are in the organization policy section, and the card links to them as Read the organization policy steps. Then run the setup command again and select Re-test. |
| “This AI model isn't available in your Google Cloud region. Pick another model, then re-test.” | Google does not serve the model in the region you chose. The message may name the model. | Pick another model for the task. The card links to Go to AI models. Or change the region. Then select Re-test. A message like this never marks a model as retired. |
| “Can't reach Google Cloud. Try again in a moment.” | Coeffection could not reach Google Cloud. The network failed, not your setup. A connection that had already passed a test stays connected. | Wait a moment and try again. |
| “AI is busy, try again.” | Google slowed the request down, or was briefly unavailable, before the answer began. | Wait a minute and try again. If it keeps happening, ask Google for a higher quota for Vertex AI on the Quotas page of your project. |
| “The answer was cut off, try again.” | The answer started and then stopped. | Ask again. |
| “That request is too long for the AI to read. Shorten it or start a new chat, then try again.” | The request is longer than the model can read. | Shorten it, or start a new chat. |
| “Google Vertex AI couldn't accept that request. Try again in a new chat. If it keeps happening, contact support.” | Google refused the request as not valid. The problem is in the request Coeffection sent, not in your Google Cloud setup, and your connection is not marked as broken. | Start a new chat and ask again. If it continues, contact Coeffection support. |
| “AI is temporarily unavailable.” | The problem is on Coeffection's side, not yours. Coeffection is alerted. | Try again in a few minutes. If it continues, contact Coeffection support. |
| “Connect Google Vertex AI to use AI” | Something asked for Google Vertex AI, but there is no working connection. | Finish the four setup steps. |
| “Connect Amazon Bedrock or Google Vertex AI to use AI” | HIPAA mode is on, but neither cloud is connected. | Connect Google Vertex AI with this guide, or Amazon Bedrock with its guide. AI features stay off until one cloud works. |
| “Web research is off in HIPAA mode” | This is by design. Live web search stays off until web grounding is confirmed. | Nothing to fix. |
While you set up and test, you may also see these.
| Message | What it means | What to do |
|---|---|---|
| “That is not a valid project ID: use 6 to 30 lowercase letters, digits and hyphens, starting with a letter and not ending with a hyphen.” | The text is not a project ID. It may be the project name or number. | Copy the project ID from the project picker in the Google Cloud console. |
| “Your Coeffection service account is not ready yet. If setup was interrupted, resume it below.” | The setup was cut off before the service account was ready. | Select Resume setup. |
| “Setup did not finish. AI is temporarily unavailable on Coeffection's side; try again in a few minutes.” | Coeffection could not finish preparing the service account for your workspace. The problem is on Coeffection's side, not in your Google Cloud project, and Coeffection is alerted. Nothing in your project was changed. | Wait a few minutes, then select Retry. If it continues, contact Coeffection support. |
| “The setup command is not available. Reload the page, and contact Coeffection support if it is still missing.” | Coeffection could not build the command for the project it has stored. | Reload the page. If the command is still missing, contact Coeffection support. |
| “Start the Google Vertex AI setup first.” | The setup was cleared, for example by a Disconnect in another tab. | Enter your project ID and region, and select Set up. |
| “Your Google Vertex AI setup changed while this was running. Try again.” | The service account, the project or the region changed while your request ran, for example in another tab. | Reload the page and try again. |
| “Could not save the Google Vertex AI connection. Try again.” | Coeffection could not save your change. | Try again. If it keeps failing, contact Coeffection support. |
| “HIPAA mode is off for this workspace. Turn it on to set up Google Vertex AI.” | Set up, Rotate and Test work only while HIPAA mode is on. | Contact Coeffection support. Only Coeffection can turn HIPAA mode on. |
| “Finish the Google Vertex AI setup, then test the connection.” | A test ran before the service account was ready. No call was made to Google. | Finish steps 1 and 2, then test again. |
| “Confirm that your organization has a BAA with Google Cloud, then test the connection.” | The BAA has not been saved. No call was made to Google. | Tick the box, select Save, then test again. |
| “The connection changed while it was being tested. Test it again.” | The service account, the project or the region changed during the test. The result was not saved. | Select Test connection or Re-test again. |
| “Too many connection tests. Try again in a few minutes.” “Too many tests — try again later” “Too many attempts. Try again later.” | Set up, Rotate and Test are limited for each workspace. | Wait a few minutes, then try again. |
| “Connection testing is unavailable right now. Try again shortly.” “This is unavailable right now. Try again shortly.” | Coeffection could not check the limit, so it did not run the request. | Wait a moment and try again. |
| “Google Vertex AI connection failed. Re-test to check again.” | The last test failed for a reason the card cannot name. | Select Re-test. |
| “Could not reach the server. Check your connection and try again.” | Your browser got no answer from Coeffection. | Check your internet connection and try again. |
Change the project or region#
On a connected card, select Change project or region. The fields open with the saved values. Change them and select Update setup. The service account stays the same.
- A new region needs a new test. The card says “A new region needs a new test. Google Vertex AI is unavailable until the test passes.”
- A new project needs more. The card says “A new project needs the setup command run again, the BAA confirmed again and a new test. Google Vertex AI is unavailable until the test passes.” Run the new command for the new project, confirm the BAA, and test.
- Coeffection does not touch the old project. If you no longer want Coeffection to have access there, remove the role from the service account in that project.
Rotate the service account#
Rotate the service account if its email was shared by mistake, or if your security policy asks for it. Coeffection makes a new service account and retires the current one, and deletes it shortly after. Your project ID, region and BAA record stay. Google Vertex AI stays unavailable until you give the new account its role and the test passes.
- On the connection card, select Rotate service account, then Rotate now. The dialog is headed “Rotate the service account?” and tells you to run the setup command again. Afterwards the card says “You rotated the service account. Run the setup command again for the new account, then test the connection. Google Vertex AI stays unavailable until the test passes.”
- Select Copy and run the new setup command in Cloud Shell, as in step 2. It holds the new email.
- Select Test connection.
- Remove the old IAM binding from your project. See the warning below.
In the Google Cloud console, open IAM, find the old service account (its name starts with vx-, and its email is not the one on the card now) and remove its Vertex AI User role. Or run this in Cloud Shell, with your project ID and the old email:
gcloud projects remove-iam-policy-binding 'PROJECT_ID' \
--member='serviceAccount:OLD_SERVICE_ACCOUNT_EMAIL' \
--role='roles/aiplatform.user' --condition=NoneDisconnect#
On the connection card, select Disconnect, then Yes, disconnect. The dialog is headed “Disconnect Google Vertex AI?” and says “AI features that run on Google Vertex AI stop until you reconnect. Coeffection deletes the service account it created for your workspace. You can also remove its role from your Google Cloud project.”
- Disconnect clears the project ID, the region, the BAA record and the service account from Coeffection, and Coeffection deletes the service account. It does not change your Google Cloud project.
- Remove the role binding for the service account from your project yourself, as under Rotate. A token that was already made keeps working until it expires, up to an hour, unless you remove the binding.
- While HIPAA mode is on and Google Vertex AI is disconnected, a task that Amazon Bedrock can run uses Amazon Bedrock, if it is connected. If no cloud is connected, AI features stay off. Coeffection does not switch to Anthropic, OpenAI or the Gemini API.
- To connect again, start from step 1. You get a new service account, run the setup command again, and confirm the BAA again.
Cost and usage#
You pay Google Cloud directly for Vertex AI. Coeffection does not bill you for it. Coeffection still counts tokens, so your usage caps keep working. Your Google Cloud bill is the number that counts.