google/adk-recipes

Make a Python Recipe Deployable

A deployable recipe is one that can be packaged into a container and run as a service. This skill writes the files that requires and configures the recipe to match.

It does not build an image, deploy anything, or provision infrastructure. Image builds happen later via Cloud Build → Artifact Registry; this skill's job ends when the files are correct.

The standard it implements lives in .github/policy.yml under deployability: — the minimum google-adk version, the required dependency list, the required file list, and the legacy app_utils file list. Change the standard there, not in the script.

What "deployable" means here, and the one distinction that matters

deployable in .github/schemas/manifest-schema.json means "can be deployed with one click". Two independent questions decide the outcome:

1. Does it need infrastructure a human must provision? If yes it is containerized, not one-click deployable.
2. Did we PROVE the container works, or only assume it?

Never describe a containerized result as "deployable" to the user. Setting that flag on a recipe that still needs hand-written terraform puts a false claim in the manifest, which is worse than leaving it unset.

Equally, never describe an -unverified result as proven. It means the files are right by inspection and nobody built the image — which is the normal result on a machine without docker, not a defect.

Why -unverified still sets the flag. Absence of evidence is not evidence of absence. Withholding it whenever docker is missing would judge the recipe by the checker's laptop rather than by its own quality, and this skill's primary user has no container runtime at all. Only a verification that actually failed withholds the flag — a recipe proven broken is not deployable, whatever the static checks said.

What generating a2a.py does and does not prove

Nothing, on its own. These templates were designed assuming the project was scaffolded by agents-cli, and a file named a2a.py does not make an agent behave correctly over A2A. The skill copies and configures; it does not certify. Say so in your summary — do not tell the owner their recipe "supports A2A" because the file exists.

Rules for the agent

1. Confirm before applying. Always run a dry-run first, show the plan, and get a "yes" before --apply. The skill writes six files and edits three.
2. Ask the questions in the Interview below before applying — but only the ones the dry-run shows are relevant. Do not interrogate the owner about data directories for a recipe that has none.
3. Never override a gate on your own. adk-locked-version, adk-version-floor and legacy-app-utils return needs_input and stop the run. Each means a human has to change code. Report the message verbatim and stop; do not go hunting for a way around it.
4. Never widen an existing version bound to satisfy the standard. The script leaves version specifiers exactly as the recipe wrote them and reports them for confirmation. It does merge in missing extras (google-adk → google-adk[gcp,otel-gcp], same version bound), because the generated code imports what those extras install and the recipe would not start otherwise. Those are different risks: an extra only adds a package's own optional dependencies, while a version rewrite can move the recipe onto code it was never tested against.
5. Do not overwrite an existing fast_api_app.py without explicit confirmation. An existing one is usually bespoke — long-horizon-harness's is ~400 lines of custom routing. --overwrite exists but is a deliberate choice, not a default.
6. Run the follow-ups yourself after a successful apply (see Step 5); the script does not, so a failure is attributable to the right step.
7. Stay inside the recipe. If a run reveals problems in a different recipe, mention them and move on.

Pipeline

Step 0 — Dry run

uv run --no-project --with tomlkit --with 'ruamel.yaml' --with packaging \
  python3 .agents/skills/make-python-recipe-deployable/scripts/make_deployable.py \
  --recipe-dir <RECIPE_DIR>

Prints a JSON report: outcome, agent_package, checks, todos, notes. Nothing is written. Exit code 0 = fine, 1 = a gate needs human input, 2 = error.

Summarise it for the owner. Do not dump the raw JSON.

Step 1 — Handle gates

If any check is needs_input, stop. The three that gate:

• adk-locked-version — uv.lock resolves google-adk to an older major than the standard requires. The declared specifier may well permit the newer version, which is exactly the trap — in both directions. Re-locking IN PLACE keeps the old major (uv is sticky), so the recipe would ship the new serving dependencies against an ADK that cannot support them; resolving FRESH crosses the major silently, and the agent code has only ever run against the old one. The owner must port the agent first. This script rewrites metadata; it cannot migrate code.
• adk-version-floor — the specifier itself excludes the required version (a <2.0.0 ceiling, an ==1.31.0 pin). Same conclusion.
• legacy-app-utils — the package carries the old ASP-era generation (telemetry.py, typing.py, deploy.py, memory_config.py). Filenames do not collide with the new set, but the two wire telemetry and services differently and the existing fast_api_app.py imports the old ones. Generating over the top orphans them or double-wires telemetry. A human decides how to migrate.

Also check already-deployable. If it is report_only, the recipe already serves and you must confirm the owner wants to migrate onto the standard layout before applying — see the advisory at the bottom of this file.

Step 2 — Interview

Ask only what applies. Keep it to one round.

