google-agents-cli-extensions 1.14.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- core/claude/README.md +35 -0
- core/claude/template/.agents/skills/agents-cli-claude/SKILL.md +106 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/claude.md +386 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/migrate-claude-agent.md +318 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/migrate-from-aws.md +132 -0
- core/claude/template/.dockerignore +28 -0
- core/claude/template/.env +18 -0
- core/claude/template/.env.example +17 -0
- core/claude/template/.template/templateconfig.yaml +31 -0
- core/claude/template/AGENTS.md +33 -0
- core/claude/template/Dockerfile +55 -0
- core/claude/template/agent_config/README.md +9 -0
- core/claude/template/agents-cli-extension.yaml +49 -0
- core/claude/template/app/__init__.py +15 -0
- core/claude/template/app/agent.py +49 -0
- core/claude/template/app/app_utils/a2a.py +245 -0
- core/claude/template/app/app_utils/bq_analytics/__init__.py +124 -0
- core/claude/template/app/app_utils/bq_analytics/recorder.py +593 -0
- core/claude/template/app/app_utils/bq_analytics/redaction.py +209 -0
- core/claude/template/app/app_utils/bq_analytics/schema.py +394 -0
- core/claude/template/app/app_utils/bq_analytics/tables.py +104 -0
- core/claude/template/app/app_utils/bq_analytics/uploader.py +188 -0
- core/claude/template/app/app_utils/claude.py +297 -0
- core/claude/template/app/app_utils/completions.py +225 -0
- core/claude/template/app/app_utils/conversation.py +29 -0
- core/claude/template/app/app_utils/memory_bank.py +308 -0
- core/claude/template/app/app_utils/project_settings.py +91 -0
- core/claude/template/app/app_utils/reasoning_engine.py +237 -0
- core/claude/template/app/app_utils/remote_agents.py +349 -0
- core/claude/template/app/app_utils/remote_auth.py +159 -0
- core/claude/template/app/app_utils/replies.py +143 -0
- core/claude/template/app/app_utils/session_store.py +174 -0
- core/claude/template/app/app_utils/settings.py +24 -0
- core/claude/template/app/app_utils/telemetry/__init__.py +114 -0
- core/claude/template/app/app_utils/telemetry/call_counts.py +44 -0
- core/claude/template/app/app_utils/telemetry/cli_relay.py +266 -0
- core/claude/template/app/app_utils/telemetry/config.py +133 -0
- core/claude/template/app/app_utils/telemetry/logs.py +175 -0
- core/claude/template/app/app_utils/telemetry/metrics.py +270 -0
- core/claude/template/app/app_utils/telemetry/request_flush.py +104 -0
- core/claude/template/app/app_utils/telemetry/subagent_spans.py +80 -0
- core/claude/template/app/app_utils/telemetry/traces.py +166 -0
- core/claude/template/app/app_utils/turn_events.py +463 -0
- core/claude/template/app/app_utils/turn_options.py +219 -0
- core/claude/template/app/app_utils/workspaces.py +65 -0
- core/claude/template/app/fast_api_app.py +71 -0
- core/claude/template/app/feature_tools.py +27 -0
- core/claude/template/pyproject.toml +100 -0
- core/claude/template/scripts/eval_generate.py +340 -0
- core/claude/template/scripts/publish.py +66 -0
- core/claude/template/scripts/run.py +85 -0
- core/claude/template/scripts/unsupported.py +48 -0
- core/claude/template/tests/eval/datasets/basic-dataset.json +31 -0
- core/claude/template/tests/eval/eval_config.yaml +17 -0
- core/claude/template/tests/eval/response_quality.py +60 -0
- core/claude/template/tests/integration/test_server_e2e.py +168 -0
- core/claude/template/tests/load_test/.results/.placeholder +0 -0
- core/claude/template/tests/load_test/README.md +24 -0
- core/claude/template/tests/load_test/load_test.py +118 -0
- core/claude/template/tests/unit/conftest.py +63 -0
- core/claude/template/tests/unit/helpers.py +32 -0
- core/claude/template/tests/unit/test_a2a.py +432 -0
- core/claude/template/tests/unit/test_bq_analytics.py +928 -0
- core/claude/template/tests/unit/test_bq_redaction.py +89 -0
- core/claude/template/tests/unit/test_claude.py +825 -0
- core/claude/template/tests/unit/test_completions.py +369 -0
- core/claude/template/tests/unit/test_fast_api_app.py +59 -0
- core/claude/template/tests/unit/test_feature_tools.py +55 -0
- core/claude/template/tests/unit/test_memory_bank.py +625 -0
- core/claude/template/tests/unit/test_reasoning_engine.py +295 -0
- core/claude/template/tests/unit/test_remote_agents.py +517 -0
- core/claude/template/tests/unit/test_telemetry.py +991 -0
- core/claude/template/tests/unit/test_turn_events.py +309 -0
- core/claude/template/tests/unit/test_turn_options.py +394 -0
- core/claude/template/uv.lock +3029 -0
- core/langchain/README.md +54 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/SKILL.md +84 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/references/langchain.md +120 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/references/samples.md +42 -0
- core/langchain/template/.template/templateconfig.yaml +32 -0
- core/langchain/template/AGENTS.md +35 -0
- core/langchain/template/agents-cli-extension.yaml +54 -0
- core/langchain/template/app/__init__.py +19 -0
- core/langchain/template/app/agent.py +61 -0
- core/langchain/template/app/app_utils/a2a.py +176 -0
- core/langchain/template/app/app_utils/content.py +37 -0
- core/langchain/template/app/app_utils/telemetry.py +154 -0
- core/langchain/template/app/fast_api_app.py +68 -0
- core/langchain/template/langgraph.json +7 -0
- core/langchain/template/pyproject.toml +102 -0
- core/langchain/template/scripts/_content.py +40 -0
- core/langchain/template/scripts/eval_generate.py +202 -0
- core/langchain/template/scripts/publish.py +59 -0
- core/langchain/template/scripts/run.py +59 -0
- core/langchain/template/scripts/unsupported.py +48 -0
- core/langchain/template/tests/eval/datasets/basic-dataset.json +16 -0
- core/langchain/template/tests/eval/eval_config.yaml +32 -0
- core/langchain/template/tests/eval/response_quality.py +60 -0
- core/langchain/template/tests/integration/test_server_e2e.py +173 -0
- core/langchain/template/tests/load_test/.results/.placeholder +0 -0
- core/langchain/template/tests/load_test/README.md +20 -0
- core/langchain/template/tests/load_test/load_test.py +82 -0
- core/langchain/template/uv.lock +3820 -0
- google_agents_cli_extensions-1.14.2.dist-info/METADATA +133 -0
- google_agents_cli_extensions-1.14.2.dist-info/RECORD +107 -0
- google_agents_cli_extensions-1.14.2.dist-info/WHEEL +4 -0
- google_agents_cli_extensions-1.14.2.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
# Migrating an existing Claude Agent SDK agent
|
|
2
|
+
|
|
3
|
+
Use when the user has a working Claude Agent SDK (Python) agent and wants it served on
|
|
4
|
+
GCP. Assume the Claude models it uses are enabled in Model Garden.
|
|
5
|
+
|
|
6
|
+
Work through the phases in order. Each ends with a check: when a check fails, fix it or
|
|
7
|
+
stop and tell the user, before moving on.
|
|
8
|
+
|
|
9
|
+
## 1. Preflight
|
|
10
|
+
|
|
11
|
+
- The agent imports `claude_agent_sdk` (Python). A TypeScript agent is not supported:
|
|
12
|
+
stop and say so.
|
|
13
|
+
- The agent runs on AWS today (Bedrock settings or model IDs, AgentCore, Lambda, `boto3`
|
|
14
|
+
tools): read `migrate-from-aws.md` now. Its rows join the Assess table, and its edits
|
|
15
|
+
come after the table is shown, before step 4.
|
|
16
|
+
- ADC is set up: `gcloud auth application-default login`.
|
|
17
|
+
- The deployed agent needs `roles/aiplatform.user`; without it every turn fails with
|
|
18
|
+
`403 Permission 'aiplatform.endpoints.predict' denied`. With Agent Identity,
|
|
19
|
+
`agents-cli deploy` grants it to the agent's principal and prints that principal.
|
|
20
|
+
Otherwise a bare `agents-cli deploy` runs as the project's default compute account,
|
|
21
|
+
which may lack it: plan step 7 with `agents-cli infra single-project --apply` and
|
|
22
|
+
`--service-account`.
|
|
23
|
+
|
|
24
|
+
Check: `gcloud projects get-iam-policy <project> --flatten="bindings[].members"
|
|
25
|
+
--filter="bindings.role:roles/aiplatform.user" --format="value(bindings.members)"`.
|
|
26
|
+
|
|
27
|
+
## 2. Assess
|
|
28
|
+
|
|
29
|
+
Read the entrypoint (`main.py`, scripts, notebooks) and fill in this table:
|
|
30
|
+
|
|
31
|
+
| Finding | Consequence |
|
|
32
|
+
|---|---|
|
|
33
|
+
| Options built in `main()` and run with `query()` or `ClaudeSDKClient` | Supported: lift them into `root_agent` (step 4) |
|
|
34
|
+
| Options depend on the request or user (per-tenant tokens, dynamic prompt) | Not supported as-is: `root_agent` is one static `ClaudeAgentOptions`. Tell the user |
|
|
35
|
+
| HTTP routes the code serves (FastAPI, Flask: agent calls, streaming, webhooks, metrics, data lookups, health checks) | Recreate every one with the same method, path, request and response (step 5), whoever calls it: an app, a service, or another agent calling it as a tool. List each route and its callers. The A2A endpoint is added beside them, not instead |
|
|
36
|
+
| A route that runs its own `ClaudeAgentOptions` (a summarizer next to the main agent) | Supported: the recreated route runs those options (step 5); `root_agent` is the agent A2A serves |
|
|
37
|
+
| Code between turns (interrupts, orchestration of several agents in Python) | Not supported as-is. Tell the user |
|
|
38
|
+
| An `mcp_servers` entry with a `command` (`npx`, `uvx`) | That runtime must be in the image (step 5) |
|
|
39
|
+
| A browser MCP server (Playwright) | Needs Chromium in the image, which the template does not provide. Tell the user |
|
|
40
|
+
| `agents=` or `.claude/agents/*.md` | Needs the `Agent` tool (step 5); `.claude/agents/` files move to `agent_config/` (step 4) |
|
|
41
|
+
| `.claude/`, `CLAUDE.md` or `.mcp.json` at the project root | The served agent loads these only from `agent_config/`. Ask the user which parts the agent itself uses (subagents, skills, its instructions, MCP servers) and move those (step 4); development settings (`permissions.allow` rules, hooks, coding notes) stay at the root |
|
|
42
|
+
| `cwd=` pointing at data that `Bash` or `Read` use | Tell the user: keeping `cwd` shares one directory across conversations; dropping it leaves those tools an empty workspace |
|
|
43
|
+
| Hooks or a `statusLine` the agent needs, in `.claude/settings.json`, that run local commands (`afplay`, `uv run`, a script) | Moved to `agent_config/`, they run in the container: drop the ones the image can't run (step 5). Tell the user |
|
|
44
|
+
| A model, or a subagent's `model:`, that isn't enabled in Model Garden | Ask the user to enable it or name a replacement. Don't pick one yourself |
|
|
45
|
+
| Calls to other agents (HTTP clients, other services' agents) | If they serve A2A, use the `remote_agent` helper in place of the tool that calls them (step 5). Tell the user |
|
|
46
|
+
| Multi-turn conversations | On `cloud_run`, scaffold with `--session-type cloud_sql` to keep them across restarts and instances; on `agent_runtime`, Cloud SQL needs manual setup (step 3) |
|
|
47
|
+
| `requires-python` that excludes 3.12 (e.g. `>=3.13`) | The image builds on `python:3.12-slim` and `uv sync` fails there: change it (step 5) |
|
|
48
|
+
|
|
49
|
+
Check: show the user the filled table and the plan before editing anything.
|
|
50
|
+
|
|
51
|
+
## 3. Scaffold
|
|
52
|
+
|
|
53
|
+
Ask the user for the deployment target (`cloud_run` or `agent_runtime`; the template does
|
|
54
|
+
not support `gke`) and whether
|
|
55
|
+
they want CI/CD, then run from the project root:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
agents-cli scaffold enhance google/agents-cli-extensions/core/claude/template \
|
|
59
|
+
--deployment-target cloud_run
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Optional: `--name <name>` (default: the directory name), which also names the deployed
|
|
63
|
+
service or agent; `--region <region>` (default `us-east1`; `infra` deploys there, so pass
|
|
64
|
+
the same one to `deploy`); `--bq-analytics` to log each turn to BigQuery Agent
|
|
65
|
+
Analytics; and `--memory-bank` to give the agent memory of each user in Memory Bank.
|
|
66
|
+
|
|
67
|
+
On `agent_runtime`, `publish gemini`, the Console playground and the Console's
|
|
68
|
+
session views do not work, and Cloud SQL sessions need manual network and database setup
|
|
69
|
+
(the project's `.agents/skills/agents-cli-claude/references/claude.md`, Sessions): tell
|
|
70
|
+
the user before choosing it.
|
|
71
|
+
|
|
72
|
+
Agent Runtime's managed sessions don't apply to Claude agents. Multi-turn works on every target while a conversation's turns reach the same live
|
|
73
|
+
instance, and ends when that instance restarts or a turn lands on another one. On
|
|
74
|
+
`cloud_run`, add `--session-type cloud_sql` when the agent holds multi-turn
|
|
75
|
+
conversations: Terraform then provisions a Cloud SQL Postgres database the transcripts
|
|
76
|
+
are mirrored to, so a conversation survives restarts and moves between instances. Cloud
|
|
77
|
+
SQL costs money while it runs.
|
|
78
|
+
|
|
79
|
+
`enhance` writes the template as `create` would: the A2A server, runtime, a sample
|
|
80
|
+
`app/agent.py`, `pyproject.toml`, `Dockerfile`, deployment files, tests and command
|
|
81
|
+
overrides. Each user file it replaces (typically `pyproject.toml`, `README.md`, `.env`,
|
|
82
|
+
`.gitignore`, `Dockerfile`) moves to `.agents-cli-original/` at the same path and is listed
|
|
83
|
+
in the output; every other file stays where it is. Until step 4, the project runs the
|
|
84
|
+
template's sample agent. Running `enhance` again re-renders the template without moving
|
|
85
|
+
anything.
|
|
86
|
+
|
|
87
|
+
Check: every file `enhance` listed is under `.agents-cli-original/` (`ls -a`: the folder
|
|
88
|
+
is gitignored), and `git status` shows no other user file modified or deleted.
|
|
89
|
+
|
|
90
|
+
## 4. Port the agent
|
|
91
|
+
|
|
92
|
+
Replace the template's sample `app/agent.py` with one exporting `root_agent`, the options
|
|
93
|
+
object the existing code builds:
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
# app/agent.py
|
|
97
|
+
from claude_agent_sdk import ClaudeAgentOptions, create_sdk_mcp_server, tool
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
# In a real repo, import the existing tool instead of defining it here.
|
|
101
|
+
@tool("search_products", "Search the catalog.", {"query": str})
|
|
102
|
+
async def search_products(args):
|
|
103
|
+
return {"content": [{"type": "text", "text": f"Results for {args['query']}"}]}
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
root_agent = ClaudeAgentOptions(
|
|
107
|
+
model="claude-haiku-4-5",
|
|
108
|
+
system_prompt="You help customers find products.",
|
|
109
|
+
mcp_servers={
|
|
110
|
+
"products": create_sdk_mcp_server(name="products", tools=[search_products])
|
|
111
|
+
},
|
|
112
|
+
tools=[],
|
|
113
|
+
allowed_tools=["mcp__products__search_products"],
|
|
114
|
+
)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
- Move the fields from the original `ClaudeAgentOptions(...)` unchanged: `model`,
|
|
118
|
+
`system_prompt`, `tools`, `allowed_tools`, `mcp_servers`, `agents`, `hooks`,
|
|
119
|
+
`can_use_tool`, `permission_mode`, `setting_sources`, `env`.
|
|
120
|
+
- When the original leaves `tools` unset, set it to the built-in tools `allowed_tools`
|
|
121
|
+
names (bare names, without a `(...)` rule), plus `"Agent"` with subagents, or `[]`:
|
|
122
|
+
unset gives the agent every built-in Claude Code tool.
|
|
123
|
+
- When `app/agent.py`, or a module it imports, reads `.env` values at import
|
|
124
|
+
(`os.environ["WEATHER_URL"]`), call `load_dotenv()` before those imports (mark the
|
|
125
|
+
imports after it `# noqa: E402`): `tests/unit` imports it before anything else loads
|
|
126
|
+
`.env`.
|
|
127
|
+
- Import existing tool functions and servers. Do not rewrite them. In-process tools
|
|
128
|
+
(`@tool`, `create_sdk_mcp_server`) run from the project root, so their relative paths
|
|
129
|
+
still work; only Claude Code's built-in tools (`Read`, `Bash`) run in a
|
|
130
|
+
per-conversation workspace.
|
|
131
|
+
- **Keep the user's scripts and modules.** Delete only the deployment files below, after
|
|
132
|
+
the user agrees.
|
|
133
|
+
- Never change the model.
|
|
134
|
+
- Do not add `cwd`, `verbatim_prompts` or other server settings: the scaffolded runtime
|
|
135
|
+
sets them.
|
|
136
|
+
|
|
137
|
+
Then carry over what the template replaced, from `.agents-cli-original/`:
|
|
138
|
+
|
|
139
|
+
- Dependencies: `uv add` each runtime dependency of the original project that the
|
|
140
|
+
template's `pyproject.toml` lacks, with its original spec, from the moved
|
|
141
|
+
`pyproject.toml` (`[project]`, or `[tool.poetry.dependencies]` without `python`, with
|
|
142
|
+
`^`/`*` translated), `requirements.txt` or `setup.py`. Don't carry over specs for
|
|
143
|
+
`claude-agent-sdk`, `fastapi`, `uvicorn` or `a2a-sdk`: the template's code needs its own
|
|
144
|
+
ranges, and an old pin such as `claude-agent-sdk==0.1.30` resolves without an error and
|
|
145
|
+
breaks at runtime. `uv add -r requirements.txt` rewrites those specs too: note them in
|
|
146
|
+
`pyproject.toml` first, and `uv add` each one the file named back afterwards.
|
|
147
|
+
- `.env`: add the values the agent reads to the template's `.env`, and keep its
|
|
148
|
+
`GOOGLE_CLOUD_PROJECT`, `GOOGLE_GENAI_USE_ENTERPRISE` and `GOOGLE_CLOUD_LOCATION` lines,
|
|
149
|
+
or `agents-cli eval` can't grade ("No API key was provided"). Set `GOOGLE_CLOUD_PROJECT`
|
|
150
|
+
to the deploy project. `deploy` copies `.env` to the service, so don't carry over
|
|
151
|
+
`ANTHROPIC_VERTEX_PROJECT_ID`, which sends model calls to another project, or
|
|
152
|
+
`ANTHROPIC_API_KEY`, which the agent doesn't use. Check your shell too (`env | grep -E
|
|
153
|
+
'^(ANTHROPIC_|CLAUDE_CODE_USE_)'`): shell values win over `.env` locally.
|
|
154
|
+
- `README.md`: move the user's back over the template's. `.gitignore`: append the user's
|
|
155
|
+
lines to the template's.
|
|
156
|
+
- `Dockerfile`: keep the template's, which serves the agent; add any system packages the
|
|
157
|
+
user's installed.
|
|
158
|
+
- Anything else listed: port what still applies.
|
|
159
|
+
- Claude Code files the agent uses (the Assess row on `.claude/`): copy them from the
|
|
160
|
+
project root into `agent_config/`, which is the only place the served agent loads
|
|
161
|
+
them from, and leave the root files for the developer's coding assistant.
|
|
162
|
+
|
|
163
|
+
Files outside the folder that only the old deployment reads (its infrastructure, its
|
|
164
|
+
platform's entrypoint, CI that deploys there, e.g. `fly.toml`, `render.yaml`): list them
|
|
165
|
+
and ask the user before deleting. `enhance`'s backup in `~/.agents-cli/backups/` and git
|
|
166
|
+
history keep them. On AWS, follow `migrate-from-aws.md` step 3.
|
|
167
|
+
|
|
168
|
+
Then delete `.agents-cli-original/`; `enhance`'s backup keeps a copy, `.env` included.
|
|
169
|
+
|
|
170
|
+
Check: `uv run python -c "from app.agent import root_agent; print(type(root_agent).__name__)"`
|
|
171
|
+
prints `ClaudeAgentOptions`, `agents-cli install` succeeds, `.agents-cli-original/` is
|
|
172
|
+
gone, and `git status` shows no deleted user file besides the ones the user agreed to.
|
|
173
|
+
|
|
174
|
+
## 5. Tweaks
|
|
175
|
+
|
|
176
|
+
Apply the rows step 2 found, and the `packages` row when step 4 finds it:
|
|
177
|
+
|
|
178
|
+
| Finding | Edit |
|
|
179
|
+
|---|---|
|
|
180
|
+
| stdio MCP server started with `npx` | Uncomment the Node.js install line in `Dockerfile` |
|
|
181
|
+
| Hooks that run local commands | Remove those entries from `agent_config/.claude/settings.json`; keep the rest of the file |
|
|
182
|
+
| `requires-python` excludes 3.12 | Set `FROM python:3.12-slim` in `Dockerfile` to a version it allows, e.g. `python:3.13-slim` |
|
|
183
|
+
| The moved `pyproject.toml` listed packages besides `app` in `[tool.hatch.build.targets.wheel] packages` | Add them to that list in `pyproject.toml`, and `COPY ./<package> ./<package>` for each before `RUN uv sync --frozen` in `Dockerfile`, or the image build can't find them |
|
|
184
|
+
| Subagents | Add `"Agent"` to `tools` (when it is a list) and to `allowed_tools`; older SDKs called it `"Task"`, so replace that |
|
|
185
|
+
| Calls to another A2A agent | `remote_agent("<name>", "<url>", description="<the original tool's description>")` from `app/app_utils/remote_agents.py` in `mcp_servers` (the description tells the model when to call it), `mcp__<name>__ask` in `allowed_tools`; the caller needs `roles/run.invoker` on a Cloud Run target, `roles/aiplatform.user` for an Agent Runtime target (URL: its `.../reasoningEngines/<id>/api/a2a/app` passthrough); a caller on Agent Runtime calling a Cloud Run target also passes `bind_id_token=False`; a token goes by default only to Agent Runtime and `*.run.app` URLs, so a Cloud Run target behind a custom domain passes `auth=True` |
|
|
186
|
+
|
|
187
|
+
Always describe the agent in `_agent_card()` in `app/app_utils/a2a.py`: callers read the
|
|
188
|
+
card to decide what the agent does, and the template's is generic. Set the card's
|
|
189
|
+
`description` and the skill's `description` (optionally its `name` and `tags`) from the
|
|
190
|
+
original agent's purpose and system prompt. Keep `name` and the URLs: the name is
|
|
191
|
+
`A2A_NAME`, also the endpoint path `/a2a/app` that `agents-cli run --url` and other
|
|
192
|
+
agents call.
|
|
193
|
+
|
|
194
|
+
Check: with `uv run uvicorn app.fast_api_app:app --port 8080` running, `curl -s
|
|
195
|
+
localhost:8080/a2a/app/.well-known/agent-card.json` shows the new descriptions.
|
|
196
|
+
|
|
197
|
+
### Keep the existing endpoints
|
|
198
|
+
|
|
199
|
+
Recreate every route the Assess table lists in a new `app/routes.py` (an `APIRouter`),
|
|
200
|
+
so its callers keep working unchanged: same method, path, request and response models,
|
|
201
|
+
status codes and headers. Then, in `app/fast_api_app.py`, add
|
|
202
|
+
`from app.routes import router` to its imports and `app.include_router(router)` after
|
|
203
|
+
`app = FastAPI(...)`: its only change. `scaffold upgrade` never touches `app/routes.py`,
|
|
204
|
+
which the template doesn't ship.
|
|
205
|
+
|
|
206
|
+
How to recreate a route depends on what it does:
|
|
207
|
+
|
|
208
|
+
| The original route | Recreate it by |
|
|
209
|
+
|---|---|
|
|
210
|
+
| Doesn't run the agent (data lookups, feedback, metrics export, health and readiness checks, auth or signature checks) | Copying its handler as it is, importing the user's modules |
|
|
211
|
+
| Runs a turn and returns a result | Replacing the SDK client calls with `reply = await run_turn(prompt, options, conversation_id)` from `app/app_utils/claude.py`, then building the original response from `reply` (below) |
|
|
212
|
+
| Streams a turn (SSE, chunked) | Iterating `stream_turn(prompt, options, conversation_id)` from `app/app_utils/claude.py` and sending `text_delta(message)` from `app/app_utils/replies.py` in the original event format; when the route also needs the turn's result, start from `reply = TurnReply()` and fold in each message with `reply = record(reply, message)`, both from `replies.py` |
|
|
213
|
+
| Runs a turn after it responds (a webhook that acknowledges, then posts the answer) | The same `run_turn`, in the same background task |
|
|
214
|
+
|
|
215
|
+
What `reply` (a `TurnReply`) holds, for responses, metrics and logs: `reply.text`, the
|
|
216
|
+
final answer; `reply.tool_calls`, one dict per call with `name`, `args` and `result`;
|
|
217
|
+
`reply.result`, the turn's `ResultMessage`, with `usage` (`input_tokens`,
|
|
218
|
+
`output_tokens`) and `total_cost_usd`.
|
|
219
|
+
|
|
220
|
+
- `options` is `root_agent`, or the route's own `ClaudeAgentOptions` when it ran other
|
|
221
|
+
options: imported from the user's module, or copied when the handler built them inline.
|
|
222
|
+
- The conversation id resumes a conversation: pass the caller's, or a new one when the
|
|
223
|
+
original route created it, or a new one per call when the route holds none. Drop
|
|
224
|
+
per-process client maps (a dict of `ClaudeSDKClient`s): the runtime keeps the
|
|
225
|
+
transcript under that id.
|
|
226
|
+
- `run_turn` raises `AgentError` (also from `app/app_utils/claude.py`) when a turn ends in
|
|
227
|
+
an error. Catch it where the original returned an error in its response body or with
|
|
228
|
+
another status code.
|
|
229
|
+
- State the original server kept besides clients (a history dict a route returns,
|
|
230
|
+
in-process counters, files it writes such as `feedback.jsonl`): keep its code. Tell the
|
|
231
|
+
user each one lives on one instance and is lost on restart, and that a route reading it
|
|
232
|
+
can miss what another instance served; moving it to a shared store is their call.
|
|
233
|
+
- Secrets a route reads (a webhook signing secret): export them in your shell for local
|
|
234
|
+
runs, not in `.env`, which `deploy` copies into the service's environment. Tell the user
|
|
235
|
+
to pass them at deploy with `agents-cli deploy --secrets ENV=SECRET`.
|
|
236
|
+
- Keep a health route callers or probes use (`GET /healthz`) even though the template
|
|
237
|
+
serves `/health`.
|
|
238
|
+
- The original server module is no longer served: ask the user before deleting it, as
|
|
239
|
+
with the deployment files (step 4).
|
|
240
|
+
|
|
241
|
+
Check: with `uv run uvicorn app.fast_api_app:app --port 8080` running, send each route a
|
|
242
|
+
request taken from its callers (README, client code, tests), including a failing one
|
|
243
|
+
where the original handled errors, and compare the response's status, headers and fields
|
|
244
|
+
with the original server's.
|
|
245
|
+
|
|
246
|
+
Leave the rest of `app/app_utils/` alone: it is the runtime that serves the agent.
|
|
247
|
+
|
|
248
|
+
## 6. Verify
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
agents-cli install
|
|
252
|
+
agents-cli lint
|
|
253
|
+
uv run pytest tests/unit
|
|
254
|
+
agents-cli run "<a prompt from the user's README or scripts>"
|
|
255
|
+
uv run pytest tests/integration
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Fix lint in the files you wrote or edited with `uv run ruff check --fix app && uv run
|
|
259
|
+
ruff format app`. If `agents-cli lint` flags the user's original files (scripts,
|
|
260
|
+
notebooks, parked files), add them to `[tool.ruff] extend-exclude`, `[tool.ty.src]
|
|
261
|
+
exclude` (e.g. `"bookshop/**"`) and, for spelling, `[tool.codespell] skip` instead of
|
|
262
|
+
restyling them. If it flags the template's files because the user's own `[tool.ruff]`
|
|
263
|
+
settings differ (e.g. `line-length`), format only those files once: `uv run ruff format
|
|
264
|
+
app/app_utils app/fast_api_app.py scripts tests`.
|
|
265
|
+
|
|
266
|
+
Check: run two or three of the user's own prompts. The replies must come from the user's
|
|
267
|
+
agent (its persona, its tools), not the template's sample weather agent, and match what
|
|
268
|
+
the original script answers.
|
|
269
|
+
|
|
270
|
+
## 7. Deploy
|
|
271
|
+
|
|
272
|
+
Ask the user before running `infra single-project --apply` or `deploy`: both create billed
|
|
273
|
+
resources and IAM bindings.
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
agents-cli infra single-project --apply --project <gcp-project>
|
|
277
|
+
agents-cli deploy --project <gcp-project> --region <region> \
|
|
278
|
+
--service-account <project-name>-app@<gcp-project>.iam.gserviceaccount.com
|
|
279
|
+
agents-cli run --url <service-url> --mode a2a --app-name app "<the same prompt>"
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
On projects deploying to `agent_runtime` with Agent Identity, skip the service account.
|
|
283
|
+
Still run `infra single-project --apply` first when the project has `--bq-analytics`: it
|
|
284
|
+
creates the Agent Runtime agent (named after the project), the dataset and the agent's
|
|
285
|
+
BigQuery roles, and `deploy` then updates that same agent. Query it with
|
|
286
|
+
`--url https://<region>-aiplatform.googleapis.com/v1/<Agent Runtime ID>`, the resource
|
|
287
|
+
name `deploy` prints.
|
|
288
|
+
|
|
289
|
+
`agents-cli deploy` copies `.env` into the agent's environment. CI/CD deploys have no
|
|
290
|
+
`.env`: add the values the agent needs (e.g. remote agent URLs) to the pipeline's
|
|
291
|
+
`--update-env-vars`.
|
|
292
|
+
|
|
293
|
+
The recreated routes keep their paths, but each caller still needs the new base URL
|
|
294
|
+
and a credential. On `cloud_run`, the service URL, `roles/run.invoker` and an ID token
|
|
295
|
+
for the service. On `agent_runtime`, the passthrough
|
|
296
|
+
`https://<region>-aiplatform.googleapis.com/reasoningEngines/v1/<Agent Runtime ID>/api`
|
|
297
|
+
(the resource name `deploy` prints) followed by the route's path (e.g. `.../api/chat`),
|
|
298
|
+
`roles/aiplatform.user` and an OAuth access token. A caller that can't send a Google token (a Slack or Stripe webhook, a
|
|
299
|
+
Prometheus scrape) needs, on `cloud_run`, a service that allows unauthenticated access,
|
|
300
|
+
or a proxy in front of it; on `agent_runtime`, which takes no unauthenticated calls, a
|
|
301
|
+
proxy. Give the user that list, route by route, for each caller's owner.
|
|
302
|
+
|
|
303
|
+
Check: the deployed agent gives the same answers as step 6, through A2A and through each
|
|
304
|
+
recreated route.
|
|
305
|
+
|
|
306
|
+
## Troubleshooting
|
|
307
|
+
|
|
308
|
+
| Issue | Solution |
|
|
309
|
+
|---|---|
|
|
310
|
+
| `403 Permission 'aiplatform.endpoints.predict' denied` | Deploy with a service account that has `roles/aiplatform.user` (step 1) |
|
|
311
|
+
| `infra single-project` fails on `logging.sinks.create` or `storage.buckets.setIamPolicy` (a project Editor) | Only the prompt-response logging export needs those. If the service account, dataset and engine or service exist, deploy anyway; a project owner can rerun `infra` later |
|
|
312
|
+
| `infra single-project` fails with `constraints/sql.restrictPublicIp` (`--session-type cloud_sql`) | The organization forbids public-IP Cloud SQL. In `deployment/terraform/single-project/service.tf`, give the instance `ip_configuration { ipv4_enabled = false, private_network = <VPC> }` and the Cloud Run service `vpc_access { network_interfaces { network = <VPC>, subnetwork = <subnet> }, egress = "PRIVATE_RANGES_ONLY" }`, then rerun `infra`. The VPC needs Private Service Access, which needs `roles/servicenetworking.networksAdmin` to set up |
|
|
313
|
+
| `MCP server '<name>' runs 'npx', which is not installed here` | Uncomment the Node.js line in `Dockerfile` |
|
|
314
|
+
| Agent answers without using its tools | Check `allowed_tools` names: `mcp__<mcp_servers key>__<tool>` |
|
|
315
|
+
| Subagent never called | Add `"Agent"` to `tools` and `allowed_tools` |
|
|
316
|
+
| `agents-cli install` finds no solution for `claude-agent-sdk` | A spec carried over from the original project is older than the template needs (`>=0.2.158`). Restore the template's (step 4) |
|
|
317
|
+
| Cloud Build fails at `uv sync --frozen` with no lock file | `.gitignore` excludes `uv.lock`, and `.gcloudignore` includes `.gitignore`. Remove `uv.lock` from `.gitignore` |
|
|
318
|
+
| Cloud Build fails to download packages | `uv.lock` points at a private index. Re-lock with `uv lock --default-index https://pypi.org/simple` |
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Migrating a Claude agent that runs on AWS
|
|
2
|
+
|
|
3
|
+
Extra steps for `migrate-claude-agent.md` when the agent runs on AWS today. Add the rows in
|
|
4
|
+
step 4 to its Assess table and show the user the table first. Then do steps 1 to 3 here,
|
|
5
|
+
before that guide's step 4 (Port), and use the rest during its steps 5 to 7.
|
|
6
|
+
|
|
7
|
+
Signs the agent runs on AWS: `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE` or
|
|
8
|
+
`CLAUDE_CODE_USE_ANTHROPIC_AWS` anywhere; model IDs such as `us.anthropic.claude-...-v1:0`
|
|
9
|
+
or `arn:aws:bedrock:...`; `bedrock_agentcore` imports, `.bedrock_agentcore.yaml` or
|
|
10
|
+
`agentcore/agentcore.json`; a Lambda `handler(event, context)`; `boto3` in tools; ECS task
|
|
11
|
+
definitions, CDK, SAM or CloudFormation files.
|
|
12
|
+
|
|
13
|
+
## 1. Remove the AWS model configuration
|
|
14
|
+
|
|
15
|
+
Leftover AWS settings beat the Gemini platform setup: with `CLAUDE_CODE_USE_BEDROCK` set, the CLI
|
|
16
|
+
calls Bedrock even on Cloud Run or Agent Runtime, and a value in `agent_config/.claude/settings.json` overrides the
|
|
17
|
+
process environment.
|
|
18
|
+
|
|
19
|
+
Search `.env*`, `Dockerfile*`, `.claude/settings*.json` (before copying them to `agent_config/`), `root_agent.env` and the options
|
|
20
|
+
builder for these, and remove them from everything the GCP deployment reads:
|
|
21
|
+
|
|
22
|
+
- `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`
|
|
23
|
+
- `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`,
|
|
24
|
+
`ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_SMALL_FAST_MODEL` (keep the model they name
|
|
25
|
+
for step 2)
|
|
26
|
+
- `ANTHROPIC_BEDROCK_*`, `ANTHROPIC_CUSTOM_HEADERS` with Bedrock Guardrail headers,
|
|
27
|
+
`AWS_BEARER_TOKEN_BEDROCK`, `modelOverrides`, `awsAuthRefresh`, `awsCredentialExport`
|
|
28
|
+
|
|
29
|
+
Files that only the AWS deployment reads (CDK, task definitions, `agentcore.json`) can keep
|
|
30
|
+
them.
|
|
31
|
+
|
|
32
|
+
Check, after `migrate-claude-agent.md` step 4 has written `app/agent.py`, that this prints nothing:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
grep -rnE "CLAUDE_CODE_USE_(BEDROCK|MANTLE|ANTHROPIC_AWS)|anthropic\.claude-|arn:aws:bedrock" \
|
|
36
|
+
.env* .claude app | grep -vE ':[0-9]+:\s*#'
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Don't quote Bedrock IDs in code or comments under `app/`.
|
|
40
|
+
|
|
41
|
+
## 2. Translate the model
|
|
42
|
+
|
|
43
|
+
Bedrock model IDs fail on Gemini platform with `400 Invalid endpoint name`. Keep the same model
|
|
44
|
+
family, version and tier, under its Gemini platform name, and put it in `root_agent.model`, also
|
|
45
|
+
when it came from `ANTHROPIC_MODEL`. Leaving `model` unset makes the CLI use its Gemini
|
|
46
|
+
platform default, which is a different and more expensive model.
|
|
47
|
+
|
|
48
|
+
To translate: drop the geo prefix (`us.`, `eu.`, `apac.`, `jp.`, `au.`, `global.`,
|
|
49
|
+
`us-gov.`) and `anthropic.`, drop the `-vN:M` suffix, and drop the date or write it as
|
|
50
|
+
`@YYYYMMDD`:
|
|
51
|
+
|
|
52
|
+
| Bedrock | Gemini platform |
|
|
53
|
+
|---|---|
|
|
54
|
+
| `us.anthropic.claude-haiku-4-5-20251001-v1:0` | `claude-haiku-4-5` or `claude-haiku-4-5@20251001` |
|
|
55
|
+
| `anthropic.claude-sonnet-4-5-20250929-v1:0` | `claude-sonnet-4-5` |
|
|
56
|
+
|
|
57
|
+
Apply the same mapping to subagent `model:` fields. Older models have different Gemini
|
|
58
|
+
platform names, so check the Model Garden model list. Ask the user when the ID is an ARN (application
|
|
59
|
+
inference profile, provisioned throughput), or when the model isn't enabled in Model
|
|
60
|
+
Garden for the target project. After the translation, `migrate-claude-agent.md`'s "Never
|
|
61
|
+
change the model" applies to the Gemini platform name.
|
|
62
|
+
|
|
63
|
+
## 3. Remove the AWS deployment files
|
|
64
|
+
|
|
65
|
+
An AWS root `Dockerfile` has the wrong command, Bedrock settings, and for AgentCore an
|
|
66
|
+
arm64 image that Cloud Run and Agent Runtime can't run. `enhance` moves it and
|
|
67
|
+
`.dockerignore` to `.agents-cli-original/`: don't port them back.
|
|
68
|
+
|
|
69
|
+
Delete every other file only the AWS deployment reads, so it is neither uploaded nor built
|
|
70
|
+
into the image. `enhance` copied the whole project to `~/.agents-cli/backups/` before it
|
|
71
|
+
changed anything, and git history keeps them too:
|
|
72
|
+
|
|
73
|
+
- Infrastructure: SAM `template.yaml` and `samconfig.toml`, CDK apps (`cdk.json` and the
|
|
74
|
+
stacks it runs), CloudFormation templates, ECS task definitions, `serverless.yml`,
|
|
75
|
+
`Procfile`, `apprunner.yaml`.
|
|
76
|
+
- AgentCore: `.bedrock_agentcore.yaml` and the `agentcore/` folder.
|
|
77
|
+
- Entrypoints only that runtime calls: a Lambda `handler(event, context)` module,
|
|
78
|
+
`BedrockAgentCoreApp` entrypoints. Keep any module that defines the agent's tools or
|
|
79
|
+
options: `migrate-claude-agent.md` step 4 imports them.
|
|
80
|
+
- CI workflows that deploy to AWS (`.github/workflows/*` running `sam deploy`,
|
|
81
|
+
`cdk deploy`, `agentcore deploy`, `aws ecs update-service`): left in place, they keep
|
|
82
|
+
deploying the old stack on every push.
|
|
83
|
+
|
|
84
|
+
List the files to delete and the backup path `enhance` printed, and ask the user before
|
|
85
|
+
deleting.
|
|
86
|
+
|
|
87
|
+
Check, after `enhance`: `grep -q "app.fast_api_app" Dockerfile && ! grep -q "linux/arm64" Dockerfile`,
|
|
88
|
+
and `! grep -rlE "sam deploy|cdk deploy|agentcore deploy|ecs update-service" .github/workflows`.
|
|
89
|
+
|
|
90
|
+
`agents-cli deploy` copies every `.env` entry into the service as a plain environment
|
|
91
|
+
variable. Delete AWS keys (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`,
|
|
92
|
+
`AWS_SESSION_TOKEN`) and other secrets from `.env`. Store secrets the agent still needs in
|
|
93
|
+
Secret Manager and pass them with `agents-cli deploy --secrets ENV=SECRET`.
|
|
94
|
+
|
|
95
|
+
## 4. Assess rows for AWS
|
|
96
|
+
|
|
97
|
+
Add these to the Assess table:
|
|
98
|
+
|
|
99
|
+
| Finding | Consequence |
|
|
100
|
+
|---|---|
|
|
101
|
+
| AgentCore `@app.entrypoint` or Lambda `handler(event, context)` | Lift the options builder into `root_agent`. Anything built from the payload or context per request, memory reads before a turn and memory writes after it, is code between turns: not supported as-is. Tell the user |
|
|
102
|
+
| Own FastAPI or Flask server calling `query()` | Lift the options. A2A replaces the routes, so callers change (see Callers) |
|
|
103
|
+
| Agent code in a subdirectory with flat imports | Make it importable from `app/agent.py` (add the directory to `sys.path` there) instead of moving files |
|
|
104
|
+
| `session_store=` on S3, Redis or DynamoDB | Recommend `--session-type cloud_sql` instead (Cloud Run; on Agent Runtime it needs manual setup, see `migrate-claude-agent.md` step 3). Keeping it needs AWS credentials and adds cross-cloud latency to every turn. Existing conversations don't carry over either way |
|
|
105
|
+
| AgentCore Memory | No equivalent. Tell the user |
|
|
106
|
+
| Tools calling AWS (`boto3`) | They need AWS credentials on GCP: keys in Secret Manager, or an AWS IAM role that trusts Google's identity token. Tell the user; adds egress cost and latency |
|
|
107
|
+
| Secrets read from Secrets Manager or SSM | Move them to Secret Manager and read an env var (`deploy --secrets`) |
|
|
108
|
+
| Bedrock geo profile in the model ID, or a data-residency need | `us.` maps to `CLOUD_ML_REGION=us` and `eu.` to `eu` (set it in `.env`, and check the model is offered there; on a `429` quota error there, use a single region within it, such as `us-east5` for `us`); `global.` keeps the default `global`, which may process data anywhere. Ask about `apac.`, `jp.`, `au.` and `us-gov.` |
|
|
109
|
+
| AWS `OTEL_*`, `CLAUDE_CODE_ENABLE_TELEMETRY`, `opentelemetry-instrument`, `aws-opentelemetry-distro` | Remove them; they stop the CLI's spans reaching Cloud Trace |
|
|
110
|
+
| Bedrock Guardrails | Don't carry over. Tell the user |
|
|
111
|
+
| Calls to agents that stay on AWS | `remote_agent` sends Google ID tokens or static headers; no SigV4 or token refresh. Tell the user |
|
|
112
|
+
|
|
113
|
+
## 5. Before cutover
|
|
114
|
+
|
|
115
|
+
- The model is enabled in Model Garden for the target project; enabling can take a day or
|
|
116
|
+
two.
|
|
117
|
+
- Gemini platform quota for that model and region covers the tokens per minute the agent uses on
|
|
118
|
+
Bedrock.
|
|
119
|
+
|
|
120
|
+
## Callers
|
|
121
|
+
|
|
122
|
+
Clients that call the AWS endpoint must switch to A2A: on Cloud Run at
|
|
123
|
+
`<service-url>/a2a/app` with a Google ID token, on Agent Runtime at the agent's
|
|
124
|
+
passthrough URL (`.../reasoningEngines/<id>/api/a2a/app`) with an OAuth access token.
|
|
125
|
+
Callers running on AWS can get either through Workload Identity Federation with an AWS
|
|
126
|
+
provider.
|
|
127
|
+
|
|
128
|
+
## Out of scope
|
|
129
|
+
|
|
130
|
+
AgentCore Memory, Gateway and Identity equivalents; migrating stored transcripts or memory
|
|
131
|
+
records; SigV4; converting AWS infrastructure code or pipelines; per-session microVM
|
|
132
|
+
isolation; runs longer than the platform's request timeout.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
.git/
|
|
3
|
+
**/__pycache__/
|
|
4
|
+
.ruff_cache/
|
|
5
|
+
.pytest_cache/
|
|
6
|
+
.env
|
|
7
|
+
artifacts/
|
|
8
|
+
.agents-cli-original/
|
|
9
|
+
.python-version
|
|
10
|
+
# Your coding assistant's Claude Code files; the agent's live in agent_config/.
|
|
11
|
+
/.claude
|
|
12
|
+
/CLAUDE.md
|
|
13
|
+
/CLAUDE.local.md
|
|
14
|
+
/.mcp.json
|
|
15
|
+
# Secrets and deployment state: pass secrets with `agents-cli deploy --secrets`.
|
|
16
|
+
**/.env
|
|
17
|
+
**/.env.*
|
|
18
|
+
!.env.example
|
|
19
|
+
**/*.pem
|
|
20
|
+
**/*-key.json
|
|
21
|
+
**/*credentials*.json
|
|
22
|
+
**/service-account*.json
|
|
23
|
+
**/.terraform/
|
|
24
|
+
**/*.tfstate
|
|
25
|
+
**/*.tfstate.*
|
|
26
|
+
# Not needed at runtime.
|
|
27
|
+
.github/
|
|
28
|
+
tests/
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Local development configuration
|
|
2
|
+
# For deployment, these are set via Terraform / the deploy command.
|
|
3
|
+
|
|
4
|
+
GOOGLE_GENAI_USE_ENTERPRISE=true
|
|
5
|
+
GOOGLE_CLOUD_PROJECT={{cookiecutter.google_cloud_project}}
|
|
6
|
+
GOOGLE_CLOUD_LOCATION=global
|
|
7
|
+
# Region for Claude calls: "global" or a region such as "us-east5".
|
|
8
|
+
CLOUD_ML_REGION=global
|
|
9
|
+
{%- if cookiecutter.bq_analytics %}
|
|
10
|
+
|
|
11
|
+
# Uncomment to log local runs too.
|
|
12
|
+
# BQ_ANALYTICS_DATASET_ID={{cookiecutter.project_name | replace('-', '_')}}_telemetry
|
|
13
|
+
{%- endif %}
|
|
14
|
+
{%- if cookiecutter.get('memory_bank') %}
|
|
15
|
+
|
|
16
|
+
# Long-term memory of each user, in Memory Bank.
|
|
17
|
+
MEMORY_BANK_ENABLED=true
|
|
18
|
+
{%- endif %}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Local development configuration
|
|
2
|
+
# For deployment, these are set via Terraform / the deploy command.
|
|
3
|
+
|
|
4
|
+
GOOGLE_GENAI_USE_ENTERPRISE=true
|
|
5
|
+
GOOGLE_CLOUD_PROJECT=your-gcp-project-id
|
|
6
|
+
GOOGLE_CLOUD_LOCATION=global
|
|
7
|
+
# Region for Claude calls: "global" or a region such as "us-east5".
|
|
8
|
+
CLOUD_ML_REGION=global
|
|
9
|
+
|
|
10
|
+
# Uncomment to log local runs too.
|
|
11
|
+
# BQ_ANALYTICS_DATASET_ID=your_dataset
|
|
12
|
+
|
|
13
|
+
# Long-term memory of each user, in Memory Bank (scaffold with --memory-bank).
|
|
14
|
+
# MEMORY_BANK_ENABLED=true
|
|
15
|
+
# Off Agent Runtime: the display name of the Agent Runtime engine that holds the
|
|
16
|
+
# memories, created when missing. Defaults to the agent's name.
|
|
17
|
+
# MEMORY_BANK_ENGINE_NAME=your-agent
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Copyright 2026 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: "claude"
|
|
16
|
+
description: "Claude Agent SDK agent (Claude on Gemini platform, A2A serving) — experimental; deploys to agent_runtime or cloud_run"
|
|
17
|
+
base_template: "empty_py"
|
|
18
|
+
example_question: "What's the weather in San Francisco?"
|
|
19
|
+
render_files: ["Dockerfile", ".env", "app/app_utils/settings.py"]
|
|
20
|
+
settings:
|
|
21
|
+
language: "python"
|
|
22
|
+
# agent_platform_sessions is ADK-only; the first entry is the default.
|
|
23
|
+
requires_session: true
|
|
24
|
+
session_types: ["in_memory", "cloud_sql"]
|
|
25
|
+
deployment_targets: ["agent_runtime", "cloud_run", "none"]
|
|
26
|
+
agent_directory: "app"
|
|
27
|
+
extra_dependencies: []
|
|
28
|
+
tags: ["claude", "a2a"]
|
|
29
|
+
frontend_type: "None"
|
|
30
|
+
# Accepts --memory-bank, which turns Memory Bank on in .env.
|
|
31
|
+
supports_memory_bank: true
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Coding Agent Guide
|
|
2
|
+
|
|
3
|
+
This is a Claude Agent SDK project, not an ADK one: `app/agent.py` declares
|
|
4
|
+
`root_agent` (a `ClaudeAgentOptions`), `app/app_utils/claude.py` runs it, and
|
|
5
|
+
`app/fast_api_app.py` serves it over A2A. Read
|
|
6
|
+
`.agents/skills/agents-cli-claude/SKILL.md` before changing any of them.
|
|
7
|
+
|
|
8
|
+
> **Experimental.** Agent Runtime and Cloud Run are the supported targets. Models
|
|
9
|
+
> are Claude on Gemini platform: the model named in `app/agent.py` must be enabled in Model
|
|
10
|
+
> Garden for the project. `agents-cli playground`, `eval dataset synthesize` and `eval
|
|
11
|
+
> optimize` need ADK, so this project refuses them, as does `publish gemini`
|
|
12
|
+
> on Agent Runtime.
|
|
13
|
+
|
|
14
|
+
## The loop
|
|
15
|
+
|
|
16
|
+
1. Build in `app/agent.py`, try it with `agents-cli run "prompt"`.
|
|
17
|
+
2. Write eval cases by hand in `tests/eval/datasets/`, then `agents-cli eval run` until it
|
|
18
|
+
holds up. `agents-cli eval compare` shows regressions; `agents-cli eval analyze` clusters
|
|
19
|
+
failures.
|
|
20
|
+
3. `uv run pytest tests/integration` before deploying.
|
|
21
|
+
4. `agents-cli infra single-project --apply` and `agents-cli deploy` **only after the user
|
|
22
|
+
approves them.**
|
|
23
|
+
|
|
24
|
+
## Rules
|
|
25
|
+
|
|
26
|
+
- Change only what was asked. Keep surrounding code, comments, and config values.
|
|
27
|
+
- **Never change the model** unless asked. On "model not available on your vertex
|
|
28
|
+
deployment", the model is not enabled for the project; ask the user to enable it.
|
|
29
|
+
- List the agent's tools explicitly (`tools=[...]`, `allowed_tools=[...]`); never give a
|
|
30
|
+
served agent Claude Code's `Bash` or file-editing tools unless the user asks.
|
|
31
|
+
- Run Python through uv: `uv run python script.py`, after `agents-cli install`.
|
|
32
|
+
- Same error three times means fix the cause, not retry.
|
|
33
|
+
- Terraform 409: `terraform import`, don't recreate.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Copyright 2026 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
|
+
# https://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 python:3.12-slim
|
|
16
|
+
|
|
17
|
+
COPY --from=ghcr.io/astral-sh/uv:0.8.13 /uv /uvx /bin/
|
|
18
|
+
|
|
19
|
+
WORKDIR /code
|
|
20
|
+
|
|
21
|
+
COPY ./pyproject.toml ./README.md ./uv.lock* ./
|
|
22
|
+
|
|
23
|
+
COPY ./{{cookiecutter.agent_directory}} ./{{cookiecutter.agent_directory}}
|
|
24
|
+
|
|
25
|
+
RUN uv sync --frozen
|
|
26
|
+
|
|
27
|
+
# Ships agent_config/: the agent's CLAUDE.md, .claude/ and .mcp.json.
|
|
28
|
+
COPY . .
|
|
29
|
+
|
|
30
|
+
# stdio MCP servers started with npx need Node.js; uncomment to install it.
|
|
31
|
+
# RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm \
|
|
32
|
+
# && rm -rf /var/lib/apt/lists/*
|
|
33
|
+
|
|
34
|
+
ARG AGENT_VERSION=0.0.0
|
|
35
|
+
ENV AGENT_VERSION=${AGENT_VERSION}
|
|
36
|
+
|
|
37
|
+
{%- if cookiecutter.agent_gateway %}
|
|
38
|
+
|
|
39
|
+
# Based on https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-gateway-runtime-deploy#configure-byoc
|
|
40
|
+
ARG AGENT_GATEWAY_ROOT_CERTIFICATES
|
|
41
|
+
RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \
|
|
42
|
+
mkdir -p /usr/local/share/ca-certificates; \
|
|
43
|
+
printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" \
|
|
44
|
+
| awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \
|
|
45
|
+
update-ca-certificates; \
|
|
46
|
+
fi
|
|
47
|
+
|
|
48
|
+
ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
|
|
49
|
+
ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
|
|
50
|
+
ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
|
|
51
|
+
{%- endif %}
|
|
52
|
+
|
|
53
|
+
EXPOSE 8080
|
|
54
|
+
|
|
55
|
+
CMD ["uv", "run", "uvicorn", "{{cookiecutter.agent_directory}}.fast_api_app:app", "--host", "0.0.0.0", "--port", "8080"]
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# agent_config
|
|
2
|
+
|
|
3
|
+
Claude Code settings for the served agent. Each conversation loads them as
|
|
4
|
+
project settings: put the agent's `CLAUDE.md`, `.claude/` (subagents in
|
|
5
|
+
`.claude/agents/`, skills, `settings.json`) and `.mcp.json` here.
|
|
6
|
+
|
|
7
|
+
The `CLAUDE.md`, `.claude/` and `.mcp.json` at the project root belong to your own
|
|
8
|
+
coding assistant: the served agent never reads them, and they are not built into the
|
|
9
|
+
image.
|