49 |
57 |
58 | 
4 |
5 | A basic agent built using the **[Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/)**. This example demonstrates core ADK concepts like agent creation and tool integration in a minimal setup.
6 |
7 | This agent uses the `gemini-2.5-flash` model and is equipped with two simple tools:
8 | * `get_weather`: Simulates fetching weather (hardcoded for SF).
9 | * `get_current_time`: Simulates fetching the time (hardcoded for SF).
10 |
11 | ## Additional Resources
12 |
13 | - **ADK Samples**: Explore more examples and use cases in the [official ADK Samples Repository](https://github.com/google/adk-samples)
14 | - **ADK Documentation**: Learn more about ADK concepts and capabilities in the [official documentation](https://google.github.io/adk-docs/)
15 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/adk_live_react/frontend/src/setupTests.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2024 Google LLC
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 |
17 | // jest-dom adds custom jest matchers for asserting on DOM nodes.
18 | // allows you to do things like:
19 | // expect(element).toHaveTextContent(/react/i)
20 | // learn more: https://github.com/testing-library/jest-dom
21 | import "@testing-library/jest-dom";
22 |
--------------------------------------------------------------------------------
/.cloudbuild/terraform/storage.tf:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | resource "google_storage_bucket" "logs_data_bucket" {
16 | name = "${var.cicd_runner_project_id}-logs-data"
17 | location = var.region
18 | project = var.cicd_runner_project_id
19 | uniform_bucket_level_access = true
20 | force_destroy = true
21 | }
22 |
--------------------------------------------------------------------------------
/agent_starter_pack/base_template/tests/unit/test_dummy.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 | """
15 | You can add your unit tests here.
16 | This is where you test your business logic, including agent functionality,
17 | data processing, and other core components of your application.
18 | """
19 |
20 |
21 | def test_dummy() -> None:
22 | """Placeholder - replace with real tests."""
23 | assert 1 == 1
24 |
--------------------------------------------------------------------------------
/agent_starter_pack/agents/agentic_rag/app/templates.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | from langchain_core.prompts import (
16 | PromptTemplate,
17 | )
18 |
19 | format_docs = PromptTemplate.from_template(
20 | """## Context provided:
21 | {% for doc in docs%}
22 |
53 | {Array(lineCount)
54 | .fill(null)
55 | .map((_, i) => (
56 | ((set, get) => ({
28 | maxLogs: 500,
29 | logs: [], //mockLogs,
30 | log: ({ date, type, message }: StreamingLog) => {
31 | set((state) => {
32 | const prevLog = state.logs.at(-1);
33 | if (prevLog && prevLog.type === type && prevLog.message === message) {
34 | return {
35 | logs: [
36 | ...state.logs.slice(0, -1),
37 | {
38 | date,
39 | type,
40 | message,
41 | count: prevLog.count ? prevLog.count + 1 : 1,
42 | } as StreamingLog,
43 | ],
44 | };
45 | }
46 | return {
47 | logs: [
48 | ...state.logs.slice(-(get().maxLogs - 1)),
49 | {
50 | date,
51 | type,
52 | message,
53 | } as StreamingLog,
54 | ],
55 | };
56 | });
57 | },
58 |
59 | clearLogs: () => {
60 | console.log("clear log");
61 | set({ logs: [] });
62 | },
63 | setMaxLogs: (n: number) => set({ maxLogs: n }),
64 | }));
65 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/adk_live_react/frontend/src/utils/worklets/vol-meter.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2024 Google LLC
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 |
17 | const VolMeterWorket = `
18 | class VolMeter extends AudioWorkletProcessor {
19 | volume
20 | updateIntervalInMS
21 | nextUpdateFrame
22 |
23 | constructor() {
24 | super()
25 | this.volume = 0
26 | this.updateIntervalInMS = 25
27 | this.nextUpdateFrame = this.updateIntervalInMS
28 | this.port.onmessage = event => {
29 | if (event.data.updateIntervalInMS) {
30 | this.updateIntervalInMS = event.data.updateIntervalInMS
31 | }
32 | }
33 | }
34 |
35 | get intervalInFrames() {
36 | return (this.updateIntervalInMS / 1000) * sampleRate
37 | }
38 |
39 | process(inputs) {
40 | const input = inputs[0]
41 |
42 | if (input.length > 0) {
43 | const samples = input[0]
44 | let sum = 0
45 | let rms = 0
46 |
47 | for (let i = 0; i < samples.length; ++i) {
48 | sum += samples[i] * samples[i]
49 | }
50 |
51 | rms = Math.sqrt(sum / samples.length)
52 | this.volume = Math.max(rms, this.volume * 0.7)
53 |
54 | this.nextUpdateFrame -= samples.length
55 | if (this.nextUpdateFrame < 0) {
56 | this.nextUpdateFrame += this.intervalInFrames
57 | this.port.postMessage({volume: this.volume})
58 | }
59 | }
60 |
61 | return true
62 | }
63 | }`;
64 |
65 | export default VolMeterWorket;
66 |
--------------------------------------------------------------------------------
/agent_starter_pack/agents/crewai_coding_crew/app/agent.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | # mypy: disable-error-code="union-attr"
16 | from langchain_google_vertexai import ChatVertexAI
17 | from langgraph.prebuilt import create_react_agent
18 |
19 | from .crew.crew import DevCrew
20 |
21 | LOCATION = "global"
22 | LLM = "gemini-2.5-flash"
23 |
24 | llm = ChatVertexAI(model=LLM, location=LOCATION, temperature=0)
25 |
26 |
27 | def coding_tool(code_instructions: str) -> str:
28 | """Use this tool to write a python program given a set of requirements and or instructions."""
29 | inputs = {"code_instructions": code_instructions}
30 | return DevCrew().crew().kickoff(inputs=inputs)
31 |
32 |
33 | system_message = (
34 | "You are an expert Lead Software Engineer Manager.\n"
35 | "Your role is to speak to a user and understand what kind of code they need to "
36 | "build.\n"
37 | "Part of your task is therefore to gather requirements and clarifying ambiguity "
38 | "by asking followup questions. Don't ask all the questions together as the user "
39 | "has a low attention span, rather ask a question at the time.\n"
40 | "Once the problem to solve is clear, you will call your tool for writing the "
41 | "solution.\n"
42 | "Remember, you are an expert in understanding requirements but you cannot code, "
43 | "use your coding tool to generate a solution. Keep the test cases if any, they "
44 | "are useful for the user."
45 | )
46 |
47 | agent = create_react_agent(model=llm, tools=[coding_tool], prompt=system_message)
48 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Contributor Code of Conduct
2 |
3 | As contributors and maintainers of this project,
4 | and in the interest of fostering an open and welcoming community,
5 | we pledge to respect all people who contribute through reporting issues,
6 | posting feature requests, updating documentation,
7 | submitting pull requests or patches, and other activities.
8 |
9 | We are committed to making participation in this project
10 | a harassment-free experience for everyone,
11 | regardless of level of experience, gender, gender identity and expression,
12 | sexual orientation, disability, personal appearance,
13 | body size, race, ethnicity, age, religion, or nationality.
14 |
15 | Examples of unacceptable behavior by participants include:
16 |
17 | - The use of sexualized language or imagery
18 | - Personal attacks
19 | - Trolling or insulting/derogatory comments
20 | - Public or private harassment
21 | - Publishing other's private information,
22 | such as physical or electronic
23 | addresses, without explicit permission
24 | - Other unethical or unprofessional conduct.
25 |
26 | Project maintainers have the right and responsibility to remove, edit, or reject
27 | comments, commits, code, wiki edits, issues, and other contributions
28 | that are not aligned to this Code of Conduct.
29 | By adopting this Code of Conduct,
30 | project maintainers commit themselves to fairly and consistently
31 | applying these principles to every aspect of managing this project.
32 | Project maintainers who do not follow or enforce the Code of Conduct
33 | may be permanently removed from the project team.
34 |
35 | This code of conduct applies both within project spaces and in public spaces
36 | when an individual is representing the project or its community.
37 |
38 | Instances of abusive, harassing, or otherwise unacceptable behavior
39 | may be reported by opening an issue
40 | or contacting one or more of the project maintainers.
41 |
42 | This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0,
43 | available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
44 |
--------------------------------------------------------------------------------
/docs/guide/community-showcase.md:
--------------------------------------------------------------------------------
1 | # 🌟 Community Showcase
2 |
3 | Welcome to the Agent Starter Pack Community Showcase! This page highlights amazing projects, implementations, and creative uses of the Agent Starter Pack by our community.
4 |
5 | ## 🔍 Explore Community Projects
6 |
7 | **[Browse all community agents on GitHub →](https://github.com/search?q=Agent+generated+with+%5B%60googleCloudPlatform%2Fagent-starter-pack%60%5D&type=code)**
8 |
9 | Discover how developers are using our templates in real-world applications.
10 |
11 | ## Featured Projects
12 |
13 | ### Smart Learning Platform by [tensr](https://tensr.be/)
14 | **Repository:** [jossehuybrechts/smart-learning](https://github.com/jossehuybrechts/smart-learning)
15 | **Blog Post:** [Building a Smart Learning Platform with Google's Agent Starter Pack](https://medium.com/@tensr/9f75876bc618)
16 |
17 | An intelligent learning platform that adapts to individual learning styles and provides personalized educational content. This project demonstrates how to build a production-ready educational AI agent using the Agent Starter Pack's templates and deployment infrastructure.
18 |
19 | ### Production Monitoring Assistant by [norma](https://norma.dev/)
20 | **Repository:** [adilmoumni/prod-monitoring-assistant](https://github.com/adilmoumni/prod-monitoring-assistant)
21 | **Blog Post:** [Building an AI Agent for Production Monitoring at the Agentic Era Hackathon](https://medium.com/norma-dev/building-an-ai-agent-for-production-monitoring-at-the-agentic-era-hackathon-ffa283dd391d)
22 |
23 | An AI-powered production monitoring assistant built for the Agentic Era Hackathon. This agent helps DevOps teams monitor system health, detect anomalies, and provide intelligent insights for maintaining production environments.
24 |
25 | ---
26 |
27 | *This section will be updated regularly as we review and feature outstanding community submissions.*
28 |
29 | ## 📝 Submit Your Project
30 |
31 | Built something amazing with the Agent Starter Pack? **[Create a showcase issue](https://github.com/GoogleCloudPlatform/agent-starter-pack/issues/new?labels=showcase)** with your repository URL, project description, and unique features.
32 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/adk_live_react/frontend/src/hooks/use-webcam.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2024 Google LLC
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 |
17 | import { useState, useEffect } from "react";
18 | import { UseMediaStreamResult } from "./use-media-stream-mux";
19 |
20 | export function useWebcam(): UseMediaStreamResult {
21 | const [stream, setStream] = useState(null);
22 | const [isStreaming, setIsStreaming] = useState(false);
23 |
24 | useEffect(() => {
25 | const handleStreamEnded = () => {
26 | setIsStreaming(false);
27 | setStream(null);
28 | };
29 | if (stream) {
30 | stream
31 | .getTracks()
32 | .forEach((track) => track.addEventListener("ended", handleStreamEnded));
33 | return () => {
34 | stream
35 | .getTracks()
36 | .forEach((track) =>
37 | track.removeEventListener("ended", handleStreamEnded),
38 | );
39 | };
40 | }
41 | }, [stream]);
42 |
43 | const start = async () => {
44 | const mediaStream = await navigator.mediaDevices.getUserMedia({
45 | video: true,
46 | });
47 | setStream(mediaStream);
48 | setIsStreaming(true);
49 | return mediaStream;
50 | };
51 |
52 | const stop = () => {
53 | if (stream) {
54 | stream.getTracks().forEach((track) => track.stop());
55 | setStream(null);
56 | setIsStreaming(false);
57 | }
58 | };
59 |
60 | const result: UseMediaStreamResult = {
61 | type: "webcam",
62 | start,
63 | stop,
64 | isStreaming,
65 | stream,
66 | };
67 |
68 | return result;
69 | }
70 |
--------------------------------------------------------------------------------
/.cloudbuild/terraform/service_account.tf:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 | # Define local variables for roles
15 |
16 |
17 | locals {
18 | cicd_runner_roles = [
19 | "roles/owner",
20 | ]
21 |
22 | e2e_project_roles = [
23 | "roles/owner",
24 | ]
25 | }
26 |
27 | # Create a service account for CICD runner
28 | resource "google_service_account" "cicd_runner_sa" {
29 | project = var.cicd_runner_project_id
30 | account_id = "cicd-tests-runner-sa"
31 | display_name = "Service Account for CI/CD Pipeline Runner"
32 | description = "Used by Cloud Build to execute CI/CD pipelines"
33 | }
34 |
35 | # Grant necessary roles to the service account
36 | resource "google_project_iam_member" "cicd_runner_roles" {
37 | for_each = toset(local.cicd_runner_roles)
38 |
39 | project = var.cicd_runner_project_id
40 | role = each.key
41 | member = "serviceAccount:${google_service_account.cicd_runner_sa.email}"
42 | }
43 |
44 | # Grant permissions to the service account for each environment project
45 | resource "google_project_iam_member" "cicd_runner_e2e_project_roles" {
46 | for_each = {
47 | for idx, proj_role in flatten([
48 | for env, project_id in var.e2e_test_project_mapping : [
49 | for role in local.e2e_project_roles : {
50 | project = project_id
51 | env = env
52 | role = role
53 | }
54 | ]
55 | ]) : "${proj_role.env}-${proj_role.role}" => proj_role
56 | }
57 |
58 | project = each.value.project
59 | role = each.value.role
60 | member = "serviceAccount:${google_service_account.cicd_runner_sa.email}"
61 | }
62 |
--------------------------------------------------------------------------------
/agent_starter_pack/agents/adk_live/README.md:
--------------------------------------------------------------------------------
1 | # ADK Live Agent
2 |
3 | Real-time conversational agent built with Google ADK and Gemini's live audio model. Supports audio, video, and text interactions with native tool calling.
4 |
5 | 
6 |
7 | **Key components:**
8 |
9 | - **Python Backend** (in `app/` folder): ADK-powered agent using Gemini's live audio model with native tool calling and deployment support for Cloud Run and Agent Engine
10 |
11 | - **React Frontend** (in `frontend/` folder): Web console for interacting with the live agent via audio, video, and text
12 |
13 | 
14 |
15 | Once running, click the play button to connect and interact with the agent. Try asking "What's the weather like in San Francisco?" to see tool calling in action.
16 |
17 | ## Additional Resources for Multimodal Live API
18 |
19 | Explore these resources to learn more about the Multimodal Live API and see examples of its usage:
20 |
21 | - [Project Pastra](https://github.com/heiko-hotz/gemini-multimodal-live-dev-guide/tree/main): a comprehensive developer guide for the Gemini Multimodal Live API.
22 | - [Google Cloud Multimodal Live API demos and samples](https://github.com/GoogleCloudPlatform/generative-ai/tree/main/gemini/multimodal-live-api): Collection of code samples and demo applications leveraging multimodal live API in Vertex AI
23 | - [Gemini 2 Cookbook](https://github.com/google-gemini/cookbook/tree/main/gemini-2): Practical examples and tutorials for working with Gemini 2
24 | - [Multimodal Live API Web Console](https://github.com/google-gemini/multimodal-live-api-web-console): Interactive React-based web interface for testing and experimenting with Gemini Multimodal Live API.
25 |
26 | ## Current Status & Future Work
27 |
28 | This pattern is under active development. Key areas planned for future enhancement include:
29 |
30 | * **Observability:** Implementing comprehensive monitoring and tracing features.
31 | * **Load Testing:** Integrating load testing capabilities.
32 |
--------------------------------------------------------------------------------
/agent_starter_pack/cli/main.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | import importlib.metadata
16 | import sys
17 |
18 | import click
19 | from rich.console import Console
20 |
21 | from .commands.create import create
22 | from .commands.enhance import enhance
23 | from .commands.list import list_agents
24 | from .commands.setup_cicd import setup_cicd
25 | from .utils import display_update_message
26 |
27 | console = Console()
28 |
29 |
30 | def print_version(ctx: click.Context, param: click.Parameter, value: bool) -> None:
31 | if not value or ctx.resilient_parsing:
32 | return
33 | try:
34 | version_str = importlib.metadata.version("agent-starter-pack")
35 | console.print(f"GCP Agent Starter Pack CLI version: {version_str}")
36 | except importlib.metadata.PackageNotFoundError:
37 | console.print("GCP Agent Starter Pack CLI (development version)")
38 | ctx.exit()
39 |
40 |
41 | @click.group(help="Production-ready Generative AI Agent templates for Google Cloud")
42 | @click.option(
43 | "--version",
44 | "-v",
45 | is_flag=True,
46 | callback=print_version,
47 | expose_value=False,
48 | is_eager=True,
49 | help="Show the version and exit.",
50 | )
51 | def cli() -> None:
52 | # Check for updates at startup (skip if --agent-garden or -ag is used)
53 | if "--agent-garden" not in sys.argv and "-ag" not in sys.argv:
54 | display_update_message()
55 |
56 |
57 | # Register commands
58 | cli.add_command(create)
59 | cli.add_command(enhance)
60 | cli.add_command(setup_cicd)
61 | cli.add_command(list_agents, name="list")
62 |
63 |
64 | if __name__ == "__main__":
65 | cli()
66 |
--------------------------------------------------------------------------------
/agent_starter_pack/agents/adk_base/tests/integration/test_agent.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | # mypy: disable-error-code="union-attr"
16 | from google.adk.agents.run_config import RunConfig, StreamingMode
17 | from google.adk.runners import Runner
18 | from google.adk.sessions import InMemorySessionService
19 | from google.genai import types
20 |
21 | from {{cookiecutter.agent_directory}}.agent import root_agent
22 |
23 |
24 | def test_agent_stream() -> None:
25 | """
26 | Integration test for the agent stream functionality.
27 | Tests that the agent returns valid streaming responses.
28 | """
29 |
30 | session_service = InMemorySessionService()
31 |
32 | session = session_service.create_session_sync(user_id="test_user", app_name="test")
33 | runner = Runner(agent=root_agent, session_service=session_service, app_name="test")
34 |
35 | message = types.Content(
36 | role="user", parts=[types.Part.from_text(text="Why is the sky blue?")]
37 | )
38 |
39 | events = list(
40 | runner.run(
41 | new_message=message,
42 | user_id="test_user",
43 | session_id=session.id,
44 | run_config=RunConfig(streaming_mode=StreamingMode.SSE),
45 | )
46 | )
47 | assert len(events) > 0, "Expected at least one message"
48 |
49 | has_text_content = False
50 | for event in events:
51 | if (
52 | event.content
53 | and event.content.parts
54 | and any(part.text for part in event.content.parts)
55 | ):
56 | has_text_content = True
57 | break
58 | assert has_text_content, "Expected at least one message with text content"
59 |
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: home
3 | title: Home
4 |
5 | hero:
6 | name: Agent Starter Pack
7 | text: Production-Ready Agents on Google Cloud, faster
8 | tagline: Go from idea to deployment faster with pre-built templates & tools.
9 | image:
10 | src: https://github.com/GoogleCloudPlatform/agent-starter-pack/blob/main/docs/images/logo.png?raw=true
11 | alt: Agent Starter Pack Logo
12 | actions:
13 | - theme: brand
14 | text: Get Started Guide
15 | link: /guide/getting-started
16 | - theme: alt
17 | text: Development Guide
18 | link: /guide/development-guide
19 | - theme: alt
20 | text: Watch Demo Video
21 | link: https://www.youtube.com/watch?v=9zqwym-N3lg
22 |
23 | features:
24 | - icon: ⚡️
25 | title: Launch Quickly
26 | details: Start fast with pre-built agent templates (ReAct, RAG, multi-agent, Live Multimodal API) implementing common patterns.
27 | - icon: 🧪
28 | title: Experiment & Evaluate
29 | details: Iterate using integrated Vertex AI evaluation and an interactive testing playground.
30 | - icon: ☁️
31 | title: Deploy Confidently
32 | details: Ship reliable agents with production-ready infra (Cloud Run / Agent Engine) featuring monitoring, observability, and CI/CD.
33 | - icon: 🛠️
34 | title: Customize & Extend
35 | details: Adapt and enhance templates for your specific use case, or create your own.
36 | ---
37 |
38 | ::: tip ⭐ Like Agent Starter Pack?
39 | Help us spread the word by giving us a star on GitHub!
40 |
41 |
42 | 
43 |
44 |
45 | :::
46 |
47 | ## Quick Links
48 |
49 | - **New Users:** [Getting Started Guide](/guide/getting-started)
50 | - **Setup:** [Installation Guide](/guide/installation)
51 | - **Going Live:** [Deployment Guide](/guide/deployment)
52 | - **Explore Templates:** [Agent Templates Overview](/agents/overview)
53 | - **Community:** [Community Showcase](/guide/community-showcase)
54 | - **Command Line:** [CLI Reference](/cli/)
--------------------------------------------------------------------------------
/agent_starter_pack/agents/crewai_coding_crew/app/crew/crew.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | # mypy: disable-error-code="attr-defined"
16 | from typing import Any
17 |
18 | from crewai import Agent, Crew, Process, Task
19 | from crewai.project import CrewBase, agent, crew, task
20 |
21 |
22 | @CrewBase
23 | class DevCrew:
24 | """Developer crew"""
25 |
26 | agents_config: dict[str, Any]
27 | tasks_config: dict[str, Any]
28 |
29 | llm = "vertex_ai/gemini-2.0-flash-001"
30 |
31 | @agent
32 | def senior_engineer_agent(self) -> Agent:
33 | return Agent(
34 | config=self.agents_config.get("senior_engineer_agent"),
35 | allow_delegation=False,
36 | verbose=True,
37 | llm=self.llm,
38 | )
39 |
40 | @agent
41 | def chief_qa_engineer_agent(self) -> Agent:
42 | return Agent(
43 | config=self.agents_config.get("chief_qa_engineer_agent"),
44 | allow_delegation=True,
45 | verbose=True,
46 | llm=self.llm,
47 | )
48 |
49 | @task
50 | def code_task(self) -> Task:
51 | return Task(
52 | config=self.tasks_config.get("code_task"),
53 | agent=self.senior_engineer_agent(),
54 | )
55 |
56 | @task
57 | def evaluate_task(self) -> Task:
58 | return Task(
59 | config=self.tasks_config.get("evaluate_task"),
60 | agent=self.chief_qa_engineer_agent(),
61 | )
62 |
63 | @crew
64 | def crew(self) -> Crew:
65 | """Creates the Dev Crew"""
66 | return Crew(
67 | agents=self.agents,
68 | tasks=self.tasks,
69 | process=Process.sequential,
70 | verbose=True,
71 | )
72 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/adk_live_react/frontend/src/hooks/use-screen-capture.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2024 Google LLC
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 |
17 | import { useState, useEffect } from "react";
18 | import { UseMediaStreamResult } from "./use-media-stream-mux";
19 |
20 | export function useScreenCapture(): UseMediaStreamResult {
21 | const [stream, setStream] = useState(null);
22 | const [isStreaming, setIsStreaming] = useState(false);
23 |
24 | useEffect(() => {
25 | const handleStreamEnded = () => {
26 | setIsStreaming(false);
27 | setStream(null);
28 | };
29 | if (stream) {
30 | stream
31 | .getTracks()
32 | .forEach((track) => track.addEventListener("ended", handleStreamEnded));
33 | return () => {
34 | stream
35 | .getTracks()
36 | .forEach((track) =>
37 | track.removeEventListener("ended", handleStreamEnded),
38 | );
39 | };
40 | }
41 | }, [stream]);
42 |
43 | const start = async () => {
44 | // const controller = new CaptureController();
45 | // controller.setFocusBehavior("no-focus-change");
46 | const mediaStream = await navigator.mediaDevices.getDisplayMedia({
47 | video: true,
48 | // controller
49 | });
50 | setStream(mediaStream);
51 | setIsStreaming(true);
52 | return mediaStream;
53 | };
54 |
55 | const stop = () => {
56 | if (stream) {
57 | stream.getTracks().forEach((track) => track.stop());
58 | setStream(null);
59 | setIsStreaming(false);
60 | }
61 | };
62 |
63 | const result: UseMediaStreamResult = {
64 | type: "screen",
65 | start,
66 | stop,
67 | isStreaming,
68 | stream,
69 | };
70 |
71 | return result;
72 | }
73 |
--------------------------------------------------------------------------------
/agent_starter_pack/agents/agentic_rag/README.md:
--------------------------------------------------------------------------------
1 | # Agentic RAG
2 |
3 | This agent enhances the Agent Starter Pack with a production-ready data ingestion pipeline, enriching your Retrieval Augmented Generation (RAG) applications. You will be able to ingest, process, and embed custom data, improving the relevance and context of your generated responses. You can choose between different datastore options including Vertex AI Search and Vertex AI Vector Search depending on your specific needs.
4 |
5 | The agent provides the infrastructure to create a Vertex AI Pipeline with your custom code. Because it's built on Vertex AI Pipelines, you benefit from features like scheduled runs, recurring executions, and on-demand triggers. For processing terabyte-scale data, we recommend combining Vertex AI Pipelines with data analytics tools like BigQuery or Dataflow.
6 |
7 | 
8 |
9 | ## Architecture
10 |
11 | The agent implements the following architecture:
12 |
13 | 
14 |
15 | ### Key Features
16 |
17 | - **Built on Agent Development Kit (ADK):** ADK is a flexible, modular framework for developing and deploying AI agents. It integrates with the Google ecosystem and Gemini models, supporting various LLMs and open-source AI tools, enabling both simple and complex agent architectures.
18 | - **Flexible Datastore Options:** Choose between Vertex AI Search or Vertex AI Vector Search for efficient data storage and retrieval based on your specific needs.
19 | - **Automated Data Ingestion Pipeline:** Automates the process of ingesting data from input sources.
20 | - **Custom Embeddings:** Generates embeddings using Vertex AI Embeddings and incorporates them into your data for enhanced semantic search.
21 | - **Terraform Deployment:** Ingestion pipeline is instantiated with Terraform alongside the rest of the infrastructure of the starter pack.
22 | - **CI/CD Integration:** Deployment of ingestion pipelines is added to the CD pipelines of the starter pack.
23 | - **Customizable Code:** Easily adapt and customize the code to fit your specific application needs and data sources.
24 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/adk_live_react/frontend/src/utils/worklets/audio-processing.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2024 Google LLC
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 |
17 | const AudioRecordingWorklet = `
18 | class AudioProcessingWorklet extends AudioWorkletProcessor {
19 |
20 | // send and clear buffer every 2048 samples,
21 | // which at 16khz is about 8 times a second
22 | buffer = new Int16Array(2048);
23 |
24 | // current write index
25 | bufferWriteIndex = 0;
26 |
27 | constructor() {
28 | super();
29 | this.hasAudio = false;
30 | }
31 |
32 | /**
33 | * @param inputs Float32Array[][] [input#][channel#][sample#] so to access first inputs 1st channel inputs[0][0]
34 | * @param outputs Float32Array[][]
35 | */
36 | process(inputs) {
37 | if (inputs[0].length) {
38 | const channel0 = inputs[0][0];
39 | this.processChunk(channel0);
40 | }
41 | return true;
42 | }
43 |
44 | sendAndClearBuffer(){
45 | this.port.postMessage({
46 | event: "chunk",
47 | data: {
48 | int16arrayBuffer: this.buffer.slice(0, this.bufferWriteIndex).buffer,
49 | },
50 | });
51 | this.bufferWriteIndex = 0;
52 | }
53 |
54 | processChunk(float32Array) {
55 | const l = float32Array.length;
56 |
57 | for (let i = 0; i < l; i++) {
58 | // convert float32 -1 to 1 to int16 -32768 to 32767
59 | const int16Value = float32Array[i] * 32768;
60 | this.buffer[this.bufferWriteIndex++] = int16Value;
61 | if(this.bufferWriteIndex >= this.buffer.length) {
62 | this.sendAndClearBuffer();
63 | }
64 | }
65 |
66 | if(this.bufferWriteIndex >= this.buffer.length) {
67 | this.sendAndClearBuffer();
68 | }
69 | }
70 | }
71 | `;
72 |
73 | export default AudioRecordingWorklet;
74 |
--------------------------------------------------------------------------------
/agent_starter_pack/resources/idx/.idx/dev.nix:
--------------------------------------------------------------------------------
1 |
2 | # To learn more about how to use Nix to configure your environment
3 | # see: https://firebase.google.com/docs/studio/customize-workspace
4 | { pkgs, ... }: {
5 | # Which nixpkgs channel to use.
6 | channel = "stable-24.11"; # or "unstable"
7 |
8 | # Use https://search.nixos.org/packages to find packages
9 | packages = [
10 | pkgs.uv
11 | pkgs.gnumake
12 | pkgs.terraform
13 | pkgs.gh
14 | ];
15 | # Sets environment variables in the workspace
16 | env = {};
17 | idx = {
18 | # Search for the extensions you want on https://open-vsx.org/ and use "publisher.id"
19 | extensions = [
20 | ];
21 | workspace = {
22 | # Runs when a workspace is first created with this `dev.nix` file
23 | onCreate = {
24 | create-venv = ''
25 | # Load environment variables from .env file if it exists
26 | source .env
27 |
28 | # Beautiful prints for gcloud setup
29 | echo ""
30 | echo "╔════════════════════════════════════════════════════════════╗"
31 | echo "║ 🔐 GCLOUD SETUP REQUIRED ║"
32 | echo "╚════════════════════════════════════════════════════════════╝"
33 | echo ""
34 | echo "📝 Before proceeding, please ensure:"
35 | echo " 1️⃣ You are logged in to gcloud"
36 | echo " 2️⃣ You have selected the correct project"
37 | echo ""
38 |
39 | auth_status=$(gcloud auth list --quiet 2>&1)
40 |
41 | echo ""
42 | echo "⚙️ We will now set the project you want to use..."
43 | gcloud config get project
44 |
45 | echo ""
46 | echo "💡 Need to setup? Run these commands:"
47 | echo " → gcloud auth login"
48 | echo " → gcloud config set project YOUR_PROJECT_ID"
49 | echo ""
50 |
51 | echo "Running agent starter pack creation..."
52 | uvx agent-starter-pack create $WS_NAME
53 | code ~/$WS_NAME/$WS_NAME/README.md
54 | exec bash
55 | '';
56 | # Open editors for the following files by default, if they exist:
57 | default.openFiles = [];
58 | };
59 | # To run something each time the workspace is (re)started, use the `onStart` hook
60 | };
61 | # Enable previews and customize configuration
62 | previews = {};
63 | };
64 | }
--------------------------------------------------------------------------------
/agent_starter_pack/base_template/{% if cookiecutter.cicd_runner == 'github_actions' %}.github{% else %}unused_github{% endif %}/workflows/pr_checks.yaml:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | name: PR Checks
16 |
17 | on:
18 | pull_request:
19 | branches:
20 | - main
21 | paths:
22 | - '{{cookiecutter.agent_directory}}/**'
23 | - 'data_ingestion/**'
24 | - 'tests/**'
25 | - 'deployment/**'
26 | - 'uv.lock'
27 | {%- if cookiecutter.data_ingestion %}
28 | - 'data_ingestion/**'
29 | {%- endif %}
30 |
31 | jobs:
32 | test:
33 | runs-on: ubuntu-latest
34 | permissions:
35 | contents: 'read'
36 | id-token: 'write'
37 | steps:
38 | - name: Checkout code
39 | uses: actions/checkout@v4
40 |
41 | - id: 'auth'
42 | name: 'Authenticate to Google Cloud'
43 | uses: 'google-github-actions/auth@v2'
44 | with:
45 | workload_identity_provider: 'projects/{% raw %}${{ vars.GCP_PROJECT_NUMBER }}{% endraw %}/locations/global/workloadIdentityPools/{% raw %}${{ secrets.WIF_POOL_ID }}{% endraw %}/providers/{% raw %}${{ secrets.WIF_PROVIDER_ID }}{% endraw %}'
46 | service_account: '{% raw %}${{ secrets.GCP_SERVICE_ACCOUNT }}{% endraw %}'
47 | create_credentials_file: true
48 | project_id: {% raw %}${{ vars.CICD_PROJECT_ID }}{% endraw %}
49 |
50 |
51 | - name: Set up Python 3.11
52 | uses: actions/setup-python@v4
53 | with:
54 | python-version: '3.11'
55 |
56 | - name: Install uv and dependencies
57 | run: |
58 | pip install uv==0.8.13
59 | uv sync --locked
60 |
61 | - name: Run unit tests
62 | run: uv run pytest tests/unit
63 |
64 | - name: Run integration tests
65 | run: uv run pytest tests/integration
66 |
--------------------------------------------------------------------------------
/agent_starter_pack/agents/adk_base/app/agent.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | import datetime
16 | import os
17 | from zoneinfo import ZoneInfo
18 |
19 | import google.auth
20 | from google.adk.agents import Agent
21 |
22 | _, project_id = google.auth.default()
23 | os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
24 | os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
25 | os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")
26 |
27 |
28 | def get_weather(query: str) -> str:
29 | """Simulates a web search. Use it get information on weather.
30 |
31 | Args:
32 | query: A string containing the location to get weather information for.
33 |
34 | Returns:
35 | A string with the simulated weather information for the queried location.
36 | """
37 | if "sf" in query.lower() or "san francisco" in query.lower():
38 | return "It's 60 degrees and foggy."
39 | return "It's 90 degrees and sunny."
40 |
41 |
42 | def get_current_time(query: str) -> str:
43 | """Simulates getting the current time for a city.
44 |
45 | Args:
46 | city: The name of the city to get the current time for.
47 |
48 | Returns:
49 | A string with the current time information.
50 | """
51 | if "sf" in query.lower() or "san francisco" in query.lower():
52 | tz_identifier = "America/Los_Angeles"
53 | else:
54 | return f"Sorry, I don't have timezone information for query: {query}."
55 |
56 | tz = ZoneInfo(tz_identifier)
57 | now = datetime.datetime.now(tz)
58 | return f"The current time for query {query} is {now.strftime('%Y-%m-%d %H:%M:%S %Z%z')}"
59 |
60 |
61 | root_agent = Agent(
62 | name="root_agent",
63 | model="gemini-2.5-flash",
64 | instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
65 | tools=[get_weather, get_current_time],
66 | )
67 |
--------------------------------------------------------------------------------
/agent_starter_pack/agents/agentic_rag/tests/integration/test_agent.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | # mypy: disable-error-code="union-attr"
16 | from unittest.mock import MagicMock, patch
17 |
18 | from google.adk.agents.run_config import RunConfig, StreamingMode
19 | from google.adk.runners import Runner
20 | from google.adk.sessions import InMemorySessionService
21 | from google.genai import types
22 |
23 | from {{cookiecutter.agent_directory}}.agent import root_agent
24 |
25 |
26 | @patch(
27 | "{{cookiecutter.agent_directory}}.agent.retrieve_docs",
28 | return_value="dummy content",
29 | )
30 | def test_agent_stream(mock_retrieve: MagicMock) -> None:
31 | """
32 | Integration test for the agent stream functionality.
33 | Tests that the agent returns valid streaming responses.
34 | """
35 |
36 | session_service = InMemorySessionService()
37 |
38 | session = session_service.create_session_sync(user_id="test_user", app_name="test")
39 | runner = Runner(agent=root_agent, session_service=session_service, app_name="test")
40 |
41 | message = types.Content(
42 | role="user", parts=[types.Part.from_text(text="Why is the sky blue?")]
43 | )
44 |
45 | events = list(
46 | runner.run(
47 | new_message=message,
48 | user_id="test_user",
49 | session_id=session.id,
50 | run_config=RunConfig(streaming_mode=StreamingMode.SSE),
51 | )
52 | )
53 | assert len(events) > 0, "Expected at least one message"
54 |
55 | has_text_content = False
56 | for event in events:
57 | if (
58 | event.content
59 | and event.content.parts
60 | and any(part.text for part in event.content.parts)
61 | ):
62 | has_text_content = True
63 | break
64 | assert has_text_content, "Expected at least one message with text content"
65 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/streamlit/frontend/utils/message_editing.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | # fmt: off
16 |
17 | from typing import Any
18 |
19 |
20 | class MessageEditing:
21 | """Provides methods for editing, refreshing, and deleting chat messages."""
22 |
23 | @staticmethod
24 | def edit_message(st: Any, button_idx: int, message_type: str) -> None:
25 | """Edit a message in the chat history."""
26 | button_id = f"edit_box_{button_idx}"
27 | if message_type == "human":
28 | messages = st.session_state.user_chats[st.session_state["session_id"]][
29 | "messages"
30 | ]
31 | st.session_state.user_chats[st.session_state["session_id"]][
32 | "messages"
33 | ] = messages[:button_idx]
34 | st.session_state.modified_prompt = st.session_state[button_id]
35 | else:
36 | st.session_state.user_chats[st.session_state["session_id"]]["messages"][
37 | button_idx
38 | ]["content"] = st.session_state[button_id]
39 |
40 | @staticmethod
41 | def refresh_message(st: Any, button_idx: int, content: str) -> None:
42 | """Refresh a message in the chat history."""
43 | messages = st.session_state.user_chats[st.session_state["session_id"]][
44 | "messages"
45 | ]
46 | st.session_state.user_chats[st.session_state["session_id"]][
47 | "messages"
48 | ] = messages[:button_idx]
49 | st.session_state.modified_prompt = content
50 |
51 | @staticmethod
52 | def delete_message(st: Any, button_idx: int) -> None:
53 | """Delete a message from the chat history."""
54 | messages = st.session_state.user_chats[st.session_state["session_id"]][
55 | "messages"
56 | ]
57 | st.session_state.user_chats[st.session_state["session_id"]][
58 | "messages"
59 | ] = messages[:button_idx]
60 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/adk_live_react/frontend/src/App.tsx:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2024 Google LLC
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 |
17 | import { useRef, useState } from "react";
18 | import "./App.scss";
19 | import { LiveAPIProvider } from "./contexts/LiveAPIContext";
20 | import SidePanel from "./components/side-panel/SidePanel";
21 | import cn from "classnames";
22 |
23 | // In development mode (frontend on :8501), connect to backend on :8000
24 | const isDevelopment = window.location.port === '8501';
25 | const defaultHost = isDevelopment ? `${window.location.hostname}:8000` : window.location.host;
26 | const defaultUri = `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${defaultHost}/`;
27 |
28 | function App() {
29 | const videoRef = useRef(null);
30 | const [videoStream, setVideoStream] = useState(null);
31 | const [serverUrl, setServerUrl] = useState(defaultUri);
32 | const [userId, setUserId] = useState("user1");
33 |
34 | return (
35 | Multimodal Live - Console
46 |
47 |
48 |
49 |
50 |
51 |
61 |
62 |
63 |
--------------------------------------------------------------------------------
/tests/test_frontend/test_utils/test_multimodal_utils.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | from unittest.mock import MagicMock, patch
16 |
17 | import pytest
18 |
19 | from frontend.utils.multimodal_utils import (
20 | format_content,
21 | get_gcs_blob_mime_type,
22 | gs_uri_to_https_url,
23 | )
24 |
25 |
26 | def test_format_content_text_only() -> None:
27 | """Test formatting plain text content"""
28 | content = "Hello world"
29 | formatted = format_content(content)
30 | assert formatted == "Hello world"
31 |
32 |
33 | def test_format_content_single_image() -> None:
34 | """Test formatting content with a single image"""
35 | content = [{"type": "image_url", "image_url": {"url": "test.jpg"}}]
36 | formatted = format_content(content)
37 | assert '
None:
42 | """Test formatting content with text and images"""
43 | content = [
44 | {"type": "text", "text": "Here's an image:"},
45 | {"type": "image_url", "image_url": {"url": "test.jpg"}},
46 | ]
47 | formatted = format_content(content)
48 | assert "Here's an image:" in formatted
49 | assert ' None:
54 | """Test getting MIME type from GCS blob"""
55 | mock_blob = MagicMock()
56 | mock_blob.content_type = "image/jpeg"
57 | mock_bucket = MagicMock()
58 | mock_bucket.blob.return_value = mock_blob
59 | mock_storage_client.return_value.bucket.return_value = mock_bucket
60 |
61 | mime_type = get_gcs_blob_mime_type("gs://bucket/test.jpg")
62 | assert mime_type == "image/jpeg"
63 |
64 |
65 | def test_gs_uri_to_https_url() -> None:
66 | """Test converting GCS URI to HTTPS URL"""
67 | gs_uri = "gs://bucket/folder/file.jpg"
68 | https_url = gs_uri_to_https_url(gs_uri)
69 | assert https_url == "https://storage.mtls.cloud.google.com/bucket/folder/file.jpg"
70 |
71 |
72 | def test_gs_uri_to_https_url_invalid() -> None:
73 | """Test converting invalid GCS URI"""
74 | with pytest.raises(ValueError):
75 | gs_uri_to_https_url("invalid_uri")
76 |
--------------------------------------------------------------------------------
/agent_starter_pack/base_template/deployment/terraform/{% if cookiecutter.cicd_runner == 'github_actions' %}wif.tf{% else %}unused_wif.tf{% endif %}:
--------------------------------------------------------------------------------
1 |
2 | data "google_project" "cicd_project" {
3 | project_id = var.cicd_runner_project_id
4 | }
5 |
6 | resource "google_service_account_iam_member" "github_oidc_access" {
7 | service_account_id = resource.google_service_account.cicd_runner_sa.name
8 | role = "roles/iam.workloadIdentityUser"
9 | member = "principalSet://iam.googleapis.com/projects/${data.google_project.cicd_project.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.github_pool.workload_identity_pool_id}/attribute.repository/${var.repository_owner}/${var.repository_name}"
10 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
11 | }
12 |
13 | # Allow the GitHub Actions principal to impersonate the CICD runner service account
14 | resource "google_service_account_iam_member" "github_sa_impersonation" {
15 | service_account_id = resource.google_service_account.cicd_runner_sa.name
16 | role = "roles/iam.serviceAccountTokenCreator"
17 | member = "principalSet://iam.googleapis.com/projects/${data.google_project.cicd_project.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.github_pool.workload_identity_pool_id}/attribute.repository/${var.repository_owner}/${var.repository_name}"
18 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
19 | }
20 |
21 | resource "google_iam_workload_identity_pool" "github_pool" {
22 | workload_identity_pool_id = "${var.project_name}-pool"
23 | project = var.cicd_runner_project_id
24 | display_name = "GitHub Actions Pool"
25 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
26 | }
27 |
28 | resource "google_iam_workload_identity_pool_provider" "github_provider" {
29 | workload_identity_pool_provider_id = "${var.project_name}-oidc"
30 | project = var.cicd_runner_project_id
31 | workload_identity_pool_id = google_iam_workload_identity_pool.github_pool.workload_identity_pool_id
32 | display_name = "GitHub OIDC Provider"
33 | oidc {
34 | issuer_uri = "https://token.actions.githubusercontent.com"
35 | }
36 | attribute_mapping = {
37 | "google.subject" = "assertion.sub"
38 | "attribute.repository" = "assertion.repository"
39 | "attribute.repository_owner" = "assertion.repository_owner"
40 | }
41 | attribute_condition = "attribute.repository == '${var.repository_owner}/${var.repository_name}'"
42 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
43 | }
44 |
--------------------------------------------------------------------------------
/agent_starter_pack/base_template/deployment/terraform/dev/log_sinks.tf:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | resource "google_project_iam_member" "bigquery_data_editor" {
16 |
17 | project = var.dev_project_id
18 | role = "roles/bigquery.dataEditor"
19 | member = module.log_export_to_bigquery.writer_identity
20 | }
21 |
22 | resource "google_bigquery_dataset" "feedback_dataset" {
23 | project = var.dev_project_id
24 | dataset_id = replace("${var.project_name}_feedback", "-", "_")
25 | friendly_name = "${var.project_name}_feedback"
26 | location = var.region
27 | depends_on = [resource.google_project_service.services]
28 | }
29 |
30 | resource "google_bigquery_dataset" "telemetry_logs_dataset" {
31 | project = var.dev_project_id
32 | dataset_id = replace("${var.project_name}_telemetry", "-", "_")
33 | friendly_name = "${var.project_name}_telemetry"
34 | location = var.region
35 | depends_on = [resource.google_project_service.services]
36 | }
37 |
38 | module "feedback_export_to_bigquery" {
39 | source = "terraform-google-modules/log-export/google"
40 | version = "10.0.0"
41 | log_sink_name = "${var.project_name}_feedback"
42 | parent_resource_type = "project"
43 | parent_resource_id = var.dev_project_id
44 | destination_uri = "bigquery.googleapis.com/projects/${var.dev_project_id}/datasets/${google_bigquery_dataset.feedback_dataset.dataset_id}"
45 | filter = var.feedback_logs_filter
46 | bigquery_options = { use_partitioned_tables = true }
47 | unique_writer_identity = true
48 | depends_on = [google_bigquery_dataset.feedback_dataset]
49 | }
50 |
51 | module "log_export_to_bigquery" {
52 | source = "terraform-google-modules/log-export/google"
53 | version = "10.0.0"
54 |
55 | log_sink_name = "${var.project_name}_telemetry"
56 | parent_resource_type = "project"
57 | parent_resource_id = var.dev_project_id
58 | destination_uri = "bigquery.googleapis.com/projects/${var.dev_project_id}/datasets/${google_bigquery_dataset.telemetry_logs_dataset.dataset_id}"
59 | filter = var.telemetry_logs_filter
60 | bigquery_options = { use_partitioned_tables = true }
61 | unique_writer_identity = true
62 | depends_on = [google_bigquery_dataset.telemetry_logs_dataset]
63 | }
64 |
--------------------------------------------------------------------------------
/tests/fixtures/makefile_snapshots/adk_base_agent_engine_no_data.makefile:
--------------------------------------------------------------------------------
1 | # ==============================================================================
2 | # Installation & Setup
3 | # ==============================================================================
4 |
5 | # Install dependencies using uv package manager
6 | install:
7 | @command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh; source $HOME/.local/bin/env; }
8 | uv sync --dev
9 |
10 | # ==============================================================================
11 | # Playground Targets
12 | # ==============================================================================
13 |
14 | # Launch local dev playground
15 | playground:
16 | @echo "==============================================================================="
17 | @echo "| 🚀 Starting your agent playground... |"
18 | @echo "| |"
19 | @echo "| 💡 Try asking: What can you help me with?|"
20 | @echo "| |"
21 | @echo "| 🔍 IMPORTANT: Select the 'test_adk_base' folder to interact with your agent. |"
22 | @echo "==============================================================================="
23 | uv run adk web . --port 8501 --reload_agents
24 |
25 | # ==============================================================================
26 | # Backend Deployment Targets
27 | # ==============================================================================
28 |
29 | # Deploy the agent remotely
30 | backend:
31 | # Export dependencies to requirements file using uv export.
32 | uv export --no-hashes --no-header --no-dev --no-emit-project --no-annotate > .requirements.txt 2>/dev/null || \
33 | uv export --no-hashes --no-header --no-dev --no-emit-project > .requirements.txt && uv run test_adk_base/agent_engine_app.py
34 |
35 |
36 | # ==============================================================================
37 | # Infrastructure Setup
38 | # ==============================================================================
39 |
40 | # Set up development environment resources using Terraform
41 | setup-dev-env:
42 | PROJECT_ID=$$(gcloud config get-value project) && \
43 | (cd deployment/terraform/dev && terraform init && terraform apply --var-file vars/env.tfvars --var dev_project_id=$$PROJECT_ID --auto-approve)
44 |
45 | # ==============================================================================
46 | # Testing & Code Quality
47 | # ==============================================================================
48 |
49 | # Run unit and integration tests
50 | test:
51 | uv run pytest tests/unit && uv run pytest tests/integration
52 |
53 | # Run code quality checks (codespell, ruff, mypy)
54 | lint:
55 | uv sync --dev --extra lint
56 | uv run codespell
57 | uv run ruff check . --diff
58 | uv run ruff format . --check --diff
59 | uv run mypy .
60 |
--------------------------------------------------------------------------------
/tests/fixtures/makefile_snapshots/agent_with_custom_commands.makefile:
--------------------------------------------------------------------------------
1 | # ==============================================================================
2 | # Installation & Setup
3 | # ==============================================================================
4 |
5 | # Install dependencies using uv package manager
6 | install:
7 | @command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh; source $HOME/.local/bin/env; }
8 | echo 'Custom install command'
9 |
10 | # ==============================================================================
11 | # Playground Targets
12 | # ==============================================================================
13 |
14 | # Launch local dev playground
15 | playground:
16 | echo 'Custom playground'
17 |
18 | # ==============================================================================
19 | # Agent-Specific Commands
20 | # ==============================================================================
21 |
22 | # Run a custom task
23 | custom-task:
24 | echo 'Running custom task'
25 |
26 | # Task with deployment-specific commands
27 | env-specific-task:
28 | echo 'Cloud Run task'
29 |
30 | # ==============================================================================
31 | # Backend Deployment Targets
32 | # ==============================================================================
33 |
34 | # Deploy the agent remotely
35 | # Usage: make backend [IAP=true] [PORT=8080] - Set IAP=true to enable Identity-Aware Proxy, PORT to specify container port
36 | backend:
37 | PROJECT_ID=$$(gcloud config get-value project) && \
38 | gcloud beta run deploy test-custom \
39 | --source . \
40 | --memory "4Gi" \
41 | --project $$PROJECT_ID \
42 | --region "us-central1" \
43 | --no-allow-unauthenticated \
44 | --no-cpu-throttling \
45 | --labels "" \
46 | --set-env-vars \
47 | "COMMIT_SHA=$(shell git rev-parse HEAD)" \
48 | $(if $(IAP),--iap) \
49 | $(if $(PORT),--port=$(PORT))
50 |
51 |
52 | # ==============================================================================
53 | # Infrastructure Setup
54 | # ==============================================================================
55 |
56 | # Set up development environment resources using Terraform
57 | setup-dev-env:
58 | PROJECT_ID=$$(gcloud config get-value project) && \
59 | (cd deployment/terraform/dev && terraform init && terraform apply --var-file vars/env.tfvars --var dev_project_id=$$PROJECT_ID --auto-approve)
60 |
61 | # ==============================================================================
62 | # Testing & Code Quality
63 | # ==============================================================================
64 |
65 | # Run unit and integration tests
66 | test:
67 | uv run pytest tests/unit && uv run pytest tests/integration
68 |
69 | # Run code quality checks (codespell, ruff, mypy)
70 | lint:
71 | uv sync --dev --extra lint
72 | uv run codespell
73 | uv run ruff check . --diff
74 | uv run ruff format . --check --diff
75 | uv run mypy .
76 |
--------------------------------------------------------------------------------
/docs/guide/troubleshooting.md:
--------------------------------------------------------------------------------
1 | # Troubleshooting
2 |
3 | This guide helps resolve common issues with the Agent Starter Pack.
4 |
5 | ## Authentication Issues
6 |
7 | For detailed information on authentication with Vertex AI, visit the [official documentation](https://cloud.google.com/vertex-ai/docs/authentication).
8 |
9 | ### "Could not find credentials" or "Could not find project" Error
10 |
11 | **Problem**: Missing credentials error with Vertex AI.
12 |
13 | **Solution**:
14 |
15 | 1. Log in to Google Cloud: `gcloud auth login --update-adc`
16 | 2. Set the correct project:
17 | ```bash
18 | gcloud config set project YOUR_PROJECT_ID
19 | gcloud auth application-default set-quota-project YOUR_PROJECT_ID
20 | ```
21 |
22 | ### Vertex AI API Not Enabled
23 |
24 | **Problem**: Operations fail because the Vertex AI API is not enabled in your project.
25 |
26 | **Solution**:
27 |
28 | 1. Enable the Vertex AI API:
29 | ```bash
30 | gcloud services enable aiplatform.googleapis.com
31 | ```
32 |
33 | 2. Verify the API is enabled:
34 | ```bash
35 | gcloud services list --filter=aiplatform.googleapis.com
36 | ```
37 |
38 | ### Permission Denied Errors
39 | **Problem**: "Permission denied" errors with Google Cloud APIs.
40 |
41 | **Solution**: Ensure your user or service account has the necessary IAM roles. For example, for Vertex AI, you often need `roles/aiplatform.user`. Grant roles using the `gcloud projects add-iam-policy-binding` command or the Cloud Console.
42 |
43 | ### Command Not Found: agent-starter-pack
44 |
45 | **Problem**: "Command not found" error after installation.
46 |
47 | **Solution**:
48 |
49 | 1. Verify installation:
50 | ```bash
51 | pip list | grep agent-starter-pack
52 | ```
53 | 2. Check PATH:
54 | ```bash
55 | echo $PATH
56 | ```
57 | 3. Reinstall if needed:
58 | ```bash
59 | pip install --user agent-starter-pack
60 | ```
61 | 4. For pipx:
62 | ```bash
63 | pipx ensurepath
64 | source ~/.bashrc # or ~/.zshrc
65 | ```
66 |
67 | ## Project Creation Issues
68 |
69 | ### Project Creation Fails
70 |
71 | **Problem**: `agent-starter-pack create` fails.
72 |
73 | **Solution**:
74 |
75 | 1. **Check Error Messages:** Examine output for clues.
76 | 2. **Write Permissions:** Ensure write access to the directory.
77 | 3. **Project Name:** Use lowercase letters, numbers and hyphens only.
78 | 4. **Debug Mode:** Consider using debug mode to get more detailed error information:
79 | ```bash
80 | agent-starter-pack create my-project-name --debug
81 | ```
82 |
83 | ### Issues with Agent Engine
84 |
85 | Consider leveraging the [public product documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/troubleshooting/set-up)
86 |
87 | ## Getting More Help
88 |
89 | If issues persist:
90 |
91 | 1. **Check GitHub Issues:** Search for existing Github issues in the `agent-starter-pack` Github repository.
92 | 2. **File a New Issue:** Provide:
93 |
94 | * Problem description.
95 | * Steps to reproduce.
96 | * Error messages (preferably run with `--debug` flag for detailed logs).
97 | * Environment: OS, Python version, `agent-starter-pack` version, installation method, shell.
98 |
--------------------------------------------------------------------------------
/tests/test_frontend/test_utils/test_local_chat_history.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | from pathlib import Path
16 |
17 | import pytest
18 | import yaml
19 |
20 | from frontend.utils.local_chat_history import LocalChatMessageHistory
21 |
22 |
23 | @pytest.fixture
24 | def chat_history(tmp_path: Path) -> LocalChatMessageHistory:
25 | """Create a temporary chat history instance"""
26 | return LocalChatMessageHistory(
27 | user_id="test_user", session_id="test_session", base_dir=str(tmp_path)
28 | )
29 |
30 |
31 | def test_init_creates_directory(tmp_path: Path) -> None:
32 | """Test directory creation on initialization"""
33 | user_dir = tmp_path / "test_user"
34 | assert not user_dir.exists()
35 |
36 | LocalChatMessageHistory(
37 | user_id="test_user", session_id="test_session", base_dir=str(tmp_path)
38 | )
39 |
40 | assert user_dir.exists()
41 |
42 |
43 | def test_get_session(chat_history: LocalChatMessageHistory) -> None:
44 | """Test session ID and file path update"""
45 | chat_history.get_session("new_session")
46 | assert chat_history.session_id == "new_session"
47 | assert chat_history.session_file.endswith("new_session.yaml")
48 |
49 |
50 | def test_upsert_session(chat_history: LocalChatMessageHistory) -> None:
51 | """Test session update/insert"""
52 | session = {
53 | "title": "Test Chat",
54 | "messages": [
55 | {"type": "human", "content": "Hello"},
56 | {"type": "ai", "content": "Hi there"},
57 | ],
58 | }
59 |
60 | chat_history.upsert_session(session)
61 |
62 | # Verify file was created
63 | assert Path(chat_history.session_file).exists()
64 |
65 | # Verify content
66 | with open(chat_history.session_file, encoding="utf-8") as f:
67 | saved_data = yaml.safe_load(f)
68 | assert len(saved_data) == 1
69 | assert saved_data[0]["title"] == "Test Chat"
70 | assert len(saved_data[0]["messages"]) == 2
71 |
72 |
73 | def test_get_all_conversations(chat_history: LocalChatMessageHistory) -> None:
74 | """Test retrieving all conversations"""
75 | # Create some test conversations
76 | sessions = {
77 | "session1": {"title": "Chat 1", "messages": []},
78 | "session2": {"title": "Chat 2", "messages": []},
79 | }
80 |
81 | for session_id, session in sessions.items():
82 | chat_history.get_session(session_id)
83 | chat_history.upsert_session(session)
84 |
85 | conversations = chat_history.get_all_conversations()
86 | assert len(conversations) == 2
87 | assert "session1" in conversations
88 | assert "session2" in conversations
89 |
--------------------------------------------------------------------------------
/tests/unit/README_MAKEFILE_TESTS.md:
--------------------------------------------------------------------------------
1 | # Makefile Template Test Suite
2 |
3 | Regression tests for `agent-starter-pack/base_template/Makefile` template refactoring. Ensures changes don't alter generated output across agent types, deployment targets, and feature combinations.
4 |
5 | ## Coverage
6 |
7 | Tests 9 configurations: ADK Base/Live (Cloud Run/Agent Engine), Agentic RAG (Vertex AI/Vector Search), LangGraph, Custom Commands, Agent Garden.
8 |
9 | ## Running Tests
10 |
11 | ```bash
12 | # All tests
13 | uv run pytest tests/unit/test_makefile_template.py -v
14 |
15 | # Specific categories (use -k filter)
16 | uv run pytest tests/unit/test_makefile_template.py -v -k "test_makefile_hash" # Fastest
17 | uv run pytest tests/unit/test_makefile_template.py -v -k "test_makefile_snapshot" # With diffs
18 | uv run pytest tests/unit/test_makefile_template.py -v -k "test_adk_live" # Specific feature
19 | ```
20 |
21 | ## Refactoring Workflow
22 |
23 | 1. Run tests before changes (verify baseline)
24 | 2. Make incremental changes to `agent-starter-pack/base_template/Makefile`
25 | 3. Run tests frequently to catch issues
26 | 4. Verify all tests pass after refactoring
27 |
28 | ## Test Failures
29 |
30 | **Snapshot failure**: Generated Makefile changed. Review diff with `git diff tests/fixtures/makefile_snapshots/.makefile`. If intentional, delete snapshot and rerun.
31 |
32 | **Hash failure**: Content changed. If intentional, delete `tests/fixtures/makefile_hashes.json` and rerun.
33 |
34 | **Feature failure**: Required target missing. Check Jinja2 conditionals in template.
35 |
36 | ## Updating Baselines
37 |
38 | ```bash
39 | # All baselines
40 | rm -rf tests/fixtures/makefile_snapshots/*.makefile tests/fixtures/makefile_hashes.json
41 | uv run pytest tests/unit/test_makefile_template.py -v
42 |
43 | # Specific config
44 | rm tests/fixtures/makefile_snapshots/.makefile
45 | uv run pytest tests/unit/test_makefile_template.py::TestMakefileGeneration::test_makefile_snapshot[] -v
46 | ```
47 |
48 | ## Test Types
49 |
50 | - **Snapshot**: Full output diffs (`tests/fixtures/makefile_snapshots/`) - for debugging
51 | - **Hash**: SHA256 comparison (`tests/fixtures/makefile_hashes.json`) - for CI/CD speed
52 | - **Feature**: Target presence validation - for functionality verification
53 |
54 | ## Adding Configurations
55 |
56 | 1. Add to `TEST_CONFIGURATIONS` in `test_makefile_template.py`
57 | 2. Run tests to generate baseline: `uv run pytest tests/unit/test_makefile_template.py -v`
58 | 3. Verify snapshot: `cat tests/fixtures/makefile_snapshots/.makefile`
59 |
60 | ## CI/CD
61 |
62 | ```yaml
63 | - name: Test Makefile Template
64 | run: uv run pytest tests/unit/test_makefile_template.py -v
65 | ```
66 |
67 | ## Refactoring Tips
68 |
69 | - Make small, incremental changes
70 | - Run tests frequently
71 | - Use Jinja2 variables for reusability
72 | - Document complex conditionals
73 | - Group related targets by agent/deployment type
74 |
75 | ## Troubleshooting
76 |
77 | - **Slow tests**: Use hash tests (`-k "test_makefile_hash"`)
78 | - **Need diffs**: Use snapshot tests (`-k "test_makefile_snapshot"`)
79 | - **Jinja2 errors**: Check error message for line number
80 | - **Missing variables**: `StrictUndefined` is already enabled
81 |
--------------------------------------------------------------------------------
/agent_starter_pack/deployment_targets/agent_engine/tests/load_test/README.md:
--------------------------------------------------------------------------------
1 | {%- if cookiecutter.agent_name == "adk_live" %}
2 | # WebSocket Load Testing for Remote Agent Engine
3 |
4 | This directory provides a comprehensive load testing framework for your Agent Engine application using WebSocket connections, leveraging the power of [Locust](http://locust.io), a leading open-source load testing tool.
5 |
6 | The load test simulates realistic user interactions by:
7 | - Establishing WebSocket connections
8 | - Sending audio chunks in the proper `realtimeInput` format
9 | - Sending text messages to complete turns
10 | - Collecting and measuring responses until `turn_complete`
11 |
12 | ## Load Testing with Remote Agent Engine
13 |
14 | **1. Start the Expose App in Remote Mode:**
15 |
16 | Launch the expose app server in a separate terminal, pointing to your deployed agent engine:
17 |
18 | ```bash
19 | uv run python -m app.utils.expose_app --mode remote --remote-id
20 | ```
21 |
22 | Or if you have `deployment_metadata.json` in your project root:
23 |
24 | ```bash
25 | uv run python -m app.utils.expose_app --mode remote
26 | ```
27 |
28 | **2. Execute the Load Test:**
29 |
30 | Using another terminal tab, trigger the Locust load test:
31 |
32 | ```bash
33 | uv run --with locust==2.31.1 --with websockets locust -f tests/load_test/load_test.py \
34 | -H http://127.0.0.1:8000 \
35 | --headless \
36 | -t 30s -u 1 -r 1 \
37 | --csv=tests/load_test/.results/results \
38 | --html=tests/load_test/.results/report.html
39 | ```
40 |
41 | This command initiates a 30-second load test with 1 concurrent user.
42 |
43 | **Results:**
44 |
45 | Comprehensive CSV and HTML reports detailing the load test performance will be generated and saved in the `tests/load_test/.results` directory.
46 | {%- else %}
47 | # Robust Load Testing for Generative AI Applications
48 |
49 | This directory provides a comprehensive load testing framework for your Generative AI application, leveraging the power of [Locust](http://locust.io), a leading open-source load testing tool.
50 |
51 | ## Load Testing
52 |
53 | Before running load tests, ensure you have deployed the backend remotely.
54 |
55 | Follow these steps to execute load tests:
56 |
57 | **1. Deploy the Backend Remotely:**
58 | ```bash
59 | gcloud config set project
60 | make backend
61 | ```
62 |
63 | **2. Create a Virtual Environment for Locust:**
64 | It's recommended to use a separate terminal tab and create a virtual environment for Locust to avoid conflicts with your application's Python environment.
65 |
66 | ```bash
67 | python3 -m venv .locust_env && source .locust_env/bin/activate && pip install locust==2.31.1
68 | ```
69 |
70 | **3. Execute the Load Test:**
71 | Trigger the Locust load test with the following command:
72 |
73 | ```bash
74 | export _AUTH_TOKEN=$(gcloud auth print-access-token -q)
75 | locust -f tests/load_test/load_test.py \
76 | --headless \
77 | -t 30s -u 5 -r 2 \
78 | --csv=tests/load_test/.results/results \
79 | --html=tests/load_test/.results/report.html
80 | ```
81 |
82 | This command initiates a 30-second load test, simulating 2 users spawning per second, reaching a maximum of 10 concurrent users.
83 | {%- endif %}
84 |
85 |
--------------------------------------------------------------------------------
/tests/fixtures/makefile_snapshots/langgraph_cloud_run_no_data.makefile:
--------------------------------------------------------------------------------
1 | # ==============================================================================
2 | # Installation & Setup
3 | # ==============================================================================
4 |
5 | # Install dependencies using uv package manager
6 | install:
7 | @command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh; source $HOME/.local/bin/env; }
8 | uv sync --dev --extra streamlit
9 |
10 | # ==============================================================================
11 | # Playground Targets
12 | # ==============================================================================
13 |
14 | # Launch local dev playground
15 | playground:
16 | @echo "==============================================================================="
17 | @echo "| 🚀 Starting your agent playground... |"
18 | @echo "| |"
19 | @echo "| 💡 Try asking: How can you help?|"
20 | @echo "==============================================================================="
21 | uv run uvicorn test_langgraph.server:app --host localhost --port 8000 --reload &
22 | uv run streamlit run frontend/streamlit_app.py --browser.serverAddress=localhost --server.enableCORS=false --server.enableXsrfProtection=false
23 |
24 | # ==============================================================================
25 | # Backend Deployment Targets
26 | # ==============================================================================
27 |
28 | # Deploy the agent remotely
29 | # Usage: make backend [IAP=true] [PORT=8080] - Set IAP=true to enable Identity-Aware Proxy, PORT to specify container port
30 | backend:
31 | PROJECT_ID=$$(gcloud config get-value project) && \
32 | gcloud beta run deploy test-langgraph \
33 | --source . \
34 | --memory "4Gi" \
35 | --project $$PROJECT_ID \
36 | --region "us-central1" \
37 | --no-allow-unauthenticated \
38 | --no-cpu-throttling \
39 | --labels "" \
40 | --set-env-vars \
41 | "COMMIT_SHA=$(shell git rev-parse HEAD)" \
42 | $(if $(IAP),--iap) \
43 | $(if $(PORT),--port=$(PORT))
44 |
45 |
46 | # ==============================================================================
47 | # Infrastructure Setup
48 | # ==============================================================================
49 |
50 | # Set up development environment resources using Terraform
51 | setup-dev-env:
52 | PROJECT_ID=$$(gcloud config get-value project) && \
53 | (cd deployment/terraform/dev && terraform init && terraform apply --var-file vars/env.tfvars --var dev_project_id=$$PROJECT_ID --auto-approve)
54 |
55 | # ==============================================================================
56 | # Testing & Code Quality
57 | # ==============================================================================
58 |
59 | # Run unit and integration tests
60 | test:
61 | uv run pytest tests/unit && uv run pytest tests/integration
62 |
63 | # Run code quality checks (codespell, ruff, mypy)
64 | lint:
65 | uv sync --dev --extra lint
66 | uv run codespell
67 | uv run ruff check . --diff
68 | uv run ruff format . --check --diff
69 | uv run mypy .
70 |
--------------------------------------------------------------------------------
/agent_starter_pack/base_template/deployment/terraform/log_sinks.tf:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | resource "google_project_iam_member" "bigquery_data_editor" {
16 | for_each = local.deploy_project_ids
17 |
18 | project = each.value
19 | role = "roles/bigquery.dataEditor"
20 | member = module.log_export_to_bigquery[each.key].writer_identity
21 | }
22 |
23 | resource "google_bigquery_dataset" "feedback_dataset" {
24 | for_each = local.deploy_project_ids
25 | project = each.value
26 | dataset_id = replace("${var.project_name}_feedback", "-", "_")
27 | friendly_name = "${var.project_name}_feedback"
28 | location = var.region
29 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
30 | }
31 |
32 | resource "google_bigquery_dataset" "telemetry_logs_dataset" {
33 | for_each = local.deploy_project_ids
34 | project = each.value
35 | dataset_id = replace("${var.project_name}_telemetry", "-", "_")
36 | friendly_name = "${var.project_name}_telemetry"
37 | location = var.region
38 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
39 | }
40 |
41 | module "log_export_to_bigquery" {
42 | for_each = local.deploy_project_ids
43 |
44 | source = "terraform-google-modules/log-export/google"
45 | version = "10.0.0"
46 |
47 | log_sink_name = "${var.project_name}_telemetry"
48 | parent_resource_type = "project"
49 | parent_resource_id = each.value
50 | destination_uri = "bigquery.googleapis.com/projects/${each.value}/datasets/${google_bigquery_dataset.telemetry_logs_dataset[each.key].dataset_id}"
51 | filter = var.telemetry_logs_filter
52 | bigquery_options = { use_partitioned_tables = true }
53 | unique_writer_identity = true
54 | depends_on = [google_bigquery_dataset.telemetry_logs_dataset]
55 | }
56 |
57 | module "feedback_export_to_bigquery" {
58 | for_each = local.deploy_project_ids
59 |
60 | source = "terraform-google-modules/log-export/google"
61 | version = "10.0.0"
62 | log_sink_name = "${var.project_name}_feedback"
63 | parent_resource_type = "project"
64 | parent_resource_id = each.value
65 | destination_uri = "bigquery.googleapis.com/projects/${each.value}/datasets/${google_bigquery_dataset.feedback_dataset[each.key].dataset_id}"
66 | filter = var.feedback_logs_filter
67 | bigquery_options = { use_partitioned_tables = true }
68 | unique_writer_identity = true
69 | depends_on = [google_bigquery_dataset.feedback_dataset]
70 | }
71 |
--------------------------------------------------------------------------------
/agent_starter_pack/cli/utils/version.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """Version checking utilities for the CLI."""
16 |
17 | import logging
18 | from importlib.metadata import PackageNotFoundError, version
19 |
20 | import requests
21 | from packaging import version as pkg_version
22 | from rich.console import Console
23 |
24 | console = Console()
25 |
26 | PACKAGE_NAME = "agent-starter-pack"
27 |
28 |
29 | def get_current_version() -> str:
30 | """Get the current installed version of the package."""
31 | try:
32 | return version(PACKAGE_NAME)
33 | except PackageNotFoundError:
34 | # For development environments where package isn't installed
35 | return "0.0.0" # Default if version can't be determined
36 |
37 |
38 | def get_latest_version() -> str:
39 | """Get the latest version available on PyPI."""
40 | try:
41 | response = requests.get(f"https://pypi.org/pypi/{PACKAGE_NAME}/json", timeout=2)
42 | if response.status_code == 200:
43 | return response.json()["info"]["version"]
44 | return "0.0.0"
45 | except Exception:
46 | return "0.0.0" # Default if PyPI can't be reached
47 |
48 |
49 | def check_for_updates() -> tuple[bool, str, str]:
50 | """Check if a newer version of the package is available.
51 |
52 | Returns:
53 | Tuple of (needs_update, current_version, latest_version)
54 | """
55 | current = get_current_version()
56 | latest = get_latest_version()
57 |
58 | needs_update = pkg_version.parse(latest) > pkg_version.parse(current)
59 |
60 | return needs_update, current, latest
61 |
62 |
63 | def display_update_message() -> None:
64 | """Check for updates and display a message if an update is available."""
65 | try:
66 | needs_update, current, latest = check_for_updates()
67 |
68 | if needs_update:
69 | console.print(
70 | f"\n[yellow]⚠️ Update available: {current} → {latest}[/]",
71 | highlight=False,
72 | )
73 | console.print(
74 | f"[yellow]Run `pip install --upgrade {PACKAGE_NAME}` to update.",
75 | highlight=False,
76 | )
77 | console.print(
78 | f"[yellow]Or, if you used pipx: `pipx upgrade {PACKAGE_NAME}`",
79 | highlight=False,
80 | )
81 | console.print(
82 | f"[yellow]Or, if you used uv: `uv pip install --upgrade {PACKAGE_NAME}`",
83 | highlight=False,
84 | )
85 | except Exception as e:
86 | # Don't let version checking errors affect the CLI
87 | logging.debug(f"Error checking for updates: {e}")
88 |
--------------------------------------------------------------------------------
/tests/fixtures/makefile_snapshots/adk_base_cloud_run_no_data.makefile:
--------------------------------------------------------------------------------
1 | # ==============================================================================
2 | # Installation & Setup
3 | # ==============================================================================
4 |
5 | # Install dependencies using uv package manager
6 | install:
7 | @command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh; source $HOME/.local/bin/env; }
8 | uv sync --dev
9 |
10 | # ==============================================================================
11 | # Playground Targets
12 | # ==============================================================================
13 |
14 | # Launch local dev playground
15 | playground:
16 | @echo "==============================================================================="
17 | @echo "| 🚀 Starting your agent playground... |"
18 | @echo "| |"
19 | @echo "| 💡 Try asking: What can you help me with?|"
20 | @echo "| |"
21 | @echo "| 🔍 IMPORTANT: Select the 'test_adk_base' folder to interact with your agent. |"
22 | @echo "==============================================================================="
23 | uv run adk web . --port 8501 --reload_agents
24 |
25 | # ==============================================================================
26 | # Backend Deployment Targets
27 | # ==============================================================================
28 |
29 | # Deploy the agent remotely
30 | # Usage: make backend [IAP=true] [PORT=8080] - Set IAP=true to enable Identity-Aware Proxy, PORT to specify container port
31 | backend:
32 | PROJECT_ID=$$(gcloud config get-value project) && \
33 | gcloud beta run deploy test-adk-base \
34 | --source . \
35 | --memory "4Gi" \
36 | --project $$PROJECT_ID \
37 | --region "us-central1" \
38 | --no-allow-unauthenticated \
39 | --no-cpu-throttling \
40 | --labels "created-by=adk" \
41 | --set-env-vars \
42 | "COMMIT_SHA=$(shell git rev-parse HEAD)" \
43 | $(if $(IAP),--iap) \
44 | $(if $(PORT),--port=$(PORT))
45 |
46 |
47 | # ==============================================================================
48 | # Infrastructure Setup
49 | # ==============================================================================
50 |
51 | # Set up development environment resources using Terraform
52 | setup-dev-env:
53 | PROJECT_ID=$$(gcloud config get-value project) && \
54 | (cd deployment/terraform/dev && terraform init && terraform apply --var-file vars/env.tfvars --var dev_project_id=$$PROJECT_ID --auto-approve)
55 |
56 | # ==============================================================================
57 | # Testing & Code Quality
58 | # ==============================================================================
59 |
60 | # Run unit and integration tests
61 | test:
62 | uv run pytest tests/unit && uv run pytest tests/integration
63 |
64 | # Run code quality checks (codespell, ruff, mypy)
65 | lint:
66 | uv sync --dev --extra lint
67 | uv run codespell
68 | uv run ruff check . --diff
69 | uv run ruff format . --check --diff
70 | uv run mypy .
71 |
--------------------------------------------------------------------------------
/tests/cli/utils/test_cicd.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """Tests for CI/CD utility functions."""
16 |
17 | from unittest.mock import MagicMock, patch
18 |
19 | import pytest
20 | from cli.utils.cicd import ProjectConfig, print_cicd_summary, run_command
21 |
22 |
23 | @pytest.fixture
24 | def mock_console() -> MagicMock:
25 | """Mock console for testing output"""
26 | with patch("cli.utils.cicd.console") as mock:
27 | yield mock
28 |
29 |
30 | @pytest.fixture
31 | def mock_run_command() -> MagicMock:
32 | """Mock run_command function"""
33 | with patch("agent_starter_pack.cli.utils.cicd.run_command") as mock:
34 | yield mock
35 |
36 |
37 | def test_project_config() -> None:
38 | """Test ProjectConfig initialization with minimal required fields"""
39 | config = ProjectConfig(
40 | staging_project_id="test-staging",
41 | prod_project_id="test-prod",
42 | cicd_project_id="test-cicd",
43 | agent="test-agent",
44 | deployment_target="cloud-run",
45 | repository_name="test-repo",
46 | repository_owner="test-owner",
47 | dev_project_id="test-dev",
48 | )
49 |
50 | assert config.dev_project_id == "test-dev"
51 | assert config.region == "us-central1" # default value
52 | assert config.git_provider == "github" # default value
53 |
54 |
55 | def test_print_cicd_summary(mock_console: MagicMock) -> None:
56 | """Test CICD summary printing"""
57 | config = ProjectConfig(
58 | staging_project_id="test-staging",
59 | prod_project_id="test-prod",
60 | cicd_project_id="test-cicd",
61 | agent="test-agent",
62 | deployment_target="cloud-run",
63 | repository_name="test-repo",
64 | repository_owner="test-owner",
65 | dev_project_id="test-dev",
66 | )
67 |
68 | print_cicd_summary(
69 | config=config,
70 | github_username="test-user",
71 | repo_url="https://github.com/test-user/test-repo",
72 | cloud_build_url="https://console.cloud.google.com/cloud-build/builds?project=test-cicd",
73 | )
74 |
75 | # Verify specific expected messages were printed
76 | assert mock_console.print.call_count > 0
77 |
78 |
79 | def test_run_command(capsys: pytest.CaptureFixture) -> None:
80 | """Test run_command output formatting"""
81 | with patch("subprocess.run") as mock_run:
82 | mock_run.return_value = MagicMock(returncode=0, stdout="test output", stderr="")
83 |
84 | result = run_command(["test", "command"], capture_output=True)
85 |
86 | captured = capsys.readouterr()
87 | assert "🔄 Running command: test command" in captured.out
88 | assert result.stdout == "test output"
89 |
--------------------------------------------------------------------------------
/docs/guide/getting-started.md:
--------------------------------------------------------------------------------
1 | # 🚀 Getting Started
2 |
3 | This guide quickly walks you through setting up your first agent project.
4 |
5 | **Want zero setup?** 👉 [Try 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 in [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)
6 |
7 | ### Prerequisites
8 |
9 | **Python 3.10+** | **Google Cloud SDK** [Install Guide](https://cloud.google.com/sdk/docs/install) | **Terraform** [Install Guide](https://developer.hashicorp.com/terraform/downloads) | **`uv` (Optional, Recommended)** [Install Guide](https://docs.astral.sh/uv/getting-started/installation/)
10 |
11 | ### 1. Create Your Agent Project
12 |
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.
14 |
15 | ::: code-group
16 |
17 | ```bash [pip]
18 | # 1. Create and activate a virtual environment
19 | python -m venv .venv
20 | source .venv/bin/activate
21 |
22 | # 2. Install the package
23 | pip install agent-starter-pack
24 |
25 | # 3. Run the create command
26 | agent-starter-pack create my-awesome-agent
27 | ```
28 |
29 | ```bash [⚡ uvx]
30 | # This single command downloads and runs the latest version
31 | uvx agent-starter-pack create my-awesome-agent
32 | ```
33 |
34 | :::
35 |
36 | No matter which method you choose, the `create` command will:
37 | * Let you choose an agent template (e.g., `adk_base`, `agentic_rag`).
38 | * Let you select a deployment target (e.g., `cloud_run`, `agent_engine`).
39 | * Generate a complete project structure (backend, optional frontend, deployment infra).
40 |
41 | **Examples:**
42 |
43 | ```bash
44 | # You can also pass flags to skip the prompts
45 | agent-starter-pack create my-adk-agent -a adk_base -d agent_engine
46 | ```
47 |
48 | ### 2. Explore and Run Locally
49 |
50 | Now, navigate into your new project and run its setup commands.
51 |
52 | ```bash
53 | cd my-awesome-agent && make install && make playground
54 | ```
55 |
56 | Inside your new project directory (`my-awesome-agent`), you'll find:
57 |
58 | * `app/`: Backend agent code (or custom directory name if configured).
59 | * `deployment/`: Terraform infrastructure code.
60 | * `tests/`: Unit and integration tests for your agent.
61 | * `notebooks/`: Jupyter notebooks for getting started with evaluation.
62 | * `frontend/`: (If applicable) Web UI for interacting with your agent.
63 | * `README.md`: **Project-specific instructions for running locally and deploying.**
64 |
65 | ➡️ **Follow the instructions in *your new project's* `README.md` to run it locally.**
66 |
67 | ### Next Steps
68 |
69 | You're ready to go! See the [Development Guide](/guide/development-guide) for detailed instructions on extending, customizing and deploying your agent.
70 |
71 | - **Add Data (RAG):** Configure [Data Ingestion](/guide/data-ingestion) for knowledge-based agents.
72 | - **Monitor Performance:** Explore [Observability](/guide/observability) features for production monitoring.
73 | - **Deploy to Production:** Follow the [Deployment Guide](/guide/deployment) to deploy your agent to Google Cloud.
--------------------------------------------------------------------------------
/docs/guide/data-ingestion.md:
--------------------------------------------------------------------------------
1 | # Data Ingestion Pipeline for RAG
2 |
3 | The Agent Starter Pack simplifies incorporating data ingestion into your agent projects. This is especially useful for agents requiring document processing and retrieval, such as Retrieval Augmented Generation (RAG) applications.
4 |
5 | ## Overview
6 |
7 | Data ingestion automates:
8 |
9 | - Loading data from various sources.
10 | - Processing and chunking documents.
11 | - Generating embeddings with Vertex AI.
12 | - Storing processed data and embeddings in **Vertex AI Search** or **Vertex AI Vector Search**.
13 | - Scheduling periodic data updates.
14 |
15 | ## When to Include Data Ingestion
16 |
17 | Consider data ingestion if:
18 |
19 | - Your agent needs to search or reference extensive documentation.
20 | - You're developing a RAG-based application.
21 | - Your agent's knowledge base requires periodic updates.
22 | - You want to keep your agent's content fresh and searchable.
23 |
24 | ## Usage
25 |
26 | ### Project Creation
27 |
28 | Include data ingestion during project creation in two ways:
29 |
30 | 1. **Automatic Inclusion**: Some agents (e.g., those designed for RAG like `agentic_rag`) automatically include it due to their nature. You will be prompted to select a datastore (`vertex_ai_search` or `vertex_ai_vector_search`) if not specified.
31 |
32 | 2. **Optional Inclusion**: For other agents, add it using the `--include-data-ingestion` flag and specify the desired datastore with `--datastore` (or `-ds`):
33 |
34 | ```bash
35 | # Using Vertex AI Search
36 | agent-starter-pack create my-agent-project --include-data-ingestion -ds vertex_ai_search
37 |
38 | # Using Vertex AI Vector Search
39 | agent-starter-pack create my-agent-project --include-data-ingestion -ds vertex_ai_vector_search
40 | ```
41 | If `--datastore` is omitted when `--include-data-ingestion` is used, you will be prompted to choose one.
42 |
43 | ### Infrastructure Setup
44 |
45 | The Terraform IaC configures the necessary infrastructure based on your chosen datastore:
46 |
47 | - **Vertex AI Search**: Datastores.
48 | - **Vertex AI Vector Search**: Indexes, Index Endpoints, and Buckets for staging data.
49 | - Necessary service accounts and permissions.
50 | - Storage buckets for pipeline artifacts.
51 | - BigQuery datasets (if applicable).
52 |
53 | ## Getting Started
54 |
55 | 1. Create your project with data ingestion, specifying your datastore:
56 |
57 | ```bash
58 | # Example with Vertex AI Search
59 | agent-starter-pack create my-project -ds vertex_ai_search
60 |
61 | # Example with Vertex AI Vector Search
62 | agent-starter-pack create my-project -ds vertex_ai_vector_search
63 | ```
64 |
65 | 2. Follow the setup instructions in the generated `data_ingestion/README.md`. Deploy the Terraform infrastructure (at least in your development project) before running the data pipeline.
66 |
67 | ## Learn More
68 |
69 | - [Vertex AI Pipelines](https://cloud.google.com/vertex-ai/docs/pipelines/introduction) for pipeline management.
70 | - [Vertex AI Search documentation](https://cloud.google.com/generative-ai-app-builder/docs/enterprise-search-introduction) for search capabilities.
71 | - [Vertex AI Vector Search documentation](https://cloud.google.com/vertex-ai/docs/vector-search/overview) for vector database capabilities.
72 |
--------------------------------------------------------------------------------
/tests/fixtures/makefile_snapshots/agent_with_agent_garden.makefile:
--------------------------------------------------------------------------------
1 | # ==============================================================================
2 | # Installation & Setup
3 | # ==============================================================================
4 |
5 | # Install dependencies using uv package manager
6 | install:
7 | @command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh; source $HOME/.local/bin/env; }
8 | uv sync --dev
9 |
10 | # ==============================================================================
11 | # Playground Targets
12 | # ==============================================================================
13 |
14 | # Launch local dev playground
15 | playground:
16 | @echo "==============================================================================="
17 | @echo "| 🚀 Starting your agent playground... |"
18 | @echo "| |"
19 | @echo "| 💡 Try asking: Agent garden question|"
20 | @echo "| |"
21 | @echo "| 🔍 IMPORTANT: Select the 'test_garden' folder to interact with your agent. |"
22 | @echo "==============================================================================="
23 | uv run adk web . --port 8501 --reload_agents
24 |
25 | # ==============================================================================
26 | # Backend Deployment Targets
27 | # ==============================================================================
28 |
29 | # Deploy the agent remotely
30 | # Usage: make backend [IAP=true] [PORT=8080] - Set IAP=true to enable Identity-Aware Proxy, PORT to specify container port
31 | backend:
32 | PROJECT_ID=$$(gcloud config get-value project) && \
33 | gcloud beta run deploy test-garden \
34 | --source . \
35 | --memory "4Gi" \
36 | --project $$PROJECT_ID \
37 | --region "us-central1" \
38 | --no-allow-unauthenticated \
39 | --no-cpu-throttling \
40 | --labels "created-by=adk,deployed-with=agent-garden,vertex-agent-sample-id=sample-123,vertex-agent-sample-publisher=google" \
41 | --set-env-vars \
42 | "COMMIT_SHA=$(shell git rev-parse HEAD)" \
43 | $(if $(IAP),--iap) \
44 | $(if $(PORT),--port=$(PORT))
45 |
46 |
47 | # ==============================================================================
48 | # Infrastructure Setup
49 | # ==============================================================================
50 |
51 | # Set up development environment resources using Terraform
52 | setup-dev-env:
53 | PROJECT_ID=$$(gcloud config get-value project) && \
54 | (cd deployment/terraform/dev && terraform init && terraform apply --var-file vars/env.tfvars --var dev_project_id=$$PROJECT_ID --auto-approve)
55 |
56 | # ==============================================================================
57 | # Testing & Code Quality
58 | # ==============================================================================
59 |
60 | # Run unit and integration tests
61 | test:
62 | uv run pytest tests/unit && uv run pytest tests/integration
63 |
64 | # Run code quality checks (codespell, ruff, mypy)
65 | lint:
66 | uv sync --dev --extra lint
67 | uv run codespell
68 | uv run ruff check . --diff
69 | uv run ruff format . --check --diff
70 | uv run mypy .
71 |
--------------------------------------------------------------------------------
(lines.current[i] = el!)}
59 | style={{ animationDelay: `${i * 133}ms` }}
60 | />
61 | ))}
62 |
63 | );
64 | }
65 |
--------------------------------------------------------------------------------
/agent_starter_pack/resources/containers/e2e-tests/Dockerfile:
--------------------------------------------------------------------------------
1 | # Stage 1: Builder - Prepare APT repositories
2 | FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim AS builder
3 |
4 | # Install tools needed to add repositories
5 | RUN apt-get update && \
6 | apt-get install -y --no-install-recommends \
7 | ca-certificates \
8 | curl \
9 | gnupg && \
10 | # GitHub CLI
11 | curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyring.gpg && \
12 | echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list && \
13 | # Google Cloud SDK
14 | curl -sS https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg && \
15 | echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" > /etc/apt/sources.list.d/google-cloud-sdk.list && \
16 | # Terraform
17 | curl -fsSL https://apt.releases.hashicorp.com/gpg | gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg && \
18 | echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com bookworm main" > /etc/apt/sources.list.d/hashicorp.list && \
19 | # Clean up builder stage
20 | apt-get clean && \
21 | rm -rf /var/lib/apt/lists/*
22 |
23 | # Stage 2: Final Image
24 | FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim
25 |
26 | # Copy repository configurations from the builder stage
27 | COPY --from=builder /etc/apt/sources.list.d/ /etc/apt/sources.list.d/
28 | COPY --from=builder /usr/share/keyrings/ /usr/share/keyrings/
29 |
30 | # Install the final packages
31 | RUN apt-get update && \
32 | apt-get install -y --no-install-recommends \
33 | gh \
34 | google-cloud-cli \
35 | terraform \
36 | make \
37 | nodejs \
38 | npm && \
39 | # Clean up apt cache
40 | apt-get clean && \
41 | rm -rf /var/lib/apt/lists/*
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/adk_live_react/frontend/src/utils/store-logger.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2024 Google LLC
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 |
17 | import { create } from "zustand";
18 | import { StreamingLog } from "../multimodal-live-types";
19 |
20 | interface StoreLoggerState {
21 | maxLogs: number;
22 | logs: StreamingLog[];
23 | log: (streamingLog: StreamingLog) => void;
24 | clearLogs: () => void;
25 | }
26 |
27 | export const useLoggerStore = create
36 |
37 |
61 |
62 | );
63 | }
64 |
65 | export default App;
66 |
--------------------------------------------------------------------------------
/docs/guide/observability.md:
--------------------------------------------------------------------------------
1 | # Monitoring and Observability
2 |
3 | 
4 |
5 | ### Trace and Log Capture
6 |
7 | Templated agents utilize [OpenTelemetry](https://opentelemetry.io/) for comprehensive observability, emitting events to Google Cloud Trace and Google Cloud Logging. Every interaction with the LLM instrumented, enabling detailed tracing of request flows throughout agents built with this framework.
8 |
9 | Leveraging the [CloudTraceSpanExporter](https://cloud.google.com/python/docs/reference/spanner/latest/opentelemetry-tracing), the framework captures and exports tracing data. To address the limitations of Cloud Trace ([256-byte attribute value limit](https://cloud.google.com/trace/docs/quotas#limits_on_spans)) and [Cloud Logging](https://cloud.google.com/logging/quotas) ([256KB log entry size](https://cloud.google.com/logging/quotas)), a custom extension of the CloudTraceSpanExporter is implemented in `app/utils/tracing.py` of the templated project.
10 |
11 | This extension enhances observability by:
12 |
13 | - Creating a corresponding Google Cloud Logging entry for every captured event.
14 | - Automatically storing event data in Google Cloud Storage when the payload exceeds 256KB.
15 |
16 | Logged payloads are associated with the original trace, ensuring seamless access from the Cloud Trace console.
17 |
18 | ### Log Router
19 |
20 | Events are forwarded to BigQuery through a [log router](https://cloud.google.com/logging/docs/routing/overview) for long-term storage and analysis. The deployment of the log router is handled via Terraform code in `deployment/terraform` in the templated project.
21 |
22 | ### Looker Studio Dashboard
23 |
24 | Once the data is written to BigQuery, it can be used to populate a [Looker Studio dashboard](https://lookerstudio.google.com/c/reporting/46b35167-b38b-4e44-bd37-701ef4307418/page/tEnnC). Use [this dashboard](https://lookerstudio.google.com/c/reporting/fa742264-4b4b-4c56-81e6-a667dd0f853f/page/tEnnC) if using non-ADK agents.
25 |
26 | This dashboard template provides a starting point for building custom visualizations on top of the captured data.
27 |
28 | ## Disclaimer
29 |
30 | **Note:** The templated agents are designed to enable *your* use-case observability in your Google Cloud Project. Google Cloud does not log, monitor, or otherwise access any data generated from the deployed resources. See the [Google Cloud Service Terms](https://cloud.google.com/terms/service-terms) for more details.
31 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/streamlit/frontend/utils/chat_utils.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | import os
16 | from pathlib import Path
17 | from typing import Any
18 |
19 | import yaml
20 |
21 | SAVED_CHAT_PATH = str(os.getcwd()) + "/.saved_chats"
22 |
23 |
24 | def clean_text(text: str) -> str:
25 | """Preprocess the input text by removing leading and trailing newlines."""
26 | if not text:
27 | return text
28 |
29 | if text.startswith("\n"):
30 | text = text[1:]
31 | if text.endswith("\n"):
32 | text = text[:-1]
33 | return text
34 |
35 |
36 | def sanitize_messages(
37 | messages: list[dict[str, str | list[dict[str, str]]]],
38 | ) -> list[dict[str, str | list[dict[str, str]]]]:
39 | """Preprocess and fix the content of messages."""
40 | for message in messages:
41 | if isinstance(message["content"], list):
42 | for part in message["content"]:
43 | if part["type"] == "text":
44 | part["text"] = clean_text(part["text"])
45 | else:
46 | message["content"] = clean_text(message["content"])
47 | return messages
48 |
49 |
50 | def save_chat(st: Any) -> None:
51 | """Save the current chat session to a YAML file."""
52 | Path(SAVED_CHAT_PATH).mkdir(parents=True, exist_ok=True)
53 | session_id = st.session_state["session_id"]
54 | session = st.session_state.user_chats[session_id]
55 | messages = session.get("messages", [])
56 | if len(messages) > 0:
57 | session["messages"] = sanitize_messages(session["messages"])
58 | filename = f"{session_id}.yaml"
59 | with open(Path(SAVED_CHAT_PATH) / filename, "w", encoding="utf-8") as file:
60 | yaml.dump(
61 | [session],
62 | file,
63 | allow_unicode=True,
64 | default_flow_style=False,
65 | encoding="utf-8",
66 | )
67 | st.toast(f"Chat saved to path: ↓ {Path(SAVED_CHAT_PATH) / filename}")
68 |
--------------------------------------------------------------------------------
/docs/remote-templates/index.md:
--------------------------------------------------------------------------------
1 | # Remote Templates
2 |
3 | Remote templates turn your agent prototype into a production-ready starter pack. A remote template is a Git repository containing your custom agent logic, dependencies, and infrastructure definitions (Terraform). The `agent-starter-pack` CLI uses it to generate a complete, deployable application by automatically adding production-grade boilerplate for testing and multi-target deployment (e.g., Cloud Run, Agent Engine).
4 |
5 | ## Choose Your Path
6 |
7 | ### 🚀 Using Remote Templates
8 | **For developers who want to use existing templates**
9 |
10 | Use any Git repository as a template to create production-ready agents instantly. Perfect for getting started quickly or using community-created templates.
11 |
12 | **[👉 Go to Using Remote Templates Guide](./using-remote-templates.md)**
13 |
14 | Quick example:
15 | ```bash
16 | uvx agent-starter-pack create my-agent -a adk@gemini-fullstack
17 | ```
18 |
19 | ---
20 |
21 | ### 🛠️ Creating Remote Templates
22 | **For developers who want to share their own templates**
23 |
24 | Package your custom agent logic, dependencies, and infrastructure into reusable templates that others can use. Perfect for sharing best practices and creating standardized agent patterns.
25 |
26 | **[👉 Go to Creating Remote Templates Guide](./creating-remote-templates.md)**
27 |
28 | Quick example:
29 | ```bash
30 | # After creating your template repository
31 | uvx agent-starter-pack create test-agent -a https://github.com/you/your-template
32 | ```
33 |
34 | ---
35 |
36 | ## Overview
37 |
38 | Remote templates work by:
39 | 1. **Fetching** template repositories from Git
40 | 2. **Version locking** - automatically uses the exact starter pack version specified by the template for guaranteed compatibility
41 | 3. **Applying** intelligent defaults based on repository structure
42 | 4. **Merging** template files with base agent infrastructure
43 | 5. **Generating** complete, production-ready agent projects
44 |
45 | Any Git repository can become a template - the system handles the complexity automatically.
46 |
47 | ## Related Documentation
48 |
49 | - **[Using Remote Templates](./using-remote-templates.md)** - Complete guide for template users
50 | - **[Creating Remote Templates](./creating-remote-templates.md)** - Complete guide for template authors
51 | - **[Template Config Reference](../guide/template-config-reference.md)** - All available configuration options
52 | - **[create CLI](../cli/create.md)** - Command line reference for creating agents
53 | - **[enhance CLI](../cli/enhance.md)** - Command line reference for enhancing projects
--------------------------------------------------------------------------------
/agent_starter_pack/utils/lock_utils.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """Utilities for managing uv lock files and dependencies."""
16 |
17 | import pathlib
18 | from pathlib import Path
19 | from typing import NamedTuple
20 |
21 | import yaml
22 |
23 |
24 | class AgentConfig(NamedTuple):
25 | """Configuration for an agent template."""
26 |
27 | targets: set[str]
28 | dependencies: list[str]
29 |
30 |
31 | def get_agent_configs(
32 | agents_dir: pathlib.Path = pathlib.Path("agent_starter_pack/agents"),
33 | ) -> dict[str, AgentConfig]:
34 | """Get all agents and their supported deployment targets.
35 |
36 | Args:
37 | agents_dir: Path to the agents directory
38 |
39 | Returns:
40 | Dictionary mapping agent names to their configuration
41 | """
42 | agent_configs = {}
43 |
44 | for agent_dir in agents_dir.iterdir():
45 | if not agent_dir.is_dir():
46 | continue
47 |
48 | config_file = agent_dir / ".template" / "templateconfig.yaml"
49 | if not config_file.exists():
50 | continue
51 |
52 | with open(config_file, encoding="utf-8") as f:
53 | config = yaml.safe_load(f)
54 |
55 | agent_name = agent_dir.name
56 | settings = config.get("settings", {})
57 |
58 | agent_configs[agent_name] = settings
59 |
60 | return agent_configs
61 |
62 |
63 | def get_lock_filename(agent_name: str, deployment_target: str) -> str:
64 | """Generate the lock filename for a given agent and deployment target.
65 |
66 | Args:
67 | agent_name: Name of the agent
68 | deployment_target: Target deployment platform
69 |
70 | Returns:
71 | Formatted lock filename
72 | """
73 | return f"uv-{agent_name}-{deployment_target}.lock"
74 |
75 |
76 | def get_lock_path(agent_name: str, deployment_target: str) -> Path:
77 | """Get the path to the appropriate lock file."""
78 | lock_filename = get_lock_filename(agent_name, deployment_target)
79 | return Path("agent_starter_pack/resources/locks") / lock_filename
80 |
--------------------------------------------------------------------------------
/tests/integration/utils.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | import pathlib
16 | import subprocess
17 |
18 | from rich.console import Console
19 |
20 | console = Console()
21 |
22 |
23 | def run_command(
24 | cmd: list[str],
25 | cwd: pathlib.Path | None,
26 | message: str,
27 | stream_output: bool = True,
28 | env: dict | None = None,
29 | ) -> subprocess.CompletedProcess:
30 | """Helper function to run commands and stream output"""
31 | console.print(f"\n[bold blue]{message}...[/]")
32 | try:
33 | # Using Popen to stream output
34 | with subprocess.Popen(
35 | cmd,
36 | stdout=subprocess.PIPE,
37 | stderr=subprocess.PIPE,
38 | text=True,
39 | cwd=cwd,
40 | bufsize=1, # Line-buffered
41 | env=env,
42 | encoding="utf-8",
43 | ) as process:
44 | if stream_output:
45 | # Stream stdout
46 | if process.stdout:
47 | for line in process.stdout:
48 | console.print(line.strip())
49 |
50 | # Stream stderr
51 | if process.stderr:
52 | for line in process.stderr:
53 | console.print("[bold red]" + line.strip())
54 | else:
55 | # Consume the output but don't print it
56 | if process.stdout:
57 | for _ in process.stdout:
58 | pass
59 | if process.stderr:
60 | for _ in process.stderr:
61 | pass
62 |
63 | # Wait for the process to complete and get the return code
64 | returncode = process.wait()
65 |
66 | if returncode != 0:
67 | raise subprocess.CalledProcessError(returncode, cmd)
68 |
69 | console.print(f"[green]✓[/] {message} completed successfully")
70 | return subprocess.CompletedProcess(cmd, returncode, "", "")
71 |
72 | except subprocess.CalledProcessError:
73 | console.print(f"[bold red]Error: {message}[/]")
74 | raise
75 |
--------------------------------------------------------------------------------
/agent_starter_pack/frontends/adk_live_react/frontend/public/index.html:
--------------------------------------------------------------------------------
1 |
2 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 |
27 |
28 |
29 |
32 |
35 |
36 |
45 |
38 |
48 |
59 |
60 | None:
42 | """Test formatting content with text and images"""
43 | content = [
44 | {"type": "text", "text": "Here's an image:"},
45 | {"type": "image_url", "image_url": {"url": "test.jpg"}},
46 | ]
47 | formatted = format_content(content)
48 | assert "Here's an image:" in formatted
49 | assert ' None:
54 | """Test getting MIME type from GCS blob"""
55 | mock_blob = MagicMock()
56 | mock_blob.content_type = "image/jpeg"
57 | mock_bucket = MagicMock()
58 | mock_bucket.blob.return_value = mock_blob
59 | mock_storage_client.return_value.bucket.return_value = mock_bucket
60 |
61 | mime_type = get_gcs_blob_mime_type("gs://bucket/test.jpg")
62 | assert mime_type == "image/jpeg"
63 |
64 |
65 | def test_gs_uri_to_https_url() -> None:
66 | """Test converting GCS URI to HTTPS URL"""
67 | gs_uri = "gs://bucket/folder/file.jpg"
68 | https_url = gs_uri_to_https_url(gs_uri)
69 | assert https_url == "https://storage.mtls.cloud.google.com/bucket/folder/file.jpg"
70 |
71 |
72 | def test_gs_uri_to_https_url_invalid() -> None:
73 | """Test converting invalid GCS URI"""
74 | with pytest.raises(ValueError):
75 | gs_uri_to_https_url("invalid_uri")
76 |
--------------------------------------------------------------------------------
/agent_starter_pack/base_template/deployment/terraform/{% if cookiecutter.cicd_runner == 'github_actions' %}wif.tf{% else %}unused_wif.tf{% endif %}:
--------------------------------------------------------------------------------
1 |
2 | data "google_project" "cicd_project" {
3 | project_id = var.cicd_runner_project_id
4 | }
5 |
6 | resource "google_service_account_iam_member" "github_oidc_access" {
7 | service_account_id = resource.google_service_account.cicd_runner_sa.name
8 | role = "roles/iam.workloadIdentityUser"
9 | member = "principalSet://iam.googleapis.com/projects/${data.google_project.cicd_project.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.github_pool.workload_identity_pool_id}/attribute.repository/${var.repository_owner}/${var.repository_name}"
10 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
11 | }
12 |
13 | # Allow the GitHub Actions principal to impersonate the CICD runner service account
14 | resource "google_service_account_iam_member" "github_sa_impersonation" {
15 | service_account_id = resource.google_service_account.cicd_runner_sa.name
16 | role = "roles/iam.serviceAccountTokenCreator"
17 | member = "principalSet://iam.googleapis.com/projects/${data.google_project.cicd_project.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.github_pool.workload_identity_pool_id}/attribute.repository/${var.repository_owner}/${var.repository_name}"
18 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
19 | }
20 |
21 | resource "google_iam_workload_identity_pool" "github_pool" {
22 | workload_identity_pool_id = "${var.project_name}-pool"
23 | project = var.cicd_runner_project_id
24 | display_name = "GitHub Actions Pool"
25 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
26 | }
27 |
28 | resource "google_iam_workload_identity_pool_provider" "github_provider" {
29 | workload_identity_pool_provider_id = "${var.project_name}-oidc"
30 | project = var.cicd_runner_project_id
31 | workload_identity_pool_id = google_iam_workload_identity_pool.github_pool.workload_identity_pool_id
32 | display_name = "GitHub OIDC Provider"
33 | oidc {
34 | issuer_uri = "https://token.actions.githubusercontent.com"
35 | }
36 | attribute_mapping = {
37 | "google.subject" = "assertion.sub"
38 | "attribute.repository" = "assertion.repository"
39 | "attribute.repository_owner" = "assertion.repository_owner"
40 | }
41 | attribute_condition = "attribute.repository == '${var.repository_owner}/${var.repository_name}'"
42 | depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
43 | }
44 |
--------------------------------------------------------------------------------
/agent_starter_pack/base_template/deployment/terraform/dev/log_sinks.tf:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | resource "google_project_iam_member" "bigquery_data_editor" {
16 |
17 | project = var.dev_project_id
18 | role = "roles/bigquery.dataEditor"
19 | member = module.log_export_to_bigquery.writer_identity
20 | }
21 |
22 | resource "google_bigquery_dataset" "feedback_dataset" {
23 | project = var.dev_project_id
24 | dataset_id = replace("${var.project_name}_feedback", "-", "_")
25 | friendly_name = "${var.project_name}_feedback"
26 | location = var.region
27 | depends_on = [resource.google_project_service.services]
28 | }
29 |
30 | resource "google_bigquery_dataset" "telemetry_logs_dataset" {
31 | project = var.dev_project_id
32 | dataset_id = replace("${var.project_name}_telemetry", "-", "_")
33 | friendly_name = "${var.project_name}_telemetry"
34 | location = var.region
35 | depends_on = [resource.google_project_service.services]
36 | }
37 |
38 | module "feedback_export_to_bigquery" {
39 | source = "terraform-google-modules/log-export/google"
40 | version = "10.0.0"
41 | log_sink_name = "${var.project_name}_feedback"
42 | parent_resource_type = "project"
43 | parent_resource_id = var.dev_project_id
44 | destination_uri = "bigquery.googleapis.com/projects/${var.dev_project_id}/datasets/${google_bigquery_dataset.feedback_dataset.dataset_id}"
45 | filter = var.feedback_logs_filter
46 | bigquery_options = { use_partitioned_tables = true }
47 | unique_writer_identity = true
48 | depends_on = [google_bigquery_dataset.feedback_dataset]
49 | }
50 |
51 | module "log_export_to_bigquery" {
52 | source = "terraform-google-modules/log-export/google"
53 | version = "10.0.0"
54 |
55 | log_sink_name = "${var.project_name}_telemetry"
56 | parent_resource_type = "project"
57 | parent_resource_id = var.dev_project_id
58 | destination_uri = "bigquery.googleapis.com/projects/${var.dev_project_id}/datasets/${google_bigquery_dataset.telemetry_logs_dataset.dataset_id}"
59 | filter = var.telemetry_logs_filter
60 | bigquery_options = { use_partitioned_tables = true }
61 | unique_writer_identity = true
62 | depends_on = [google_bigquery_dataset.telemetry_logs_dataset]
63 | }
64 |
--------------------------------------------------------------------------------
/tests/fixtures/makefile_snapshots/adk_base_agent_engine_no_data.makefile:
--------------------------------------------------------------------------------
1 | # ==============================================================================
2 | # Installation & Setup
3 | # ==============================================================================
4 |
5 | # Install dependencies using uv package manager
6 | install:
7 | @command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh; source $HOME/.local/bin/env; }
8 | uv sync --dev
9 |
10 | # ==============================================================================
11 | # Playground Targets
12 | # ==============================================================================
13 |
14 | # Launch local dev playground
15 | playground:
16 | @echo "==============================================================================="
17 | @echo "| 🚀 Starting your agent playground... |"
18 | @echo "| |"
19 | @echo "| 💡 Try asking: What can you help me with?|"
20 | @echo "| |"
21 | @echo "| 🔍 IMPORTANT: Select the 'test_adk_base' folder to interact with your agent. |"
22 | @echo "==============================================================================="
23 | uv run adk web . --port 8501 --reload_agents
24 |
25 | # ==============================================================================
26 | # Backend Deployment Targets
27 | # ==============================================================================
28 |
29 | # Deploy the agent remotely
30 | backend:
31 | # Export dependencies to requirements file using uv export.
32 | uv export --no-hashes --no-header --no-dev --no-emit-project --no-annotate > .requirements.txt 2>/dev/null || \
33 | uv export --no-hashes --no-header --no-dev --no-emit-project > .requirements.txt && uv run test_adk_base/agent_engine_app.py
34 |
35 |
36 | # ==============================================================================
37 | # Infrastructure Setup
38 | # ==============================================================================
39 |
40 | # Set up development environment resources using Terraform
41 | setup-dev-env:
42 | PROJECT_ID=$$(gcloud config get-value project) && \
43 | (cd deployment/terraform/dev && terraform init && terraform apply --var-file vars/env.tfvars --var dev_project_id=$$PROJECT_ID --auto-approve)
44 |
45 | # ==============================================================================
46 | # Testing & Code Quality
47 | # ==============================================================================
48 |
49 | # Run unit and integration tests
50 | test:
51 | uv run pytest tests/unit && uv run pytest tests/integration
52 |
53 | # Run code quality checks (codespell, ruff, mypy)
54 | lint:
55 | uv sync --dev --extra lint
56 | uv run codespell
57 | uv run ruff check . --diff
58 | uv run ruff format . --check --diff
59 | uv run mypy .
60 |
--------------------------------------------------------------------------------
/tests/fixtures/makefile_snapshots/agent_with_custom_commands.makefile:
--------------------------------------------------------------------------------
1 | # ==============================================================================
2 | # Installation & Setup
3 | # ==============================================================================
4 |
5 | # Install dependencies using uv package manager
6 | install:
7 | @command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh; source $HOME/.local/bin/env; }
8 | echo 'Custom install command'
9 |
10 | # ==============================================================================
11 | # Playground Targets
12 | # ==============================================================================
13 |
14 | # Launch local dev playground
15 | playground:
16 | echo 'Custom playground'
17 |
18 | # ==============================================================================
19 | # Agent-Specific Commands
20 | # ==============================================================================
21 |
22 | # Run a custom task
23 | custom-task:
24 | echo 'Running custom task'
25 |
26 | # Task with deployment-specific commands
27 | env-specific-task:
28 | echo 'Cloud Run task'
29 |
30 | # ==============================================================================
31 | # Backend Deployment Targets
32 | # ==============================================================================
33 |
34 | # Deploy the agent remotely
35 | # Usage: make backend [IAP=true] [PORT=8080] - Set IAP=true to enable Identity-Aware Proxy, PORT to specify container port
36 | backend:
37 | PROJECT_ID=$$(gcloud config get-value project) && \
38 | gcloud beta run deploy test-custom \
39 | --source . \
40 | --memory "4Gi" \
41 | --project $$PROJECT_ID \
42 | --region "us-central1" \
43 | --no-allow-unauthenticated \
44 | --no-cpu-throttling \
45 | --labels "" \
46 | --set-env-vars \
47 | "COMMIT_SHA=$(shell git rev-parse HEAD)" \
48 | $(if $(IAP),--iap) \
49 | $(if $(PORT),--port=$(PORT))
50 |
51 |
52 | # ==============================================================================
53 | # Infrastructure Setup
54 | # ==============================================================================
55 |
56 | # Set up development environment resources using Terraform
57 | setup-dev-env:
58 | PROJECT_ID=$$(gcloud config get-value project) && \
59 | (cd deployment/terraform/dev && terraform init && terraform apply --var-file vars/env.tfvars --var dev_project_id=$$PROJECT_ID --auto-approve)
60 |
61 | # ==============================================================================
62 | # Testing & Code Quality
63 | # ==============================================================================
64 |
65 | # Run unit and integration tests
66 | test:
67 | uv run pytest tests/unit && uv run pytest tests/integration
68 |
69 | # Run code quality checks (codespell, ruff, mypy)
70 | lint:
71 | uv sync --dev --extra lint
72 | uv run codespell
73 | uv run ruff check . --diff
74 | uv run ruff format . --check --diff
75 | uv run mypy .
76 |
--------------------------------------------------------------------------------
/docs/guide/troubleshooting.md:
--------------------------------------------------------------------------------
1 | # Troubleshooting
2 |
3 | This guide helps resolve common issues with the Agent Starter Pack.
4 |
5 | ## Authentication Issues
6 |
7 | For detailed information on authentication with Vertex AI, visit the [official documentation](https://cloud.google.com/vertex-ai/docs/authentication).
8 |
9 | ### "Could not find credentials" or "Could not find project" Error
10 |
11 | **Problem**: Missing credentials error with Vertex AI.
12 |
13 | **Solution**:
14 |
15 | 1. Log in to Google Cloud: `gcloud auth login --update-adc`
16 | 2. Set the correct project:
17 | ```bash
18 | gcloud config set project YOUR_PROJECT_ID
19 | gcloud auth application-default set-quota-project YOUR_PROJECT_ID
20 | ```
21 |
22 | ### Vertex AI API Not Enabled
23 |
24 | **Problem**: Operations fail because the Vertex AI API is not enabled in your project.
25 |
26 | **Solution**:
27 |
28 | 1. Enable the Vertex AI API:
29 | ```bash
30 | gcloud services enable aiplatform.googleapis.com
31 | ```
32 |
33 | 2. Verify the API is enabled:
34 | ```bash
35 | gcloud services list --filter=aiplatform.googleapis.com
36 | ```
37 |
38 | ### Permission Denied Errors
39 | **Problem**: "Permission denied" errors with Google Cloud APIs.
40 |
41 | **Solution**: Ensure your user or service account has the necessary IAM roles. For example, for Vertex AI, you often need `roles/aiplatform.user`. Grant roles using the `gcloud projects add-iam-policy-binding` command or the Cloud Console.
42 |
43 | ### Command Not Found: agent-starter-pack
44 |
45 | **Problem**: "Command not found" error after installation.
46 |
47 | **Solution**:
48 |
49 | 1. Verify installation:
50 | ```bash
51 | pip list | grep agent-starter-pack
52 | ```
53 | 2. Check PATH:
54 | ```bash
55 | echo $PATH
56 | ```
57 | 3. Reinstall if needed:
58 | ```bash
59 | pip install --user agent-starter-pack
60 | ```
61 | 4. For pipx:
62 | ```bash
63 | pipx ensurepath
64 | source ~/.bashrc # or ~/.zshrc
65 | ```
66 |
67 | ## Project Creation Issues
68 |
69 | ### Project Creation Fails
70 |
71 | **Problem**: `agent-starter-pack create` fails.
72 |
73 | **Solution**:
74 |
75 | 1. **Check Error Messages:** Examine output for clues.
76 | 2. **Write Permissions:** Ensure write access to the directory.
77 | 3. **Project Name:** Use lowercase letters, numbers and hyphens only.
78 | 4. **Debug Mode:** Consider using debug mode to get more detailed error information:
79 | ```bash
80 | agent-starter-pack create my-project-name --debug
81 | ```
82 |
83 | ### Issues with Agent Engine
84 |
85 | Consider leveraging the [public product documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/troubleshooting/set-up)
86 |
87 | ## Getting More Help
88 |
89 | If issues persist:
90 |
91 | 1. **Check GitHub Issues:** Search for existing Github issues in the `agent-starter-pack` Github repository.
92 | 2. **File a New Issue:** Provide:
93 |
94 | * Problem description.
95 | * Steps to reproduce.
96 | * Error messages (preferably run with `--debug` flag for detailed logs).
97 | * Environment: OS, Python version, `agent-starter-pack` version, installation method, shell.
98 |
--------------------------------------------------------------------------------
/tests/test_frontend/test_utils/test_local_chat_history.py:
--------------------------------------------------------------------------------
1 | # Copyright 2025 Google LLC
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | from pathlib import Path
16 |
17 | import pytest
18 | import yaml
19 |
20 | from frontend.utils.local_chat_history import LocalChatMessageHistory
21 |
22 |
23 | @pytest.fixture
24 | def chat_history(tmp_path: Path) -> LocalChatMessageHistory:
25 | """Create a temporary chat history instance"""
26 | return LocalChatMessageHistory(
27 | user_id="test_user", session_id="test_session", base_dir=str(tmp_path)
28 | )
29 |
30 |
31 | def test_init_creates_directory(tmp_path: Path) -> None:
32 | """Test directory creation on initialization"""
33 | user_dir = tmp_path / "test_user"
34 | assert not user_dir.exists()
35 |
36 | LocalChatMessageHistory(
37 | user_id="test_user", session_id="test_session", base_dir=str(tmp_path)
38 | )
39 |
40 | assert user_dir.exists()
41 |
42 |
43 | def test_get_session(chat_history: LocalChatMessageHistory) -> None:
44 | """Test session ID and file path update"""
45 | chat_history.get_session("new_session")
46 | assert chat_history.session_id == "new_session"
47 | assert chat_history.session_file.endswith("new_session.yaml")
48 |
49 |
50 | def test_upsert_session(chat_history: LocalChatMessageHistory) -> None:
51 | """Test session update/insert"""
52 | session = {
53 | "title": "Test Chat",
54 | "messages": [
55 | {"type": "human", "content": "Hello"},
56 | {"type": "ai", "content": "Hi there"},
57 | ],
58 | }
59 |
60 | chat_history.upsert_session(session)
61 |
62 | # Verify file was created
63 | assert Path(chat_history.session_file).exists()
64 |
65 | # Verify content
66 | with open(chat_history.session_file, encoding="utf-8") as f:
67 | saved_data = yaml.safe_load(f)
68 | assert len(saved_data) == 1
69 | assert saved_data[0]["title"] == "Test Chat"
70 | assert len(saved_data[0]["messages"]) == 2
71 |
72 |
73 | def test_get_all_conversations(chat_history: LocalChatMessageHistory) -> None:
74 | """Test retrieving all conversations"""
75 | # Create some test conversations
76 | sessions = {
77 | "session1": {"title": "Chat 1", "messages": []},
78 | "session2": {"title": "Chat 2", "messages": []},
79 | }
80 |
81 | for session_id, session in sessions.items():
82 | chat_history.get_session(session_id)
83 | chat_history.upsert_session(session)
84 |
85 | conversations = chat_history.get_all_conversations()
86 | assert len(conversations) == 2
87 | assert "session1" in conversations
88 | assert "session2" in conversations
89 |
--------------------------------------------------------------------------------
/tests/unit/README_MAKEFILE_TESTS.md:
--------------------------------------------------------------------------------
1 | # Makefile Template Test Suite
2 |
3 | Regression tests for `agent-starter-pack/base_template/Makefile` template refactoring. Ensures changes don't alter generated output across agent types, deployment targets, and feature combinations.
4 |
5 | ## Coverage
6 |
7 | Tests 9 configurations: ADK Base/Live (Cloud Run/Agent Engine), Agentic RAG (Vertex AI/Vector Search), LangGraph, Custom Commands, Agent Garden.
8 |
9 | ## Running Tests
10 |
11 | ```bash
12 | # All tests
13 | uv run pytest tests/unit/test_makefile_template.py -v
14 |
15 | # Specific categories (use -k filter)
16 | uv run pytest tests/unit/test_makefile_template.py -v -k "test_makefile_hash" # Fastest
17 | uv run pytest tests/unit/test_makefile_template.py -v -k "test_makefile_snapshot" # With diffs
18 | uv run pytest tests/unit/test_makefile_template.py -v -k "test_adk_live" # Specific feature
19 | ```
20 |
21 | ## Refactoring Workflow
22 |
23 | 1. Run tests before changes (verify baseline)
24 | 2. Make incremental changes to `agent-starter-pack/base_template/Makefile`
25 | 3. Run tests frequently to catch issues
26 | 4. Verify all tests pass after refactoring
27 |
28 | ## Test Failures
29 |
30 | **Snapshot failure**: Generated Makefile changed. Review diff with `git diff tests/fixtures/makefile_snapshots/