1. Runtime data directories. Does the agent read anything at runtime that is not in the agent package — assets/, sample_data/, a config file? Those need COPY lines or the container fails at request time, not at build time, which is why a human confirms rather than the skill guessing. Pass them as --data-dirs assets,sample_data.
2. An existing serving file was found. The dry-run reports each as report_only. Ask whether to keep it (default) or replace it (--overwrite). Show what the existing file does first.
3. Version bounds that sit below the standard. The report lists any existing requirement it left alone (e.g. google-adk>=2.2.0 against a >=2.6.0 standard). Resolution usually lands on a satisfying version anyway — a2a-sdk>=1.0 forces google-adk>=2.5 on its own — but confirm the owner is happy rather than rewriting their pin.
4. Deployment region. Nothing in a recipe declares one, and it goes into agents-cli-manifest.yaml, so it is a real decision. Default us-east1 (agents-cli's own). Pass --region us-central1 etc.
5. Backing infrastructure. If the outcome is containerized, confirm the owner understands manifest.deployable stays unset and why.

Step 3 — Apply

uv run --no-project --with tomlkit --with 'ruamel.yaml' --with packaging \
  python3 .agents/skills/make-python-recipe-deployable/scripts/make_deployable.py \
  --recipe-dir <RECIPE_DIR> --apply [--data-dirs a,b] [--overwrite] \
  [--region us-central1]

Step 4 — Report what changed

List files_written and the checks that moved to fixed.

Step 5 — Follow-ups (you run these)

When the script changes dependencies the lockfile goes stale, and the new files are unformatted. In order:

cd <RECIPE_DIR> && uv lock --python 3.11

--python 3.11 because CI pins it — locking with a newer local interpreter produces a lockfile CI rejects with a misleading "out of date" error.

Run the lock command the report's todos actually give you, and if they give you none, skip it. The report picks between three states rather than always asking for a re-lock:

The third row is why an idempotent re-run is quiet. The script asks uv lock --check before staying silent, so an earlier run that added dependencies and never locked still produces the todo.

If adk-locked-version came back report_only, the recipe is pinned below the ADK floor — uv keeps any locked version that still satisfies the declared specifier. The report will hand you this instead:

cd <RECIPE_DIR> && uv lock --upgrade-package google-adk --python 3.11

Then confirm the resolved pair. An ADK below 2.5 alongside a2a-sdk 1.x looks fine in the lockfile and dies at import with cannot import name 'TextPart' from 'a2a.types' — invisible to every static check, and one of the reasons Step 6.5 exists.

# from the REPO ROOT, so the root ruff config wins
uv run ruff format <RECIPE_DIR>/ && uv run ruff check --fix <RECIPE_DIR>/

Then the repo validators:

uv run validate manifest <RECIPE_DIR>
uv run validate structure <RECIPE_DIR>
cd <RECIPE_DIR> && uv run pytest tests/ -q

Step 6 — Boot check (the real proof)

Static checks cannot tell you the recipe actually serves. This can, it needs no container runtime, and it is the closest thing to a correctness oracle the skill has. Run it from inside the recipe after uv sync:

cd <RECIPE_DIR> && uv sync --python 3.11 && uv run --python 3.11 --with httpx python -c "
import warnings; warnings.filterwarnings('ignore')
from fastapi.testclient import TestClient
from <PKG>.fast_api_app import app
with TestClient(app) as c:          # entering runs the lifespan
    print('/list-apps ->', c.get('/list-apps').status_code, c.get('/list-apps').json())
    card = [r.path for r in app.routes if 'well-known' in r.path]
    print('agent card ->', c.get(card[0]).status_code if card else 'NO A2A ROUTES')
"

Expected: /list-apps returns 200 listing the agent package, and the agent card returns 200. Entering the TestClient context is what triggers the lifespan — without it the A2A routes never attach and the check is worthless.

If the agent card 404s or no A2A routes exist, the A2A wiring did not take effect. Report that plainly; do not describe the recipe as A2A-capable.

Warnings about experimental InMemoryCredentialService are expected and harmless.

Step 6.5 — Container verification (ask first)

Step 6 proves the app boots on this machine. This proves the image the recipe will actually be deployed as. It is the only step that turns "we generated a Dockerfile" into evidence, and it is what lets the word "deployable" mean anything.

Look at the docker check in the report. It is present in every run, including the dry-run, and its details.docker_state is one of:

When and only when the state is usable, ask:

Docker is available. Shall I build the generated Dockerfile and check the container actually serves? It takes a few minutes, and it means manifest.deployable is set on evidence rather than on inspection. If the container does not come up, I will not set the flag.

If they decline, carry on — the outcome ends -unverified and that is a legitimate result. Do not decide for them, and do not skip the question because verification seems slow.

On a "yes", re-invoke with both --apply and --verify-container. --verify-container does not imply --apply — on its own it reports that verification needs the files on disk, and builds nothing:

uv run --no-project --with tomlkit --with 'ruamel.yaml' --with packaging \
  python3 .agents/skills/make-python-recipe-deployable/scripts/make_deployable.py \
  --recipe-dir <RECIPE_DIR> --apply --verify-container [--data-dirs a,b]

Run it after Step 5's uv lock, not before. The Dockerfile runs uv sync --frozen, which cannot succeed until the lockfile matches. If the lockfile is stale the script does not build — it defers manifest.deployable, returns needs_input, and tells you to lock first. That is by design: a build attempted against a stale lockfile fails with an error that looks exactly like a broken template and is not.

What it does: builds for linux/amd64 (Cloud Run's platform), runs the container with the recipe's own .env.example values plus the policy's container_env, polls /list-apps until it answers, then probes the A2A agent card. It removes the container and the image afterwards.

Reading the result:

• container-build ERROR — the Dockerfile does not build. The check carries a details.hint naming the likely structural cause. Report it and stop; the recipe is not deployable.
• container-serves ERROR — the image builds but the app does not come up. The log tail is in the message. manifest.deployable was not set.
• container-a2a REPORT_ONLY — it serves, but the agent card did not return 200. The A2A wiring did not take effect. Say so plainly and do not call the recipe A2A-capable.

⚠️ Running a container is allowlisted, not automatic. Recipes not on deployability.verification.run_allowlist are built only, because some create real cloud resources at import — core/python/cross-session-memory calls client.agent_engines.create() at module scope. A build-only result is reported as unproven, never as a pass. Add a recipe to the allowlist only after reading its package for import-time side effects.

Step 7 — Close out

Walk the report's todos with the owner — .env.example entries for any new variables (the extract-python-environment-variables skill does this), and terraform if the outcome was containerized.

If you created a .venv in the recipe to run Step 6 and it was not there before, remove it.

Deliberately not in scope