Vertex Ai Agents

<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
name: vertex-ai-agents
description: Google Vertex AI Agent Builder patterns for building enterprise AI agents with Gemini. Use when designing agents with OpenAPI tools, data stores, playbooks, multi-agent orchestration, or deploying on Google Cloud.
---

> **Platform Note:** This skill was designed for multi-agent execution. In Codex, treat sub-agent instructions as sequential steps to complete thoroughly within a single agent context.

# Vertex AI Agent Builder

Build enterprise AI agents on Google Cloud using Gemini models with Vertex AI Agent Builder.

## When to Use

- Building agents that connect to enterprise systems via OpenAPI tools
- Grounding agent responses in enterprise data stores (BigQuery, GCS, websites)
- Implementing multi-agent architectures with specialized sub-agents (playbooks)
- Deploying agents with Google Cloud's security and compliance controls
- Integrating with the Google Cloud connector ecosystem (SAP, Salesforce, ServiceNow)

## Core Architecture

```
User Query
  --> Conversational Agent (Gemini)
    --> Playbook Selection (intent routing)
      --> Tool Execution:
        - OpenAPI Tool (Cloud Functions / Cloud Run)
        - Data Store Tool (RAG grounding)
        - Code Interpreter (Python sandbox)
        - Google Search (web grounding)
      --> Response Generation (grounded in tool results)
```

## Patterns

### 1. Agent with OpenAPI Tool (via ADK)

```python
from google.adk.agents import Agent
from google.adk.tools import OpenAPITool

# Define agent with an enterprise API tool
customer_service_agent = Agent(
    model="gemini-2.0-flash",
    name="customer_service",
    instruction="""You are a customer service agent. Use the CRM tool to
    look up customer information and resolve inquiries.""",
    tools=[
        OpenAPITool(
            spec_uri="gs://my-bucket/crm-api-spec.yaml",
            # Or inline spec_dict={"openapi": "3.0.0", ...}
        )
    ],
)
```

### 2. Data Store Grounding (RAG)

```python
from google.cloud import discoveryengine_v1 as discoveryengine

def create_data_store(project_id: str, location: str, data_store_id: str):
    """Create a data store for agent grounding."""
    client = discoveryengine.DataStoreServiceClient()

    data_store = discoveryengine.DataStore(
        display_name="Enterprise Knowledge Base",
        industry_vertical=discoveryengine.IndustryVertical.GENERIC,
        solution_types=[discoveryengine.SolutionType.SOLUTION_TYPE_CHAT],
        content_config=discoveryengine.DataStore.ContentConfig.CONTENT_REQUIRED,
    )

    operation = client.create_data_store(
        parent=f"projects/{project_id}/locations/{location}/collections/default_collection",
        data_store=data_store,
        data_store_id=data_store_id,
    )
    return operation.result()


def ingest_documents(project_id: str, location: str, data_store_id: str, gcs_uri: str):
    """Ingest documents from GCS into the data store."""
    client = discoveryengine.DocumentServiceClient()

    request = discoveryengine.ImportDocumentsRequest(
        parent=f"projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{data_store_id}/branches/default_branch",
        gcs_source=discoveryengine.GcsSource(
            input_uris=[gcs_uri],
            data_schema="content",
        ),
        reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
    )
    operation = client.import_documents(request=request)
    return operation.result()
```

### 3. Function Calling (Parallel)

```python
from google import genai
from google.genai import types

client = genai.Client(vertexai=True, project="my-project", location="us-central1")

# Define tools
tools = [
    types.Tool(function_declarations=[
        types.FunctionDeclaration(
            name="get_customer",
            description="Look up customer details by ID",
            parameters=types.Schema(
                type="OBJECT",
                properties={
                    "customer_id": types.Schema(type="STRING", description="Customer ID"),
                },
                required=["customer_id"],
            ),
        ),
        types.FunctionDeclaration(
            name="get_orders",
            description="Get recent orders for a customer",
            parameters=types.Schema(
                type="OBJECT",
                properties={
                    "customer_id": types.Schema(type="STRING"),
                    "limit": types.Schema(type="INTEGER", description="Max orders to return"),
                },
                required=["customer_id"],
            ),
        ),
    ]),
]

# Gemini may call multiple functions in parallel
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Show me customer C-123 details and their last 5 orders",
    config=types.GenerateContentConfig(
        tools=tools,
        tool_config=types.ToolConfig(
            function_calling_config=types.FunctionCallingConfig(mode="AUTO")
        ),
    ),
)
```

### 4. Multi-Agent with ADK

```python
from google.adk.agents import Agent

# Specialized sub-agents
billing_agent = Agent(
    model="gemini-2.0-flash",
    name="billing_specialist",
    instruction="Handle billing inquiries. Query invoices and payment status.",
    tools=[billing_api_tool],
)

shipping_agent = Agent(
    model="gemini-2.0-flash",
    name="shipping_specialist",
    instruction="Handle shipping inquiries. Track orders and manage returns.",
    tools=[shipping_api_tool],
)

# Supervisor agent delegates to specialists
supervisor = Agent(
    model="gemini-2.0-flash",
    name="customer_service_supervisor",
    instruction="""Route customer inquiries to the appropriate specialist.
    Use billing_specialist for payment/invoice questions.
    Use shipping_specialist for delivery/return questions.""",
    sub_agents=[billing_agent, shipping_agent],
)
```

### 5. MCP Server Integration via ADK

```python
from google.adk.agents import Agent
from google.adk.tools.mcp_tool import MCPToolset, StdioServerParameters

# Connect to any MCP server
postgres_mcp = MCPToolset(
    connection_params=StdioServerParameters(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."],
    )
)

agent = Agent(
    model="gemini-2.0-flash",
    name="data_analyst",
    instruction="Query the database to answer user questions about business data.",
    tools=[postgres_mcp],
)
```

## Anti-Patterns

- Using Gemini API directly when you need agent orchestration -- use Agent Builder or ADK
- Embedding API keys in OpenAPI specs -- use Google Cloud Secret Manager
- Single monolithic agent for all domains -- use multi-agent playbook architecture
- Skipping data store grounding -- ungrounded agents hallucinate enterprise facts
- Ignoring Google Cloud IAM -- always scope service accounts to minimum permissions

## References

- [Vertex AI Agent Builder](https://cloud.google.com/products/agent-builder)
- [Google ADK Documentation](https://google.github.io/adk-docs/)
- [Gemini Function Calling](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/function-calling)
- [Application Integration Connectors](https://cloud.google.com/application-integration/docs/connectors-overview)

<!-- Source: .faos/custom/skills/cloud/gcp/vertex-ai-agents/SKILL.md -->