Create and deploy an agent with Agent CLI and Agent Identity

This guide shows you how to create and deploy an agent in Agent Runtime on Gemini Enterprise Agent Platform with Agent Identity enabled.

Agent Identity assigns a secure SPIFFE identity to your deployed agent. The agent uses this identity to authenticate to Cloud de Confiance by S3NS services and retrieve credentials from the Agent Identity auth manager.

Before you begin

  1. Enable the Agent Identity API, Agent Platform API, Agent Registry API, and App Hub API APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  2. Ensure you have the Agent Platform User (roles/aiplatform.user) role on your project.

Create and deploy the agent

Create a sample agent using google-agents-cli and deploy it with Agent Identity:

  1. Install uv, and then run the google-agents-cli setup:

    pip install uv
uvx google-agents-cli setup

  2. Create an agent project using the prototype template:

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    Replace AGENT_PROJECT with the name for your new agent project directory (for example, maps-agent).

    This command generates the following project directory structure:

    AGENT_PROJECT/
├── app/                       # Core agent code
│   ├── agent.py               # Main agent logic
│   ├── fast_api_app.py        # Client application logic
│   └── app_utils/             # App utilities and helpers
├── tests/                     # Unit and integration tests
├── GEMINI.md                  # Development guide
└── pyproject.toml             # Project dependencies

  3. Rename the default application folder (app) to match your agent name (AGENT_NAME, for example, maps_agent). Agent names must be a valid Python identifier: they must start with a letter, and contain only letters, numbers, and underscores.

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. Update your agent.py configuration file to reflect the new name:

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  5. Choose a model to use, based on its regional availability. Update the value for MODEL in agent.py to match your chosen model.

    Workaround for models that are only available in the global region

    To use a model that's only available in the global region, you must modify agent.py so that your agent can access it.

    1. Add the following imports:

      from functools import cached_property
from google.genai import Client

    2. Add the following subclass after the imports:

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. Find the following code:

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      Change it to reference the new subclass:

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

  6. Enable Agent Identity by creating a config file:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  7. Create a requirements.txt file for the deployment dependencies:

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

  8. Verify the project directory structure:

    AGENT_PROJECT/
├── AGENT_NAME/                 # Agent application folder
│   ├── .agent_engine_config.json # Agent Identity configuration
│   ├── agent.py                  # Main agent logic
│   ├── fast_api_app.py           # Client application logic
│   ├── requirements.txt          # Deployment dependencies
│   └── app_utils/                # App helpers
├── tests/                        # Tests
├── GEMINI.md                     # Development guide
└── pyproject.toml                # Project dependencies

  9. Test your agent locally:

    uv run adk web . --port 8501 --reload_agents

    To validate your agent, do the following:

    1. Go to http://localhost:8501. Alternatively, if you're using Cloud Shell, click the link provided by the web server output.

    2. In the chat interface, send a test prompt to verify the response.

  10. Terminate the server with CTRL+C.

  11. Deploy your agent to Cloud de Confiance:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Replace the following:

    • PROJECT_ID: Your Cloud de Confiance project ID.

    • LOCATION: The supported region where you want to deploy the agent (for example, us-west1).

    The deployment can take a few minutes to complete. After it finishes, the CLI outputs a confirmation message and a link to your agent's playground in the Cloud de Confiance console.

  12. Retrieve your agent's SPIFFE ID (Agent Identity):

    1. In the Cloud de Confiance console, go to the Deployments page.

      Go to Deployments

    2. To copy your agent's SPIFFE ID to the clipboard, find the row that your deployed agent is in, and in the Identity column of that row click Copy to clipboard. The identity looks similar to the following: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

What's next