Creating Remote Templates

This guide is for developers who want to create and share their own remote templates. Remote templates let you package your custom agent logic, dependencies, and infrastructure definitions into a reusable Git repository that others can use to generate production-ready agents.

Requirements for Template Creators

When creating a remote template, you need to consider:

Dependencies (`pyproject.toml`)

Required for custom dependencies: If your agent has custom Python dependencies, you must include a pyproject.toml file at the template root with those dependencies listed.

For guidance on the structure and content of your pyproject.toml, you can reference the base template pyproject.toml as an example of the expected format and common dependencies.

Configuration (`[tool.agent-starter-pack]`)

Optional but recommended: Add this section to your pyproject.toml for:

Discoverability: Templates with this section appear in uvx agent-starter-pack list commands
Customization: Override default behaviors like base template, deployment targets, etc.
Metadata: Provide clear name and description for your template

Smart Defaults

Templates work even without explicit configuration thanks to intelligent defaults based on your repository structure.

Quick Start: Creating Your First Template

Let's build a simple remote template that customizes the built-in adk_base agent.

Step 1: Create the Template Structure

A remote template mirrors a standard agent codebase:

my-first-remote-template/
├── pyproject.toml           # Dependencies and configuration
├── app/
│   └── agent.py             # Your custom agent logic
└── README.md                # Template documentation

Step 2: Configure Dependencies and Settings

Create a pyproject.toml file:

toml

[project]
name = "my-first-remote-template"
version = "0.1.0"
description = "A simple template that says hello"
dependencies = [
    "google-adk>=1.8.0",
]

[tool.agent-starter-pack]
# The built-in agent to use as a foundation
base_template = "adk_base"

# Template metadata (optional - falls back to [project] section)
name = "My First Remote Template"
description = "A simple template that demonstrates custom greetings"

# Override settings from the base template
[tool.agent-starter-pack.settings]
# This template will only support the 'agent_engine' deployment target
deployment_targets = ["agent_engine"]

Step 3: Create Your Custom Agent Logic

Create your custom agent logic in app/agent.py:

python

from google.adk.agents import Agent

def get_greeting(name: str = "World") -> str:
    """Returns a friendly greeting from the remote template."""
    return f"Hello, {name}! This greeting comes from a remote template."

root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful AI assistant. Use your tools to answer questions.",
    tools=[get_greeting],
)

Step 4: Test Locally

Test your template locally before publishing:

bash

# Run from the parent directory of 'my-first-remote-template'
uvx agent-starter-pack create my-test-agent -a local@./my-first-remote-template

Initialize a Git repository and push to GitHub:

bash

cd my-first-remote-template
git init
git add .
git commit -m "Initial remote template"
git remote add origin https://github.com/your-username/my-first-remote-template
git push -u origin main

Now anyone can use your template:

bash

uvx agent-starter-pack create my-remote-agent -a https://github.com/your-username/my-first-remote-template

Template Structure Details

Required Files

pyproject.toml (Required for custom dependencies):

Must be at the root of your repository
Defines your agent's Python dependencies
Contains optional [tool.agent-starter-pack] configuration

Recommended Structure

my-awesome-template/
├── pyproject.toml           # Dependencies and configuration
├── uv.lock                  # (Recommended) Locked dependencies  
├── app/
│   └── agent.py             # Your custom agent logic
├── tests/
│   └── test_agent.py        # Your custom tests
├── deployment/
│   └── terraform/
│       └── custom.tf        # Custom infrastructure
└── README.md                # Template documentation

Configuration Format

toml

[project]
name = "my-awesome-template"
description = "An awesome AI agent template"
dependencies = ["google-adk>=1.8.0", "custom-lib"]

[tool.agent-starter-pack]
base_template = "adk_base"
name = "My Awesome Template"  # Optional: falls back to [project].name
description = "Custom description"  # Optional: falls back to [project].description

[tool.agent-starter-pack.settings]
deployment_targets = ["cloud_run", "agent_engine"]
frontend_type = "adk_streamlit"

