> ## Documentation Index > Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt > Use this file to discover all available pages before exploring further. # GCP Vertex AI > Discover and monitor Vertex AI Reasoning Engines, models, datasets, and Model Armor guardrails across your Google Cloud project. TrustLens connects to **Google Cloud Vertex AI** to discover and monitor your AI agents deployed as **Reasoning Engines**. In addition to agent discovery, it collects usage metrics, tool call data, and security events from Cloud Monitoring, Cloud Trace, and Cloud Logging. *** ## What TrustLens discovers ### For each Reasoning Engine (agent) | Data | Source | | --------------------------------------------------- | ----------------------------------------------- | | Agent name, description, status | Vertex AI API | | Agent framework (ADK, LangChain, LangGraph, custom) | Vertex AI API (`spec.agentFramework`) | | Tools and instructions | GCS pickle file (requires Cloud Storage access) | | Request count | Cloud Monitoring | | Error count | Cloud Monitoring | | Latency (p50, p95, p99) | Cloud Monitoring | | CPU and memory allocation | Cloud Monitoring | | Tool call breakdown by type | Cloud Trace + Cloud Logging | | Conversations (grouped by trace) | Cloud Logging | | Security events (errors, safety triggers) | Cloud Logging | ### For models and datasets TrustLens also discovers models from the Vertex AI **Model Registry** and managed **Datasets**, including basic metadata, lifecycle status, and labels. ### Tool call categories Tool calls are classified into the following categories based on the tool name: | Category | Tool name patterns | | ---------------- | ----------------------------------------------------------------------- | | Code interpreter | Contains `python`, `code_interpreter`, or `code` + `exec`/`interpreter` | | File search | Contains `file_search` or `file-search` | | Web search | Contains `web_search`, `google_search`, or `web` + `search` | | Image generation | Contains `image_generation` or `image` + `generat` | | Function calls | Everything else | To ensure tool calls appear in the correct category in TrustLens dashboards, name your tools following the patterns above — for example, use `google_search` instead of `search_tool`. *** ## Required GCP APIs Enable all six APIs in your GCP project before creating the integration: | API | Purpose | | --------------------------- | ---------------------------------------------------------------------- | | `aiplatform.googleapis.com` | List and read agents, models, and datasets | | `storage.googleapis.com` | Download agent configuration files from GCS | | `monitoring.googleapis.com` | Read usage metrics (requests, latency, CPU, memory) | | `cloudtrace.googleapis.com` | Read invocation traces for tool call extraction | | `logging.googleapis.com` | Read structured logs for telemetry, conversations, and security events | | `modelarmor.googleapis.com` | Read Model Armor templates and floor settings for guardrails discovery | **Enable all at once:** ```bash theme={null} gcloud services enable \ aiplatform.googleapis.com \ storage.googleapis.com \ monitoring.googleapis.com \ cloudtrace.googleapis.com \ logging.googleapis.com \ modelarmor.googleapis.com \ --project=YOUR_PROJECT_ID ``` **Optional — `cloudasset.googleapis.com`:** TrustLens uses the Cloud Asset Inventory API to accelerate location discovery when scanning multi-region projects (reduces scan time from \~3–5 s to \~1–2 s). If this API is not enabled or the service account does not have `roles/cloudasset.viewer`, the connector automatically falls back to parallel regional probing — discovery still completes successfully but may take slightly longer. To enable: ```bash theme={null} gcloud services enable cloudasset.googleapis.com --project=YOUR_PROJECT_ID # Then grant the viewer role to your service account: gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member="serviceAccount:YOUR_SA_EMAIL" \ --role="roles/cloudasset.viewer" ``` *** ## Required IAM roles The service account provided to TrustLens needs all seven roles: | Role | Purpose | What you lose without it | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `roles/aiplatform.viewer` | List and read agents, models, datasets | No agents will be discovered | | `roles/storage.objectViewer` | Download pickle files from GCS to extract tools and instructions | Tools and instructions will show as unavailable | | `roles/monitoring.viewer` | Read Cloud Monitoring metrics | Usage metrics (request count, latency, CPU, memory) will be unavailable | | `roles/cloudtrace.user` | Read Cloud Trace data for tool call extraction | Tool call breakdown from OpenTelemetry-instrumented agents will be unavailable | | `roles/logging.viewer` | Read Cloud Logging for conversations, tool calls from custom agents, and security events | Conversations and security events will be unavailable; tool call extraction from non-instrumented agents will also be unavailable | | `roles/modelarmor.viewer` | Read Model Armor templates | Guardrail template policies will not appear on agents | | `projects/YOUR_PROJECT/roles/modelArmorFloorReader` *(custom)* | Read the project-level floor setting | Floor setting enforcement status will not appear | All roles are read-only. TrustLens cannot create, modify, or delete any GCP resources. **Why a custom role for the floor setting?** GCP's predefined `roles/modelarmor.viewer` and `roles/modelarmor.admin` do not include `modelarmor.floorSettings.get`. That permission is only in `roles/editor`. Create a minimal custom role to grant it in a least-privilege way: ```bash theme={null} # Create the custom role (requires project Owner) gcloud iam roles create modelArmorFloorReader \ --project=YOUR_PROJECT_ID \ --title="Model Armor Floor Setting Reader" \ --description="Read the project-level Model Armor floor setting" \ --permissions="modelarmor.floorSettings.get,modelarmor.floorSettings.computeEffectiveFloorSetting" # Bind it to your service account gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member="serviceAccount:YOUR_SA_EMAIL" \ --role="projects/YOUR_PROJECT_ID/roles/modelArmorFloorReader" ``` ### Custom role (strict least-privilege) If your policy requires a single custom role instead of predefined roles, the minimum individual permissions needed are: ``` aiplatform.reasoningEngines.list aiplatform.reasoningEngines.get aiplatform.models.list aiplatform.models.get aiplatform.datasets.list aiplatform.datasets.get storage.objects.get storage.objects.list monitoring.timeSeries.list cloudtrace.traces.list cloudtrace.traces.get logging.logEntries.list modelarmor.locations.list modelarmor.locations.get modelarmor.templates.list modelarmor.templates.get modelarmor.floorSettings.get modelarmor.floorSettings.computeEffectiveFloorSetting ``` *** ## Step-by-step setup ```bash theme={null} PROJECT_ID="your-project-id" gcloud iam service-accounts create neuraltrust-trustlens \ --project=$PROJECT_ID \ --display-name="NeuralTrust TrustLens" ``` 1. Go to **IAM & Admin** → **Service Accounts** 2. Click **+ Create Service Account** 3. Name: `neuraltrust-trustlens` (or any name you prefer) 4. Click **Create and continue** 5. Skip role assignment here — you will grant roles in the next step 6. Click **Done** ```bash theme={null} PROJECT_ID="your-project-id" SA_EMAIL="neuraltrust-trustlens@${PROJECT_ID}.iam.gserviceaccount.com" for ROLE in \ roles/aiplatform.viewer \ roles/storage.objectViewer \ roles/monitoring.viewer \ roles/cloudtrace.user \ roles/logging.viewer \ roles/modelarmor.viewer; do gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SA_EMAIL" \ --role="$ROLE" done ``` 1. Go to **IAM & Admin** → **IAM** 2. Click **+ Grant Access** 3. Enter the service account email 4. Add all six roles listed above 5. Click **Save** ```bash theme={null} gcloud iam service-accounts keys create neuraltrust-key.json \ --iam-account="neuraltrust-trustlens@${PROJECT_ID}.iam.gserviceaccount.com" ``` 1. Go to **IAM & Admin** → **Service Accounts** → click your service account 2. Go to the **Keys** tab → **Add key** → **Create new key** 3. Select **JSON** → **Create** 4. The key file downloads automatically Provide the following when creating the GCP integration: | Field | Description | Example | | ------------------------ | ----------------------------------------- | -------------------------------------------- | | **Project ID** | Your GCP project ID | `my-project-123` | | **Service Account JSON** | Contents of the JSON key file from Step 3 | Paste your downloaded JSON key file contents | ### Location configuration TrustLens supports three location modes: Leave the location field empty in the UI, or pass `discover_all: true`. TrustLens probes all known Vertex AI regions and syncs any that contain resources. ```json theme={null} { "project_id": "my-project-123", "discover_all": true } ``` Provide a JSON array of region strings when you know exactly which regions you use. ```json theme={null} { "project_id": "my-project-123", "discover_all": false, "selected_locations": ["us-central1", "europe-west4"] } ``` Provide a single region string. Equivalent to `selected_locations` with one entry. Supported for backwards compatibility. ```json theme={null} { "project_id": "my-project-123", "location": "us-central1" } ``` Do not pass a comma-separated string (e.g. `"us-central1,europe-west4"`) — use `selected_locations` as a JSON array instead. *** ## Tool call extraction — instrumented vs. non-instrumented agents TrustLens extracts tool call data from two sources and merges the results: ### Cloud Trace (OpenTelemetry-instrumented agents) For agents built with **ADK**, **LangChain**, or **LangGraph**, TrustLens reads OpenTelemetry spans from Cloud Trace. These frameworks automatically emit spans with `openinference.span.kind=TOOL` labels, which include the tool name and invocation count. ### Cloud Logging (all agents) TrustLens also scans Cloud Logging for structured log entries containing tool call information in their JSON payload, covering agents that emit logs but not OpenTelemetry traces. ### Availability by framework | Framework | Tool calls available | Source | | --------------------------- | ----------------------------------- | ------------- | | ADK (Agent Development Kit) | Full breakdown | Cloud Trace | | LangChain | Full breakdown | Cloud Trace | | LangGraph | Full breakdown | Cloud Trace | | Custom / cloudpickle | Only if agent emits structured logs | Cloud Logging | Non-instrumented agents will show `total_runs > 0` (from Cloud Monitoring) but all tool call counts at zero if they do not emit structured logs. This is expected behavior. *** ## Model Armor guardrails discovery TrustLens integrates with **Google Cloud Model Armor** to discover and surface your project's AI content safety posture alongside each Vertex AI agent. Model Armor operates at the **project level** — policies (templates) and the floor setting apply to all agents in the project rather than being configured per agent. TrustLens discovers this data and associates it with every agent in the integration so you can assess your safety coverage in one place. ### What is discovered TrustLens reads two categories of Model Armor data: #### Templates Model Armor templates are named policy definitions that apply RAI (Responsible AI) content filters. Each template includes: | Field | Description | | ------------------------------------- | ---------------------------------------------------------------------------- | | `name` | Full resource name: `projects/{project}/locations/{location}/templates/{id}` | | `filterConfig.raiSettings.raiFilters` | List of active RAI filter rules | | Each filter's `filterType` | Content category being filtered (see table below) | | Each filter's `confidenceLevel` | Detection sensitivity threshold | **`filterType` values:** | Value | Content category | | ------------------- | ------------------------- | | `SEXUALLY_EXPLICIT` | Sexually explicit content | | `HATE_SPEECH` | Hate speech | | `HARASSMENT` | Harassment and bullying | | `DANGEROUS_CONTENT` | Dangerous activities | | `VIOLENT` | Violent content | **`confidenceLevel` values (from least to most strict):** | Value | Meaning | | ------------------ | ---------------------------------------------- | | `LOW_AND_ABOVE` | Block low, medium, and high confidence matches | | `MEDIUM_AND_ABOVE` | Block medium and high confidence matches | | `HIGH_AND_ABOVE` | Block only high confidence matches | #### Floor setting The floor setting is a single project-level object that defines the minimum content safety policy enforced across all Model Armor usage in the project, regardless of what individual templates specify: | Field | Description | | ------------------------------- | ------------------------------------------------------ | | `name` | `projects/{project}/locations/{location}/floorSetting` | | `enableFloorSettingEnforcement` | `true` if the floor policy is actively enforced | When `enableFloorSettingEnforcement` is `true`, Model Armor applies the floor policy as a baseline even if a weaker template is attached to a call. TrustLens surfaces this as a project-wide safety control. ### Guardrails object shape All Model Armor data is stored on each agent's `guardrails` field with the following structure: | Field | Type | Description | | --------------- | ------------------- | -------------------------------------------------------- | | `provider` | `"gcp_model_armor"` | Identifies the guardrails source | | `scope` | `"project"` | Policies apply at the project level, not per agent | | `policy_count` | `integer` | Number of distinct templates discovered | | `policies` | `array` | Deduplicated Model Armor template objects | | `floor_setting` | `object` \| `null` | The project floor setting, or `null` if not accessible | | `locations` | `array of strings` | GCP regions where Model Armor data was successfully read | **Example `guardrails` object for a GCP agent:** ```json theme={null} { "provider": "gcp_model_armor", "scope": "project", "policy_count": 2, "policies": [ { "name": "projects/my-project/locations/europe-west1/templates/strict-rai", "filterConfig": { "raiSettings": { "raiFilters": [ { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "LOW_AND_ABOVE" }, { "filterType": "HATE_SPEECH", "confidenceLevel": "MEDIUM_AND_ABOVE" }, { "filterType": "DANGEROUS_CONTENT", "confidenceLevel": "LOW_AND_ABOVE" } ] } } }, { "name": "projects/my-project/locations/europe-west1/templates/moderate-rai", "filterConfig": { "raiSettings": { "raiFilters": [ { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "HIGH_AND_ABOVE" } ] } } } ], "floor_setting": { "name": "projects/my-project/locations/europe-west1/floorSetting", "enableFloorSettingEnforcement": true }, "locations": ["europe-west1"] } ``` ### Partial access behavior TrustLens reads templates and the floor setting **independently**. If your service account has `roles/modelarmor.viewer` but not the floor setting custom role, templates will still appear — the floor setting will show as `null`. Similarly, if templates are inaccessible but the floor setting is readable, the floor setting is surfaced on its own. A completely missing guardrails field means neither source was accessible. ### Agents without Model Armor If your GCP project has no Model Armor templates configured, or the service account does not have the required roles, the `guardrails` field will be `null` for all agents in the integration. TrustLens surfaces this as a **missing guardrails** finding. *** ## Feature availability by permission level | Feature | Minimum (`aiplatform.viewer` only) | Full (all roles) | | ---------------------------------------------- | :------------------------------------------------------------------------------------: | :--------------------------------------------------------: | | Agent discovery | Yes | Yes | | Model discovery | Yes | Yes | | Dataset discovery | Yes | Yes | | Security posture assessment | Yes | Yes | | Tools and instructions | No — needs `storage.objectViewer` | Yes | | Usage metrics (requests, latency, CPU, memory) | No — needs `monitoring.viewer` | Yes | | Tool call breakdown | No — needs `cloudtrace.user` + `logging.viewer` | Yes | | Conversation discovery | No — needs `logging.viewer` | Yes | | Security event detection | No — needs `logging.viewer` | Yes | | Model Armor templates (guardrails) | No — needs `modelarmor.viewer` | Yes | | Model Armor floor setting (guardrails) | No — needs custom `modelArmorFloorReader` role | Yes | *** ## Known limitations | Limitation | Details | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Pickle file sharing | If multiple agents share the same GCS pickle file, they will appear to have identical tools and instructions. Each agent should have its own unique pickle file. | | Non-instrumented agents | Custom cloudpickle agents without OpenTelemetry tracing show zero tool call counts unless they emit structured JSON logs. | | Metrics delay | Cloud Monitoring metrics may take up to 24 hours to appear for newly deployed agents. | | No conversation content | TrustLens collects conversation metadata (count, errors) but not message content. | | Location-specific discovery | Agents, models, and datasets in a region that is not configured will not be discovered. Use `discover_all: true` or include the region in `selected_locations` to avoid missing resources. | *** ## Security considerations * The service account key should be stored securely. Rotate it regularly. * All IAM roles are read-only — TrustLens cannot modify or delete GCP resources. * TrustLens encrypts the service account JSON at rest. * For keyless authentication, Workload Identity Federation can be used in environments where storing a service account key is not permitted. Contact support for assistance. *** ## Troubleshooting * Verify `roles/aiplatform.viewer` is granted at the project level. * Confirm your agents are deployed in the configured region. If using auto-discovery, set `discover_all: true` rather than specifying individual regions. * Enable the `aiplatform.googleapis.com` API in the project. * Verify `roles/storage.objectViewer` is granted at the project level (not just on specific buckets). * Confirm the agent has a pickle file URI in `spec.packageSpec.pickleObjectGcsUri`. * Verify `roles/monitoring.viewer` is granted. * Enable the `monitoring.googleapis.com` API. * Metrics may take up to 24 hours to appear for new agents. * Check whether the agent is built with ADK, LangChain, or LangGraph (instrumented). Custom cloudpickle agents require structured JSON log emission for tool call data. * Verify `roles/cloudtrace.user` and `roles/logging.viewer` are granted. * Enable `cloudtrace.googleapis.com` and `logging.googleapis.com` APIs. * Verify `roles/logging.viewer` is granted. * Enable the `logging.googleapis.com` API. * Cloud Logging entries may take a few minutes to appear after agent invocations. Multiple agents are likely sharing the same GCS pickle file. Each agent needs its own unique pickle file to show distinct configurations. * Enable the `modelarmor.googleapis.com` API: `gcloud services enable modelarmor.googleapis.com --project=YOUR_PROJECT_ID` * Grant `roles/modelarmor.viewer` to the service account: `gcloud projects add-iam-policy-binding YOUR_PROJECT_ID --member="serviceAccount:YOUR_SA_EMAIL" --role="roles/modelarmor.viewer"` * Verify at least one Model Armor template exists in the GCP Console under **Model Armor** in the regions you have configured. * IAM changes can take 1–2 minutes to propagate. Trigger a resync from the integration settings page after granting permissions. The floor setting requires `modelarmor.floorSettings.get`, which is not included in `roles/modelarmor.viewer`. Create and bind the `modelArmorFloorReader` custom role using the commands in the **Required IAM roles** section above.