> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plerion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scan Vertex AI Agent Engine agents deployed from a staging bucket

> Share the Cloud Storage staging bucket that holds a Vertex AI Agent Engine agent's code so Plerion can scan it for vulnerabilities, secrets and an SBOM, and read the agent's tools and prompt.

With **[GCP workload scanning](https://docs.plerion.com/guides/integrations/gcp/workload-scanning/overview.md)**, Plerion scans Vertex AI Agent Engine agents when the **Vertex AI Agent Engine agents** workload type is on. Turn it on or off with the other workload types in the integration's Capabilities panel. New integrations have it on. An integration set up before this workload type existed has it off until you turn it on.

How you deployed an agent decides what you need to do:

* An agent deployed from a **container image** in Artifact Registry is scanned with no extra setup.
* An agent deployed from a **staging bucket**, the Vertex AI SDK's default, keeps its code in a Cloud Storage bucket in your organization. Plerion reads it only from buckets you share with it, so no other bucket is readable.
* An agent Google builds from inline source, a Dockerfile, a git repository or Developer Connect can't be scanned. See [Coverage](https://docs.plerion.com/guides/integrations/gcp/workload-scanning/coverage.md#vertex-ai-agent-engine-agents).

Until Plerion can read the bucket, the agent's page says it was not scanned and why. When the bucket is all that is missing, the message names it.

The workload type covers vulnerabilities, the software bill of materials (SBOM) and sensitive data. Vertex AI Agent Engine scanning also reads each agent's tools and prompt, to show what the agent can do.

***

## Before you start

The access that reads staging buckets comes with version v11 of the onboarding script and Terraform template, which Plerion calls the access command. Re-running it needs the same Organization Admin access as onboarding. Turning the **Vertex AI Agent Engine agents** type on for an existing integration shows the **Update Plerion access in Google Cloud** warning. After you save, copy the updated command from the integration's **Plerion access** panel and re-run it, or re-apply the Terraform template with the type in `workload_types`. See [Re-running the access command](https://docs.plerion.com/guides/integrations/gcp/workload-scanning/managing-workload-scanning.md#re-running-the-access-command).

Re-running it creates the **agent code scanner**, a service account named `plerion-scanner-agent@<scanning-project>.iam.gserviceaccount.com`, in the scanning project onboarding created for Plerion's scan jobs, and the role that lets it read tagged buckets. It also creates the `PlerionAccess` tag key at your organization, with its `Granted` value, if they don't exist yet. Until you re-run it, agents deployed from a staging bucket aren't scanned and say so.

***

## Share a staging bucket with Plerion

Do this once for each bucket that holds agent code. The agent's page in Plerion names the bucket in its "not scanned" notice. It is the `staging_bucket` you passed to `vertexai.init()` or to the agent's deployment.

Attach the tag `PlerionAccess: Granted` to the bucket with `gcloud`, for example in Cloud Shell:

```bash theme={"system"}
gcloud resource-manager tags bindings create \
  --tag-value=<organization-id>/PlerionAccess/Granted \
  --parent=//storage.googleapis.com/projects/_/buckets/<bucket> \
  --location=<bucket-location>
```

Find your organization ID with `gcloud organizations list`, and the bucket's location with `gcloud storage buckets describe gs://<bucket> --format='value(location)'`. Give the location in lower case, such as `us-central1` or `us`. Google Cloud documents tagging buckets with `gcloud` and the API. See [Tags for buckets](https://cloud.google.com/storage/docs/tags-and-labels) in the Cloud Storage docs.

To attach the tag, you need the Tag User role (`roles/resourcemanager.tagUser`) on the `Granted` tag value (or on the `PlerionAccess` key or the organization above it), and the `storage.buckets.createTagBinding` permission on the bucket. The Storage Admin role (`roles/storage.admin`) has that permission.

The agent is scanned on the integration's next workload scan. Once it is, the "not scanned" notice on the agent's page is replaced by the results.

> [!WARNING]
>
> Sharing a bucket lets Plerion read every object in it, not only agent code. Plerion reads only the files an agent's deployment names, but its access covers the whole bucket. To limit what Plerion can read, stage agents in a bucket used only for agent staging, and share that one.

### Tags pass down from folder to project to bucket

Google Cloud passes tags down the resource hierarchy. A bucket in a project or folder tagged `PlerionAccess: Granted` is shared too.

| You tag | What Plerion can read |
| - | - |
| A bucket | That bucket only |
| A project | Every bucket in the project, including buckets created later |
| A folder | Every bucket in every project under the folder, including buckets and projects created later |

Tag the staging bucket itself. Tag a project or folder only if you want every bucket under it, now and later, to be readable.

`Denied` and `Granted` are two values of the same `PlerionAccess` key, and a resource holds one value of a key. A project tagged `Denied` has its custom images excluded from scanning. Changing that project to `Granted` shares its buckets and also turns custom image scanning back on for it. See [Excluding a project's custom images](https://docs.plerion.com/guides/integrations/gcp/overview.md#excluding-a-projects-custom-images).

### If you used accept\_existing\_granted

Versions v11 and v12 of the access command held back the read grant when the `PlerionAccess: Granted` value already existed, until you passed `--accept-existing-granted` to the script or set `accept_existing_granted = true` in Terraform. From v13 the grant is made either way. The flag and the variable are ignored, and you can remove them. The Terraform template still declares the variable, so an older settings file still applies.

***

## What Plerion reads and what it sends

The agent code scanner is a service account in your own scanning project. It holds one role, `PlerionWorkloadScanAgentCodeRead`, with one permission, `storage.objects.get`. The role is bound at your organization with an IAM condition that limits it to resources tagged `PlerionAccess: Granted`. It can't list a bucket, so it can only fetch objects it already knows the names of. See [Access and permissions](https://docs.plerion.com/guides/integrations/gcp/workload-scanning/access-and-permissions.md#plerionworkloadscanagentcoderead).

Plerion operates the scan: it creates the scan job in your scanning project and chooses the image the job runs. The job runs as the agent code scanner and reads two files for each agent, `requirements.txt` and the dependency archive (`dependencies.tar.gz`). It never opens the agent's pickle file. The files are read and scanned inside your organization and are not copied to Plerion.

Plerion receives:

* Vulnerability findings and the package list (SBOM).
* Secret findings, if **Sensitive data** is on for the integration.
* The tools the code defines: each tool's name, description, and the file and line that define it.
* The agent's prompt text, for a short time. It is uploaded to a temporary Plerion bucket, sent to a model to write a one-sentence summary of the agent's purpose, then deleted. Plerion keeps only the summary and a hash of the prompt. The prompt is sent again only when it changes.

An agent deployed from a container image is scanned by a job in the same scanning project. It runs as the artifact scanner service account, which pulls the image from Artifact Registry. Tools and the prompt are read from the files the image adds, and the same results are sent to Plerion.

***

## Tools and prompt

Plerion reads the tools an agent's code defines and shows them on the agent's **Tools** tab. This works for agents written with LangChain, LangGraph, Strands or the Google Agent Development Kit (ADK). For an ADK agent written in Python, Plerion lists the functions and agents in its `tools` list and ADK's own tools, such as Google Search. An agent with sub-agents also lists `transfer_to_agent`, the tool ADK adds so the agent can hand a question on. Plerion doesn't list tools from toolsets, such as MCP, OpenAPI or BigQuery, from custom `BaseTool` classes, or from agents defined in YAML files. Plerion doesn't read tools for agents built with other frameworks, such as CrewAI or AG2, and the **Tools** tab says so. Plerion reads the code as text and does not run it, so a tool the agent builds while it runs is not listed.

Plerion also reads the agent's prompt and writes a one-sentence summary of what the agent is for, including for ADK agents. An agent whose code Plerion can't read gets a summary written from its name and description instead. Plerion writes these only for projects that have workload scanning on.

***

## Why an agent was not scanned

The agent's page shows one of these messages and links here.

| Message on the agent | What to do |
| - | - |
| To scan this agent, add the tag PlerionAccess: Granted to Cloud Storage bucket … | Follow [Share a staging bucket with Plerion](#share-a-staging-bucket-with-plerion) for that bucket. If the bucket is already tagged, re-run the access command, as in [Before you start](#before-you-start). Versions before v13 could hold back the read grant. |
| To scan this agent, re-run the Plerion onboarding command for your organization. … | The agent code scanner doesn't exist yet. Re-run the access command with the **Vertex AI Agent Engine agents** type on, as in [Before you start](#before-you-start), then share the bucket. |
| Plerion can't scan this agent because gs\://…, which held its code, no longer exists. | The staging files the agent was deployed from have been deleted or replaced. Redeploy the agent. |

For agents Plerion can't scan at all, or scans only in part, see [Coverage](https://docs.plerion.com/guides/integrations/gcp/workload-scanning/coverage.md#why-an-agent-engine-agent-was-not-scanned).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.