Configuration Reference

Configuration Fallback Behavior

The system intelligently falls back between configuration sources:

[tool.agent-starter-pack] section (highest priority)
[project] section (fallback for name and description)
Smart defaults (based on repository structure)

Example with fallbacks:

toml

[project]
name = "my-agent-template"
description = "A template for building chatbots"

# This section is optional - without it, falls back to [project] + defaults
[tool.agent-starter-pack]
base_template = "adk_base"  # Override default
# name and description will use [project] values

For complete configuration options, see the Template Config Reference.

How File Merging Works

When someone uses your template, files are copied and overlaid in this order (later steps overwrite earlier ones):

Base Template Files: The foundational files from the starter pack
Deployment Target Files: Files for the chosen deployment target (e.g., cloud_run)
Frontend Files (Optional): If a frontend_type is specified
Base Agent Files: The application logic from the base_template (e.g., adk_base)
Remote Template Files (Highest Precedence): All files from your repository root

This means your template files will override any conflicting files from the base system.

Managing Dependencies

Python Dependencies

pyproject.toml (Required for custom deps):

toml

[project]
dependencies = [
    "google-adk>=1.8.0",
    "your-custom-package>=1.0.0",
    "another-dependency",
]

uv.lock (Strongly Recommended):

Run uv lock after changing dependencies
Commit the resulting uv.lock file for reproducibility
If present, it guarantees exact dependency versions for users

Best Practice: Always include a uv.lock file for reproducible builds.

Makefile Customization

If your template includes a Makefile, it will be intelligently merged:

Your commands take precedence: If a command exists in both makefiles, yours is kept
New commands are added: Any unique commands from your Makefile are included
Base commands are preserved: Essential commands from the base Makefile are appended

This lets you customize the build process while preserving starter pack functionality.

Customizing Infrastructure

Terraform Overrides

You can customize the generated agent's infrastructure by adding or replacing Terraform files:

Adding New Files: Place new .tf files in the appropriate directory
Overriding Base Files: Create files with the same name to completely replace base files

Environment-Specific Configuration

Production/Staging Configuration:

deployment/terraform/
├── service.tf      # Replaces base service.tf for 'staging' and 'prod'
└── variables.tf    # Custom variables

Development Configuration:

deployment/terraform/dev/
├── service.tf      # Replaces base service.tf ONLY for 'dev'
└── variables.tf    # Dev-specific variables

Example Structure:

my-terraform-template/
├── pyproject.toml
└── deployment/
    └── terraform/
        ├── service.tf      # Production/staging override
        └── dev/
            └── service.tf  # Development override

For complete infrastructure customization options, see the Deployment guide.

Testing Your Template

Local Testing

bash

# Test from parent directory
uvx agent-starter-pack create test-project -a local@./your-template

# Test with different options
uvx agent-starter-pack create test-project -a local@./your-template --deployment-target cloud_run

Validation Checklist

Before publishing, verify:

[ ] pyproject.toml has all required dependencies
[ ] Agent code is in /app directory structure
[ ] uv lock generates without errors
[ ] Local testing creates working agent
[ ] README documents usage and requirements
[ ] Configuration section enables discoverability

Publishing Best Practices

Repository Organization

Use clear, descriptive repository names
Include comprehensive README with usage examples
Tag releases for stable versions
Document any special requirements or setup

Versioning

bash

# Tag stable releases
git tag v1.0.0
git push origin v1.0.0

# Users can reference specific versions
uvx agent-starter-pack create my-agent -a github.com/user/template@v1.0.0

Documentation

Include in your template's README:

Purpose and use case of the template
Usage examples
Configuration options
Prerequisites or special requirements
Changelog for updates

Troubleshooting for Template Authors

"Template works but doesn't show up in `list`"

Add [tool.agent-starter-pack] section to your pyproject.toml
The list command only shows templates with explicit configuration

"Template fails with dependency errors"

