GCP Vertex AI Agent Builder Deployment Guide

+-------------------------------------------------------------+
|                        GCP Cloud                             |
|                                                              |
|  +------------------+      +------------------------------+  |
|  |   Your Agent     |----->|    Cloud Trace               |  |
|  |  (TraceCraft     |      |   (OTel/Cloud Trace API)     |  |
|  |   enabled)       |      +------------------------------+  |
|  +------------------+                     |                  |
|                                           v                  |
|                           +------------------------------+   |
|                           |   Vertex AI Agent Builder    |   |
|                           |   (Trace Visualization)      |   |
|                           +------------------------------+   |
+-------------------------------------------------------------+

# Enable Cloud Trace API
gcloud services enable cloudtrace.googleapis.com --project=YOUR_PROJECT_ID

pip install tracecraft[gcp-vertex-agent]

import tracecraft
from tracecraft.contrib.gcp import create_vertex_agent_exporter
 
# Create exporter with Vertex AI Agent Builder features
exporter = create_vertex_agent_exporter(
    # GCP project ID (or set GOOGLE_CLOUD_PROJECT env var)
    project_id="your-project-id",
 
    # Service name appears in Cloud Trace
    service_name="my-agent-service",
 
    # Session ID for multi-turn conversation tracking
    session_id="session-12345",
 
    # Enable content recording (prompts/responses)
    # WARNING: Only enable in dev or when data policies allow
    enable_content_recording=False,
 
    # Agent metadata
    agent_name="research-agent",
    agent_id="agent-001",
    agent_description="Researches topics and synthesizes information",
 
    # For Reasoning Engine integration
    reasoning_engine_id="re-001",
)
 
# Initialize TraceCraft
tracecraft.init(
    exporters=[exporter],
    console=False,  # Disable console in production
    jsonl=False,    # Disable local JSONL
)

# main.py
import functions_framework
import tracecraft
from tracecraft.contrib.gcp import configure_for_vertex_agent_builder
 
# Configure at function startup
exporter = configure_for_vertex_agent_builder(service_name="my-function")
tracecraft.init(exporters=[exporter], console=False, jsonl=False)
 
@functions_framework.http
def process_agent(request):
    # Your traced agent code here
    pass

FROM python:3.11-slim
 
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
 
COPY . .
CMD ["python", "main.py"]

# Create service account with Cloud Trace permissions
gcloud iam service-accounts create agent-tracer \
    --display-name="Agent Tracer"
 
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:agent-tracer@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"
 
# Deploy Cloud Run service
gcloud run deploy my-agent \
    --source . \
    --service-account=agent-tracer@YOUR_PROJECT_ID.iam.gserviceaccount.com \
    --set-env-vars=GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID \
    --set-env-vars=TRACECRAFT_GCP_AGENT_NAME=my-agent

from tracecraft.contrib.gcp import configure_for_vertex_agent_builder
 
exporter = configure_for_vertex_agent_builder(service_name="my-cloudrun-agent")
tracecraft.init(exporters=[exporter])

# gcp-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: gcp-credentials
  namespace: default
type: Opaque
data:
  key.json: <base64-encoded-service-account-key>

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: agent
        image: my-agent:latest
        env:
        - name: GOOGLE_CLOUD_PROJECT
          value: "your-project-id"
        - name: GOOGLE_APPLICATION_CREDENTIALS
          value: "/var/secrets/google/key.json"
        - name: TRACECRAFT_GCP_AGENT_NAME
          value: "gke-research-agent"
        volumeMounts:
        - name: gcp-credentials
          mountPath: /var/secrets/google
          readOnly: true
      volumes:
      - name: gcp-credentials
        secret:
          secretName: gcp-credentials

# service-account.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: agent-sa
  annotations:
    iam.gke.io/gcp-service-account: agent-tracer@YOUR_PROJECT_ID.iam.gserviceaccount.com
---
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
spec:
  template:
    spec:
      serviceAccountName: agent-sa
      containers:
      - name: agent
        image: my-agent:latest
        env:
        - name: GOOGLE_CLOUD_PROJECT
          value: "your-project-id"

from tracecraft.contrib.gcp import inject_cloudtrace_context, extract_cloudtrace_context
from tracecraft import get_current_run
import requests
 
# Inject context into outgoing request
headers = {}
inject_cloudtrace_context(headers, get_current_run(), session_id="session-123")
response = requests.post(downstream_url, headers=headers, json=payload)
 
# Extract context from incoming request (in downstream service)
result = extract_cloudtrace_context(request.headers)
if result:
    trace_id, span_id, sampled, session_id = result
    # Continue the trace

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

X-Cloud-Trace-Context: 105445aa7843bc8bf206b12000100000/12345678901234567;o=1

from tracecraft.core.models import AgentRun
 
# Create run with session ID
run = AgentRun(
    name="conversation",
    start_time=datetime.now(UTC),
    session_id="user-session-abc123",  # Links all turns
)
 
# Each turn in the conversation uses the same session_id
# Traces will be correlated in Cloud Trace

exporter = create_vertex_agent_exporter(
    project_id="your-project-id",
    reasoning_engine_id="projects/123/locations/us-central1/reasoningEngines/456",
    agent_name="reasoning-agent",
)

from tracecraft.contrib.gcp import VertexAITracerAdapter
 
adapter = VertexAITracerAdapter(
    project_id="your-project-id",
    enable_content_recording=True,
    agent_name="langchain-agent",
)
 
# Use as LangChain callback
chain.invoke({"input": "..."}, config={"callbacks": [adapter]})

# Verify ADC is configured
gcloud auth application-default print-access-token
 
# Re-authenticate if needed
gcloud auth application-default login