Google Vertex AI Connector
The Google Vertex AI connector imports activity from an agent deployed on Vertex AI Agent Engine (a reasoning engine) into an ANTS Platform project as traces, without changes to the agent. It is one of the AI Studio connectors.
It reads two sources, which you can turn on separately:
| Source | What it adds |
|---|---|
| Cloud Logging (input/output data) | Log entries for the reasoning engine, with inputs and outputs |
| Cloud Trace (span metadata) | Spans with names and timing |
The connector also lists every reasoning engine in its Google Cloud project and region and adds them to the agent inventory, including those that have never run. See Agent inventory.
Self-hosted deployments need the Vertex connector service
(vertexConnector.enabled: true in the Helm values). It is off by default.
Prerequisites
- A Google Cloud service account with a JSON key, in the project that hosts the reasoning engine.
- These APIs enabled in that project:
- Vertex AI API (
aiplatform.googleapis.com) - Cloud Logging API (
logging.googleapis.com) - Cloud Trace API (
cloudtrace.googleapis.com)
- Vertex AI API (
- In ANTS Platform, write access to AI Studio Connectors (the Owner role has it).
IAM roles
Grant the service account these roles, or equivalent permissions:
| Role | Permission used | Why |
|---|---|---|
roles/aiplatform.viewer | aiplatform.reasoningEngines.get, aiplatform.reasoningEngines.list | Read the agent's display name, and list every reasoning engine for the agent inventory |
roles/logging.viewer | logging.logEntries.list | Read Cloud Logging entries |
roles/cloudtrace.user | cloudtrace.traces.get | Read Cloud Trace spans |
Create the connector
Open AI Studio connectors
Go to Project Settings > Integrations, scroll to AI Studio connectors and add a Google Vertex AI connector.
Enter the details
| Field | Notes |
|---|---|
| Service Account JSON | Paste the full JSON key |
| Reasoning Engine ID | For example 4285195936163954688 |
| Region | For example us-central1 |
| Collection Sources | Cloud Logging (input/output data) and Cloud Trace (span metadata). Both are selected by default. |
| Sync Frequency | Every 5, 15, 30 or 60 minutes |
Save
Create the connector. ANTS Platform reads the agent's display name from Vertex AI to check the credentials and uses it as the connector's display name.
Sync behaviour
- The first sync covers one sync interval back from the time it runs (for example the last 15 minutes). Earlier activity is not imported.
- Later syncs read from the last checkpoint to the current time.
- Logs are filtered to the reasoning engine ID you entered, in the Google Cloud project of the service account.
- See results under View sync logs on the connector row.
Agent inventory
On every sync, the connector lists all Vertex AI reasoning engines in the service account's Google Cloud project and the connector's region, and adds each one to the AI Agent Center. Agents appear before they first run, so the inventory covers every reasoning engine in the project, not only the active ones.
- A reasoning engine found in the inventory that has never sent a trace is marked Not seen running.
- Once the agent runs and its activity is imported, the mark is cleared.
- Inventory runs for every Vertex AI connector in the project. One connector per Google Cloud project and region is enough to list all of its reasoning engines.
Troubleshooting
- Create fails with "Failed to fetch agent name from Vertex AI". Check the
reasoning engine ID and region, that the Vertex AI API is enabled, and that
the service account has
roles/aiplatform.viewer. - Traces have no inputs or outputs. Turn on Cloud Logging and check
roles/logging.viewer. - Traces have no timing detail. Turn on Cloud Trace and check
roles/cloudtrace.user. - Last sync never changes. On self-hosted deployments, check that the Vertex connector service is running.
- Reasoning engines that have not run are missing from the AI Agent
Center. The service account lacks
aiplatform.reasoningEngines.list. The sync log shows the access error.