Ensure your pyproject.toml includes all required dependencies
Run uv lock to generate a uv.lock file for reproducibility
Test locally: uvx agent-starter-pack create test -a local@./your-template

"Template uses wrong base or missing features"

Check your [tool.agent-starter-pack] configuration
Verify base_template is set correctly (defaults to "adk_base")
Review available settings in the Template Config Reference

"Users report missing dependencies"

Your pyproject.toml may be incomplete
Consider providing a more comprehensive dependency list
Include usage instructions in your README

Examples and Inspiration

Popular Template Patterns

Data Science Agent:

toml

[tool.agent-starter-pack]
base_template = "adk_base"
[tool.agent-starter-pack.settings]
deployment_targets = ["cloud_run"]
extra_dependencies = ["pandas", "numpy", "scikit-learn"]

Chat Bot Template:

toml

[tool.agent-starter-pack]
base_template = "adk_base"
[tool.agent-starter-pack.settings]
frontend_type = "adk_streamlit"
deployment_targets = ["agent_engine", "cloud_run"]

Enterprise Template:

toml

[tool.agent-starter-pack]
base_template = "adk_base"
[tool.agent-starter-pack.settings]
session_type = "alloydb"
deployment_targets = ["cloud_run"]
include_data_ingestion = true

Official Examples

Browse google/adk-samples for production-ready examples
Use uvx agent-starter-pack list --adk to see available official templates

Next Steps

Start simple: Begin with basic agent logic, add complexity gradually
Study examples: Examine successful templates in adk-samples
Get feedback: Share with the community and iterate based on usage
Stay updated: Follow starter pack updates for new features and best practices

Creating Remote Templates ​

Requirements for Template Creators ​

Dependencies (pyproject.toml) ​

Configuration ([tool.agent-starter-pack]) ​

Smart Defaults ​

Quick Start: Creating Your First Template ​

Step 1: Create the Template Structure ​

Step 2: Configure Dependencies and Settings ​

Step 3: Create Your Custom Agent Logic ​

Step 4: Test Locally ​

Step 5: Publish and Share ​

Template Structure Details ​

Required Files ​

Recommended Structure ​

Configuration Format ​

Configuration Reference ​

Configuration Fallback Behavior ​

How File Merging Works ​

Managing Dependencies ​

Python Dependencies ​

Makefile Customization ​

Customizing Infrastructure ​

Terraform Overrides ​

Environment-Specific Configuration ​

Testing Your Template ​

Local Testing ​

Validation Checklist ​

Publishing Best Practices ​

Repository Organization ​

Versioning ​

Documentation ​

Troubleshooting for Template Authors ​

"Template works but doesn't show up in list" ​

"Template fails with dependency errors" ​

"Template uses wrong base or missing features" ​

"Users report missing dependencies" ​

Examples and Inspiration ​

Popular Template Patterns ​

Official Examples ​

Next Steps ​

Creating Remote Templates

Requirements for Template Creators

Dependencies (`pyproject.toml`)

Configuration (`[tool.agent-starter-pack]`)

Smart Defaults

Quick Start: Creating Your First Template

Step 1: Create the Template Structure

Step 2: Configure Dependencies and Settings

Step 3: Create Your Custom Agent Logic

Step 4: Test Locally

Step 5: Publish and Share

Template Structure Details

Required Files

Recommended Structure

Configuration Format

Configuration Reference

Configuration Fallback Behavior

How File Merging Works

Managing Dependencies

Python Dependencies

Makefile Customization

Customizing Infrastructure

Terraform Overrides

Environment-Specific Configuration

Testing Your Template

Local Testing

Validation Checklist

Publishing Best Practices

Repository Organization

Versioning

Documentation

Troubleshooting for Template Authors

"Template works but doesn't show up in `list`"

"Template fails with dependency errors"

"Template uses wrong base or missing features"

"Users report missing dependencies"

Examples and Inspiration

Popular Template Patterns

Official Examples

Next Steps