Agent Starter Pack

The Agent Starter Pack is designed to bridge the 'production gap' between a Generative AI prototype and a production-ready agent. It provides a template foundation so developers can focus on core agent logic while the starter pack handles the 'last mile' requirements.

Core Agent Focus (Your Responsibility)

• Prompts and LLM interactions
• Business logic integration
• Agent orchestration (e.g., Google ADK, LangGraph, Agent2Agent (A2A))
• Tools and data source definitions

Starter Pack Foundation (Provided by Template)

• Deployment & Operations: API server, serving options, CI/CD pipelines, Infrastructure as Code (IaC), and testing.
• Observability: Logging, tracing, and monitoring dashboards.
• Evaluation: Vertex AI Evaluation integration.
• Data & UI: Storage connections, vector stores, and a UI playground.
• Security: Implementation of GCP security best practices.

Prompt-response logging is enabled by default in Terraform-managed environments (dev, staging, prod). Use one of the following methods to disable it.

For Cloud Run Deployments

Method 1: Terraform (Permanent) Edit deployment/terraform/[dev/]service.tf to set the environment variable to false:

env {
  name  = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
  value = "false"
}

Then apply the changes:

cd deployment/terraform
terraform apply -var-file=vars/[dev/staging/prod].tfvars

Method 2: gcloud CLI (Temporary) Update the service directly. Note that this will be reverted on the next Terraform apply:

gcloud run services update YOUR_SERVICE_NAME \
  --update-env-vars OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false \
  --region=YOUR_REGION \
  --project=YOUR_PROJECT_ID

For Agent Engine Deployments

Modify app_utils/deploy.py to set the environment variable to false:

# Remove or set to "false"
env_vars["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "false"

Then redeploy using:

make deploy

To test an agent deployed to Cloud Run, retrieve the SERVICE_URL from deployment_metadata.json.

1. Testing Notebook: Use jupyter notebook notebooks/adk_app_testing.ipynb.
2. Python Script: Use requests to create a session via the /apps/<agent-directory>/users/<user_id>/sessions endpoint, then send messages to the /run_sse endpoint using an identity token for authorization.
3. Playground: Run make playground.

import json
import requests

SERVICE_URL = "YOUR_SERVICE_URL"  # From deployment_metadata.json
ID_TOKEN = !gcloud auth print-identity-token -q
headers = {"Content-Type": "application/json", "Authorization": f"Bearer {ID_TOKEN[0]}"}

# Step 1: Create a session
user_id = "test_user"
session_resp = requests.post(
    f"{SERVICE_URL}/apps/<your-agent-directory>/users/{user_id}/sessions",
    headers=headers,
    json={"state": {}}
)
session_id = session_resp.json()["id"]

# Step 2: Send a message
message_resp = requests.post(
    f"{SERVICE_URL}/run_sse",
    headers=headers,
    json={
        "app_name": "<your-agent-directory>",
        "user_id": user_id,
        "session_id": session_id,
        "new_message": {"role": "user", "parts": [{"text": "Hello!"}]},
        "streaming": True
    },
    stream=True
)

for line in message_resp.iter_lines():
    if line and line.decode().startswith("data: "):
        print(json.loads(line.decode()[6:]))

Remote templates allow you to package custom agent logic, dependencies, and infrastructure into a Git repository for others to reuse.

Requirements

• pyproject.toml (Required): Must be at the repository root. It defines Python dependencies and optional [tool.agent-starter-pack] configuration.
• uv.lock (Recommended): Include this for reproducible builds and exact dependency versions.

Quick Start Workflow

1. Structure: Create a directory containing pyproject.toml, an app/ directory (or custom agent_directory), and a README.md.
2. Configure: Define base_template and settings in pyproject.toml.
3. Logic: Implement your agent in app/agent.py.
4. Test: Use uvx agent-starter-pack create <name> -a local@./<path-to-template>.
5. Publish: Push your repository to a Git provider (e.g., GitHub).
6. Share: Users can then run uvx agent-starter-pack create <name> -a <git-url>.