|
| 1 | +# Development Guide |
| 2 | + |
| 3 | +::: tip Note |
| 4 | +This starter pack embraces a **"bring your own agent"** philosophy. You focus on your unique business logic, and we provide the scaffolding for UI, infrastructure, deployment, and monitoring. |
| 5 | +::: |
| 6 | + |
| 7 | +### 1. Prototype Your Agent |
| 8 | +Begin by building and experimenting with your Generative AI Agent. |
| 9 | + |
| 10 | +* Use the introductory notebooks in `notebooks/` for guidance. This is ideal for rapid experimentation and focused agent logic development before integrating into the full application structure |
| 11 | +* Evaluate its performance with [Vertex AI Evaluation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-overview). |
| 12 | + |
| 13 | +### 2. Integrate Your Agent |
| 14 | +Incorporate your prototyped agent into the application. |
| 15 | + |
| 16 | +* Edit `app/agent.py` to import and configure your agent. |
| 17 | +* Customize code within the `app/` directory (e.g., prompts, tools, API endpoints, business logic, functionality). |
| 18 | + |
| 19 | +### 3. Test Locally |
| 20 | +Iterate on your agent using the built-in UI playground. It automatically reloads on code changes and offers features like chat history, user feedback, and diverse input types. |
| 21 | + |
| 22 | +> Note: The specific UI playground (e.g., Streamlit, ADK web UI) launched by `make playground` depends on the agent template you selected. |
| 23 | +
|
| 24 | +### 4. Deploy to the Cloud |
| 25 | +Once you're satisfied with local testing, you are ready to deploy your agent to Google Cloud! |
| 26 | + |
| 27 | +*All `make` commands should be run from the root of your agent project.* |
| 28 | + |
| 29 | +#### A. Cloud Development Environment Setup |
| 30 | +Establish a development (dev) environment in the cloud for initial remote testing. |
| 31 | + |
| 32 | +**i. Set Google Cloud Project:** |
| 33 | +Configure `gcloud` to target your development project: |
| 34 | +```bash |
| 35 | +# Replace YOUR_DEV_PROJECT_ID with your actual Google Cloud Project ID |
| 36 | +gcloud config set project YOUR_DEV_PROJECT_ID |
| 37 | +``` |
| 38 | + |
| 39 | +**ii. Provision Cloud Resources:** |
| 40 | +This command uses Terraform (scripts in `deployment/terraform/dev/`) to set up necessary cloud resources (IAM, databases, etc.): |
| 41 | +```bash |
| 42 | +make setup-dev-env |
| 43 | +``` |
| 44 | + |
| 45 | +**iii. 🚀 Deploy Agent Backend:** |
| 46 | +Build and deploy your agent's backend to the dev environment: |
| 47 | +```bash |
| 48 | +make backend |
| 49 | +``` |
| 50 | + |
| 51 | +#### B. Production-Ready Deployment with CI/CD |
| 52 | +For reliable, automated deployments to staging and production, a CI/CD pipeline is essential. Customize tests within your pipeline as needed. |
| 53 | + |
| 54 | +**Option 1: One-Command CI/CD Setup (Recommended for GitHub)** |
| 55 | +The `agent-starter-pack` CLI streamlines CI/CD setup with GitHub: |
| 56 | +```bash |
| 57 | +agent-starter-pack setup-cicd |
| 58 | +``` |
| 59 | +This automates creating a GitHub repository, connecting to Cloud Build, setting up staging/production infrastructure with Terraform, and configuring CI/CD triggers. |
| 60 | + |
| 61 | +Follow the interactive prompts. For critical systems needing granular control, consider the manual setup. |
| 62 | +See the [`agent-starter-pack setup-cicd` CLI reference](https://github.com/GoogleCloudPlatform/agent-starter-pack/blob/main/docs/cli/setup_cicd.md) for details. *(Note: Automated setup currently supports GitHub only).* |
| 63 | + |
| 64 | +**Option 2: Manual CI/CD Setup** |
| 65 | +For full control and compatibility with other Git providers, refer to the [manual deployment setup guide](./deployment.md). |
| 66 | + |
| 67 | +**Initial Commit & Push (After CI/CD Setup):** |
| 68 | +Once CI/CD is configured, commit and push your code to trigger the first pipeline run: |
| 69 | +```bash |
| 70 | +git add -A |
| 71 | +git config --global user.email "you@example.com" # If not already configured |
| 72 | +git config --global user.name "Your Name" # If not already configured |
| 73 | +git commit -m "Initial commit of agent code" |
| 74 | +git push --set-upstream origin main |
| 75 | +``` |
| 76 | + |
| 77 | +### 5. Monitor Your Deployed Agent |
| 78 | +Track your agent's performance and gather insights using integrated observability tools. |
| 79 | + |
| 80 | +* **Technology**: OpenTelemetry events are sent to Google Cloud. |
| 81 | +* **Cloud Trace & Logging**: Inspect request flows, analyze latencies, and review prompts/outputs. Access traces at: `https://console.cloud.google.com/traces/list?project=YOUR_PROD_PROJECT_ID` |
| 82 | +* **BigQuery**: Route trace and log data to BigQuery for long-term storage and advanced analytics. |
| 83 | +* **Looker Studio Dashboards**: Visualize agent performance with pre-built templates: |
| 84 | + * ADK Agents: [Looker Studio ADK Dashboard](https://lookerstudio.google.com/c/reporting/46b35167-b38b-4e44-bd37-701ef4307418/page/tEnnC) |
| 85 | + * Non-ADK Agents: [Looker Studio Non-ADK Dashboard](https://lookerstudio.google.com/c/reporting/fa742264-4b4b-4c56-81e6-a667dd0f853f/page/tEnnC) |
| 86 | + *(Remember to follow the "Setup Instructions" within the dashboards to connect your project's data sources).* |
| 87 | + |
| 88 | +➡️ For details, see the [Observability Guide](./guide/observability.md). |
| 89 | + |
| 90 | +### 6. Advanced Customization & Data |
| 91 | +Tailor the starter pack further to meet specific needs. |
| 92 | + |
| 93 | +* **RAG Data Ingestion**: For Retrieval Augmented Generation (RAG) agents, configure data pipelines to process your information and load embeddings into Vertex AI Search or Vector Search. |
| 94 | + ➡️ See the [Data Ingestion Guide](./guide/data-ingestion.md). |
| 95 | +* **Custom Terraform**: Modify Terraform configurations in `deployment/terraform/` for unique infrastructure requirements. |
| 96 | + ➡️ Refer to the [Deployment Guide](./guide/deployment.md). |
0 commit comments