You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+12-9Lines changed: 12 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,24 +34,27 @@ Ready to build your AI agent? Simply run this command:
34
34
python -m venv .venv &&source .venv/bin/activate
35
35
36
36
# Install the agent starter pack
37
-
pip install agent-starter-pack
37
+
pip install --upgrade agent-starter-pack
38
38
39
39
# Create a new agent project
40
40
agent-starter-pack create my-awesome-agent
41
41
```
42
42
43
-
**That's it!** You now have a fully functional agent project—complete with backend, frontend, and deployment infrastructure—ready for you to explore and customize.
44
-
See [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) for more options, or try with zero setup in [Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs).
45
-
46
-
---
47
-
48
-
🆕 The starter pack offers full support for Agent Engine, a new fully managed solution to deploy agents. Simply run this command to get started:
43
+
<details>
44
+
<summary> ✨ Alternative: Using uv</summary>
49
45
46
+
If you have [`uv`](https://github.com/astral-sh/uv) installed, you can create and set up your project with a single command:
50
47
```bash
51
-
agent-starter-pack create my-agent -d agent_engine -a adk_base
48
+
uvx agent-starter-pack create my-fullstack-agent
52
49
```
50
+
This command handles creating the project without needing to pre-install the package into a virtual environment.
51
+
</details>
53
52
54
-
*See the [full list of options](https://googlecloudplatform.github.io/agent-starter-pack/cli/create) for details.*
53
+
**That's it!** You now have a fully functional agent project—complete with backend, frontend, and deployment infrastructure—ready for you to explore and customize.
54
+
55
+
See [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) for more options, or try with zero setup in [Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs).
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.
4
+
This guide walks you through the entire lifecycle of creating, developing, deploying, and monitoring your agent project.
5
+
6
+
::: tip Our Philosophy: "Bring Your Own Agent"
7
+
This starter pack provides the scaffolding for UI, infrastructure, deployment, and monitoring. You focus on building your unique agent logic, and we handle the rest.
5
8
:::
6
9
7
-
### 1. Prototype Your Agent
8
-
Begin by building and experimenting with your Generative AI Agent.
10
+
::: details Create Your Project
11
+
You can use the `pip` workflow for a traditional setup, or `uvx` to create a project in a single command without a permanent install.
12
+
13
+
::: code-group
14
+
```bash [pip]
15
+
# 1. Create and activate a virtual environment
16
+
python -m venv .venv
17
+
source .venv/bin/activate
18
+
19
+
# 2. Install the package
20
+
pip install agent-starter-pack
21
+
22
+
# 3. Run the create command
23
+
agent-starter-pack create my-awesome-agent
24
+
```
25
+
26
+
```bash [⚡ uvx]
27
+
# This single command downloads and runs the latest version
28
+
`uvx agent-starter-pack create my-awesome-agent
29
+
```
30
+
:::
31
+
32
+
## 1. Local Development & Iteration
33
+
34
+
Navigate into your new project to begin development.
9
35
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).
36
+
```bash
37
+
cd my-awesome-agent
38
+
```
39
+
40
+
Inside, you'll find a complete project structure:
12
41
13
-
### 2. Integrate Your Agent
14
-
Incorporate your prototyped agent into the application.
42
+
* `app/`: Backend agent code (prompts, tools, business logic).
43
+
* `deployment/`: Terraform infrastructure code.
44
+
* `tests/`: Unit and integration tests.
45
+
* `notebooks/`: Jupyter notebooks for prototyping and evaluation.
46
+
* `frontend/`: (If applicable) Web UI for interacting with your agent.
47
+
* `README.md`: **Project-specific instructions for your chosen template.**
15
48
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).
49
+
Your development loop will look like this:
18
50
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.
51
+
1. **Prototype:** Use the notebooks in `notebooks/` for rapid experimentation with your agent's core logic. This is ideal for trying new prompts or tools before integrating them.
52
+
2. **Integrate:** Edit `app/agent.py` and other files in the `app/` directory to incorporate your new logic into the main application.
53
+
3. **Test:** Run the interactive UI playground to test your changes. It features hot-reloading, chat history, and user feedback.
54
+
55
+
```bash
56
+
# Install dependencies and launch the local playground
57
+
make install && make playground
58
+
```
59
+
> Note: The specific UI playground launched by `make playground` depends on the agent template you selected during creation.
21
60
22
-
> Note: The specific UI playground (e.g., Streamlit, ADK web UI) launched by `make playground` depends on the agent template you selected.
61
+
## 2. Deploy to the Cloud
23
62
24
-
### 4. Deploy to the Cloud
25
-
Once you're satisfied with local testing, you are ready to deploy your agent to Google Cloud!
63
+
Once you're satisfied with local testing, you are ready to deploy your agent to Google Cloud.
26
64
27
-
*All `make` commands should be run from the root of your agent project.*
65
+
*All `make` commands should be run from the root of your agent project (`my-awesome-agent`).*
28
66
29
-
#### A. Cloud Development Environment Setup
30
-
Establish a development (dev) environment in the cloud for initial remote testing.
67
+
### A. Cloud Development Environment Setup
31
68
32
-
**i. Set Google Cloud Project:**
33
-
Configure `gcloud` to target your development project:
69
+
First, provision a non-production environment in the cloud for remote testing.
70
+
71
+
**i. Set Google Cloud Project**
72
+
Configure `gcloud` to target your development project.
34
73
```bash
35
74
# Replace YOUR_DEV_PROJECT_ID with your actual Google Cloud Project ID
36
75
gcloud config set project YOUR_DEV_PROJECT_ID
37
76
```
38
77
39
-
**ii. Provision Cloud Resources:**
40
-
This command uses Terraform (scripts in `deployment/terraform/dev/`) to set up necessary cloud resources (IAM, databases, etc.):
78
+
**ii. Provision Cloud Resources**
79
+
This command uses Terraform to set up necessary cloud resources for your dev environment.
41
80
```bash
42
81
make setup-dev-env
43
82
```
44
83
45
-
**iii. 🚀 Deploy Agent Backend:**
46
-
Build and deploy your agent's backend to the dev environment:
84
+
**iii. Deploy Agent Backend**
85
+
Build and deploy your agent's backend to the dev environment.
47
86
```bash
48
87
make backend
49
88
```
50
89
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.
90
+
### B. Production-Ready Deployment with CI/CD
91
+
92
+
For reliable, automated deployments, a CI/CD pipeline is essential.
53
93
54
94
**Option 1: One-Command CI/CD Setup (Recommended for GitHub)**
55
-
The `agent-starter-pack` CLI streamlines CI/CD setup with GitHub:
95
+
The `agent-starter-pack` CLI can automate the entire CI/CD setup process.
56
96
```bash
57
97
uvx agent-starter-pack setup-cicd
58
98
```
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](../cli/setup_cicd) for details. *(Note: Automated setup currently supports GitHub only).*
99
+
This command creates a GitHub repository, connects it to Cloud Build, provisions staging/production infrastructure, and configures deployment triggers. For details, see the [`setup-cicd` CLI reference](../cli/setup_cicd).
63
100
64
101
**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).
102
+
For full control or for other Git providers, refer to the [manual deployment setup guide](./deployment.md).
66
103
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:
104
+
**Trigger Your First Deployment**
105
+
After CI/CD is configured, commit and push your code to trigger the pipeline.
69
106
```bash
70
107
git add -A
71
108
git config --global user.email "you@example.com"# If not already configured
* **BigQuery**: Route trace and log data to BigQuery for long-term storage and advanced analytics.
83
120
* **Looker Studio Dashboards**: Visualize agent performance with pre-built templates:
84
121
* ADK Agents: [Looker Studio ADK Dashboard](https://lookerstudio.google.com/c/reporting/46b35167-b38b-4e44-bd37-701ef4307418/page/tEnnC)
85
122
* 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).*
123
+
*(Remember to follow the "Setup Instructions" within the dashboards to connect your data sources).*
87
124
88
125
➡️ For details, see the [Observability Guide](./observability.md).
89
126
90
-
### 6. Advanced Customization & Data
91
-
Tailor the starter pack further to meet specific needs.
127
+
## 4. Advanced Customization
128
+
129
+
Tailor the starter pack further to meet your specific requirements.
92
130
93
131
* **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
132
➡️ See the [Data Ingestion Guide](./data-ingestion.md).
95
-
***Custom Terraform**: Modify Terraform configurations in `deployment/terraform/` for unique infrastructure requirements.
96
-
➡️ Refer to the [Deployment Guide](./deployment.md).
133
+
* **Custom Terraform**: Modify Terraform configurations in `deployment/terraform/` for unique infrastructure needs.
134
+
➡️ Refer to the [Deployment Guide](./deployment.md).
# Create and activate a Python virtual environment (Recommended)
16
-
python -m venv .venv
17
-
source .venv/bin/activate # On Windows: .venv\Scripts\activate
13
+
You can use the `pip` workflow for a traditional setup, or `uvx` to create a project in a single command without a permanent install. Choose your preferred method below.
18
14
19
-
# Install the package
20
-
pip install agent-starter-pack
21
-
```
22
-
Check the [Installation Guide](/guide/installation) for alternative installation methods.
15
+
::: code-group
23
16
24
-
### 2. Create Your Agent Project
17
+
```bash [pip]
18
+
# 1. Create and activate a virtual environment
19
+
python -m venv .venv
20
+
source .venv/bin/activate
25
21
26
-
Run the `create` command and follow the prompts:
22
+
# 2. Install the package
23
+
pip install agent-starter-pack
27
24
28
-
```bash
25
+
# 3. Run the create command
29
26
agent-starter-pack create my-awesome-agent
30
27
```
31
28
32
-
This command:
33
-
* Lets you choose an agent template (e.g., `adk_base`, `agentic_rag`).
34
-
* Lets you select a deployment target (e.g., `cloud_run`, `agent_engine`).
0 commit comments