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.
Files changed (107) hide show
  1. core/claude/README.md +35 -0
  2. core/claude/template/.agents/skills/agents-cli-claude/SKILL.md +106 -0
  3. core/claude/template/.agents/skills/agents-cli-claude/references/claude.md +386 -0
  4. core/claude/template/.agents/skills/agents-cli-claude/references/migrate-claude-agent.md +318 -0
  5. core/claude/template/.agents/skills/agents-cli-claude/references/migrate-from-aws.md +132 -0
  6. core/claude/template/.dockerignore +28 -0
  7. core/claude/template/.env +18 -0
  8. core/claude/template/.env.example +17 -0
  9. core/claude/template/.template/templateconfig.yaml +31 -0
  10. core/claude/template/AGENTS.md +33 -0
  11. core/claude/template/Dockerfile +55 -0
  12. core/claude/template/agent_config/README.md +9 -0
  13. core/claude/template/agents-cli-extension.yaml +49 -0
  14. core/claude/template/app/__init__.py +15 -0
  15. core/claude/template/app/agent.py +49 -0
  16. core/claude/template/app/app_utils/a2a.py +245 -0
  17. core/claude/template/app/app_utils/bq_analytics/__init__.py +124 -0
  18. core/claude/template/app/app_utils/bq_analytics/recorder.py +593 -0
  19. core/claude/template/app/app_utils/bq_analytics/redaction.py +209 -0
  20. core/claude/template/app/app_utils/bq_analytics/schema.py +394 -0
  21. core/claude/template/app/app_utils/bq_analytics/tables.py +104 -0
  22. core/claude/template/app/app_utils/bq_analytics/uploader.py +188 -0
  23. core/claude/template/app/app_utils/claude.py +297 -0
  24. core/claude/template/app/app_utils/completions.py +225 -0
  25. core/claude/template/app/app_utils/conversation.py +29 -0
  26. core/claude/template/app/app_utils/memory_bank.py +308 -0
  27. core/claude/template/app/app_utils/project_settings.py +91 -0
  28. core/claude/template/app/app_utils/reasoning_engine.py +237 -0
  29. core/claude/template/app/app_utils/remote_agents.py +349 -0
  30. core/claude/template/app/app_utils/remote_auth.py +159 -0
  31. core/claude/template/app/app_utils/replies.py +143 -0
  32. core/claude/template/app/app_utils/session_store.py +174 -0
  33. core/claude/template/app/app_utils/settings.py +24 -0
  34. core/claude/template/app/app_utils/telemetry/__init__.py +114 -0
  35. core/claude/template/app/app_utils/telemetry/call_counts.py +44 -0
  36. core/claude/template/app/app_utils/telemetry/cli_relay.py +266 -0
  37. core/claude/template/app/app_utils/telemetry/config.py +133 -0
  38. core/claude/template/app/app_utils/telemetry/logs.py +175 -0
  39. core/claude/template/app/app_utils/telemetry/metrics.py +270 -0
  40. core/claude/template/app/app_utils/telemetry/request_flush.py +104 -0
  41. core/claude/template/app/app_utils/telemetry/subagent_spans.py +80 -0
  42. core/claude/template/app/app_utils/telemetry/traces.py +166 -0
  43. core/claude/template/app/app_utils/turn_events.py +463 -0
  44. core/claude/template/app/app_utils/turn_options.py +219 -0
  45. core/claude/template/app/app_utils/workspaces.py +65 -0
  46. core/claude/template/app/fast_api_app.py +71 -0
  47. core/claude/template/app/feature_tools.py +27 -0
  48. core/claude/template/pyproject.toml +100 -0
  49. core/claude/template/scripts/eval_generate.py +340 -0
  50. core/claude/template/scripts/publish.py +66 -0
  51. core/claude/template/scripts/run.py +85 -0
  52. core/claude/template/scripts/unsupported.py +48 -0
  53. core/claude/template/tests/eval/datasets/basic-dataset.json +31 -0
  54. core/claude/template/tests/eval/eval_config.yaml +17 -0
  55. core/claude/template/tests/eval/response_quality.py +60 -0
  56. core/claude/template/tests/integration/test_server_e2e.py +168 -0
  57. core/claude/template/tests/load_test/.results/.placeholder +0 -0
  58. core/claude/template/tests/load_test/README.md +24 -0
  59. core/claude/template/tests/load_test/load_test.py +118 -0
  60. core/claude/template/tests/unit/conftest.py +63 -0
  61. core/claude/template/tests/unit/helpers.py +32 -0
  62. core/claude/template/tests/unit/test_a2a.py +432 -0
  63. core/claude/template/tests/unit/test_bq_analytics.py +928 -0
  64. core/claude/template/tests/unit/test_bq_redaction.py +89 -0
  65. core/claude/template/tests/unit/test_claude.py +825 -0
  66. core/claude/template/tests/unit/test_completions.py +369 -0
  67. core/claude/template/tests/unit/test_fast_api_app.py +59 -0
  68. core/claude/template/tests/unit/test_feature_tools.py +55 -0
  69. core/claude/template/tests/unit/test_memory_bank.py +625 -0
  70. core/claude/template/tests/unit/test_reasoning_engine.py +295 -0
  71. core/claude/template/tests/unit/test_remote_agents.py +517 -0
  72. core/claude/template/tests/unit/test_telemetry.py +991 -0
  73. core/claude/template/tests/unit/test_turn_events.py +309 -0
  74. core/claude/template/tests/unit/test_turn_options.py +394 -0
  75. core/claude/template/uv.lock +3029 -0
  76. core/langchain/README.md +54 -0
  77. core/langchain/template/.agents/skills/agents-cli-langchain/SKILL.md +84 -0
  78. core/langchain/template/.agents/skills/agents-cli-langchain/references/langchain.md +120 -0
  79. core/langchain/template/.agents/skills/agents-cli-langchain/references/samples.md +42 -0
  80. core/langchain/template/.template/templateconfig.yaml +32 -0
  81. core/langchain/template/AGENTS.md +35 -0
  82. core/langchain/template/agents-cli-extension.yaml +54 -0
  83. core/langchain/template/app/__init__.py +19 -0
  84. core/langchain/template/app/agent.py +61 -0
  85. core/langchain/template/app/app_utils/a2a.py +176 -0
  86. core/langchain/template/app/app_utils/content.py +37 -0
  87. core/langchain/template/app/app_utils/telemetry.py +154 -0
  88. core/langchain/template/app/fast_api_app.py +68 -0
  89. core/langchain/template/langgraph.json +7 -0
  90. core/langchain/template/pyproject.toml +102 -0
  91. core/langchain/template/scripts/_content.py +40 -0
  92. core/langchain/template/scripts/eval_generate.py +202 -0
  93. core/langchain/template/scripts/publish.py +59 -0
  94. core/langchain/template/scripts/run.py +59 -0
  95. core/langchain/template/scripts/unsupported.py +48 -0
  96. core/langchain/template/tests/eval/datasets/basic-dataset.json +16 -0
  97. core/langchain/template/tests/eval/eval_config.yaml +32 -0
  98. core/langchain/template/tests/eval/response_quality.py +60 -0
  99. core/langchain/template/tests/integration/test_server_e2e.py +173 -0
  100. core/langchain/template/tests/load_test/.results/.placeholder +0 -0
  101. core/langchain/template/tests/load_test/README.md +20 -0
  102. core/langchain/template/tests/load_test/load_test.py +82 -0
  103. core/langchain/template/uv.lock +3820 -0
  104. google_agents_cli_extensions-1.14.2.dist-info/METADATA +133 -0
  105. google_agents_cli_extensions-1.14.2.dist-info/RECORD +107 -0
  106. google_agents_cli_extensions-1.14.2.dist-info/WHEEL +4 -0
  107. google_agents_cli_extensions-1.14.2.dist-info/licenses/LICENSE +201 -0
core/claude/README.md ADDED
@@ -0,0 +1,35 @@
1
+ # Claude extension
2
+
3
+ > **Experimental.** Agent Runtime and Cloud Run are the supported deployment targets.
4
+
5
+ Run a Claude Agent SDK agent through the `agents-cli` lifecycle: scaffold, run, evaluate, and deploy. The template scaffolds an agent that calls Claude on Gemini platform and is served over [A2A](https://a2a-protocol.org), with no ADK dependency. It overrides only the commands that depend on the framework, and the rest, such as `deploy`, `infra`, and `eval grade`, run natively.
6
+
7
+ | Command | Behavior in a Claude project |
8
+ |---------|------------------------------|
9
+ | `run` | Runs the agent in-process with a single prompt. |
10
+ | `eval generate` | Generates eval traces in the standard `EvaluationDataset` shape, so `eval grade` works unchanged. |
11
+ | `publish gemini` | Registers over A2A; refused on Agent Runtime, which needs ADK. |
12
+ | `playground`, `eval dataset`, `eval optimize` | Refused with an explanation: the SDK has no local dev UI, and the eval commands need an ADK agent. |
13
+
14
+ ## Installation
15
+
16
+ Install [Agents CLI](https://github.com/google/agents-cli) first, then scaffold a project from the template:
17
+
18
+ ```bash
19
+ agents-cli create my-agent --agent google/agents-cli-extensions/core/claude/template -d cloud_run
20
+ cd my-agent && agents-cli install
21
+ ```
22
+
23
+ Append `@<tag|branch|sha>` to the template path to pin a version. The project's `agents-cli-extension.yaml` holds the overrides and is loaded automatically, so commit it.
24
+
25
+ Then try it:
26
+
27
+ ```bash
28
+ agents-cli run "What's the weather in San Francisco?"
29
+ ```
30
+
31
+ The model named in `app/agent.py` must be enabled in Model Garden for your project, and `run` and `eval` need `GOOGLE_CLOUD_PROJECT` with Application Default Credentials.
32
+
33
+ Pass `--memory-bank` to `create` (Agents CLI 1.14.0 or later) to give the agent long-term memory of each user in Memory Bank.
34
+
35
+ The project's coding-agent guide (`AGENTS.md`) and skill (`.agents/skills/agents-cli-claude/`) cover the agent's configuration, sessions, and migrating an existing Claude agent.
@@ -0,0 +1,106 @@
1
+ ---
2
+ name: agents-cli-claude
3
+ description: >
4
+ Use when working in this project — adding tools, editing the agent, running,
5
+ evaluating, serving or deploying it — or when guidance mentions ADK, LlmAgent,
6
+ google.adk, adk web, or an ADK runner. This project is a Claude Agent SDK
7
+ agent scaffolded by agents-cli, so ADK-specific instructions do not apply.
8
+ ---
9
+
10
+ # Claude Agent SDK project (agents-cli)
11
+
12
+ The agent is a `ClaudeAgentOptions` exported as `root_agent` from
13
+ `app/agent.py`. There is no `google.adk` dependency and no ADK runner. Other
14
+ `google-agents-cli-*` skills assume ADK; where they describe the agent itself,
15
+ this skill wins.
16
+
17
+ **Experimental.** Deploy to agent_runtime (limits: `references/claude.md`) or cloud_run.
18
+ The model runs on Claude on Gemini platform and must be enabled in Model Garden.
19
+
20
+ ## What ADK guidance maps to here
21
+
22
+ | ADK guidance | This project |
23
+ |---|---|
24
+ | `LlmAgent`, `Agent` | `ClaudeAgentOptions(model=..., system_prompt=..., ...)` assigned to `root_agent` |
25
+ | `Agent(name=...)` | `AGENT_NAME` in `app/app_utils/settings.py` (`ClaudeAgentOptions` has no name); keep it equal to `create_params.root_agent_name` in `agents-cli-manifest.yaml` |
26
+ | `google.adk.tools`, `FunctionTool` | `@tool(...)` async functions, served by `create_sdk_mcp_server` and passed in `mcp_servers` |
27
+ | `adk web`, `agents-cli playground` | Unavailable (no SDK dev UI). Use `agents-cli run`, or `uv run uvicorn app.fast_api_app:app --port 8080` |
28
+ | ADK runner behind `agents-cli run` | `agents-cli run` runs `root_agent` in process |
29
+ | `agents-cli eval dataset synthesize`, `eval optimize` | Unavailable: both drive the agent through ADK. The command says so and exits |
30
+ | `agents-cli eval generate --url` (traces from a served agent) | Unavailable: the server speaks A2A, not ADK's `/run_sse`. `eval generate` runs `root_agent` in process; the command refuses `--url` |
31
+ | ADK sessions | Claude sessions, one per A2A conversation; scaffold with `--session-type cloud_sql` to keep them across instances |
32
+
33
+ ## The contract
34
+
35
+ - `app/agent.py` exports `root_agent: ClaudeAgentOptions`. Only it changes when
36
+ you change the agent.
37
+ - `app/app_utils/claude.py` runs it. Leave `app/app_utils/` alone.
38
+ - The served agent's own `CLAUDE.md`, `.claude/` and `.mcp.json` go in `agent_config/`.
39
+ - `app/fast_api_app.py` exposes `app`. Every deployment target runs
40
+ `uvicorn app.fast_api_app:app`.
41
+
42
+ ## Adding a tool
43
+
44
+ ```python
45
+ @tool("lookup_order", "Look up an order by id.", {"order_id": str})
46
+ async def lookup_order(args: dict[str, Any]) -> dict[str, Any]:
47
+ return {"content": [{"type": "text", "text": f"Order {args['order_id']}: shipped"}]}
48
+
49
+
50
+ server = create_sdk_mcp_server(name="orders", tools=[lookup_order])
51
+
52
+ root_agent = ClaudeAgentOptions(
53
+ ...,
54
+ mcp_servers={"orders": server},
55
+ tools=[], # no built-in Claude Code tools
56
+ allowed_tools=["mcp__orders__lookup_order"], # mcp__<server>__<tool>
57
+ )
58
+ ```
59
+
60
+ A tool missing from `allowed_tools` is not available to the agent. Subagents (`agents=`
61
+ or `agent_config/.claude/agents/`) run through the built-in `Agent` tool: add `"Agent"` to both
62
+ `tools` and `allowed_tools`. Built-in tools
63
+ (`WebFetch`, `WebSearch`, `Read`, `Bash`, ...) go in both `tools` and `allowed_tools`;
64
+ keep `Bash` and file-editing tools out of a served agent unless the user asks.
65
+
66
+ ## Commands
67
+
68
+ ```bash
69
+ agents-cli install # uv sync
70
+ agents-cli run "hello" # run root_agent in process; prints a session id
71
+ agents-cli run "and?" --session-id <id> # continue that conversation
72
+ agents-cli eval generate --dataset tests/eval/datasets/basic-dataset.json -o tests/eval/output/
73
+ agents-cli eval grade --traces tests/eval/output/<dataset>.json --config tests/eval/eval_config.yaml
74
+ agents-cli deploy
75
+ agents-cli scaffold enhance -d cloud_run --cicd-runner github_actions # add infra later
76
+ ```
77
+
78
+ `run`, `eval generate`, `publish gemini`, `playground`, `eval dataset` and
79
+ `eval optimize` are overridden by `agents-cli-extension.yaml` at the project root.
80
+ Prefix any command with `AGENTS_CLI_DISABLE_OVERRIDES=1` to reach the built-in instead.
81
+
82
+ ## Serving
83
+
84
+ A2A: JSON-RPC at `POST /a2a/app`, card at `/a2a/app/.well-known/agent-card.json`,
85
+ health at `/health`; over A2A, text streams as it is generated. On Agent Runtime, also
86
+ `:query` and `:streamQuery` (new sessions and turns), which `agents-cli run --mode adk`
87
+ and an ingress Agent Gateway use. See `references/claude.md` for sessions, telemetry
88
+ and deployment.
89
+
90
+ ## Common mistakes
91
+
92
+ - Renaming `root_agent` or `app`, which breaks `run`, eval and deploy.
93
+ - Leaving `tools` unset: the agent then gets every built-in Claude Code tool.
94
+ - Using a model id that is not enabled on Gemini platform for the project.
95
+ - Reaching for `eval dataset synthesize` or `eval optimize`: they need ADK.
96
+ Write cases into `tests/eval/datasets/` and use `eval generate` + `eval grade`.
97
+ - Expecting `/run_sse` or ADK's REST session routes; this server serves A2A and
98
+ Agent Runtime's `:query` / `:streamQuery`.
99
+
100
+ ## References
101
+
102
+ - `references/claude.md` — how a turn runs, model access, project settings, sessions,
103
+ calling other agents, telemetry and logs.
104
+ - `references/migrate-claude-agent.md` — moving an existing Claude Agent SDK agent into
105
+ this project and onto GCP.
106
+ - `references/migrate-from-aws.md` — extra migration steps for an agent running on AWS.
@@ -0,0 +1,386 @@
1
+ # Claude Agent SDK with agents-cli
2
+
3
+ This project carries `agents-cli-extension.yaml` at its root, which overrides the
4
+ commands that assume ADK. Everything else (deploy, infra, eval grade) runs natively.
5
+
6
+ ## On Agent Runtime
7
+
8
+ The container serves A2A and exports traces as on Cloud Run. It also serves Agent
9
+ Runtime's `:query` and `:streamQuery` methods (see Serving), so `agents-cli run --mode
10
+ adk` works and an ingress Agent Gateway can govern the agent. `publish gemini` is refused,
11
+ the Console playground cannot invoke the agent, and the Console's session and trace views
12
+ stay empty; read traces in Cloud Trace. Transcripts stay on the instance unless you set
13
+ up Cloud SQL by hand (see Sessions).
14
+
15
+ ## How the agent runs
16
+
17
+ `app/app_utils/claude.py` runs each turn of `root_agent` in a Claude Code CLI
18
+ subprocess. For every turn it:
19
+
20
+ - points the CLI at Claude on Vertex AI (`CLAUDE_CODE_USE_VERTEX=1`,
21
+ `CLOUD_ML_REGION`, default `global`, and `ANTHROPIC_VERTEX_PROJECT_ID`, default
22
+ `GOOGLE_CLOUD_PROJECT`, else the ADC project). The region and project in the
23
+ environment or `.env` win. The Anthropic API is not supported: the CLI gets
24
+ `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` blanked.
25
+ - runs the turn in a working directory for its conversation,
26
+ `<tmp>/claude-agent/<AGENT_NAME>/<session id>`, so concurrent conversations don't
27
+ share files. It is a working directory, not a sandbox: tools you allow can still
28
+ reach the rest of the container.
29
+ - denies any tool outside `allowed_tools` (`permission_mode="dontAsk"`) unless
30
+ `root_agent` sets its own `permission_mode` or `can_use_tool`. Its other defaults can
31
+ be overridden in `root_agent.env`.
32
+
33
+ On Gemini platform the CLI always starts the system prompt with "You are Claude Code,
34
+ Anthropic's official CLI for Claude.", and no option removes it. Give the agent a name
35
+ in `system_prompt` ("You are Skye, ..."), or it introduces itself as Claude Code.
36
+
37
+ ## Model access
38
+
39
+ The model in `app/agent.py` (default `claude-haiku-4-5`) must be enabled for the
40
+ project in Model Garden; unversioned ids work. "not available on your vertex
41
+ deployment" means it is not enabled, a one-time Console step for the user. With no
42
+ `model=` (and no `ANTHROPIC_MODEL` or settings file naming one), a turn fails before any
43
+ model call rather than fall back to the CLI's default model.
44
+
45
+ The deployed identity needs `roles/aiplatform.user`. New projects deploy with Agent
46
+ Identity, and `agents-cli deploy` grants the role to the agent's Agent Identity principal.
47
+ A Cloud Run project whose `cloud_run.identity_default` is `service_account` deploys either
48
+ as the service account passed via `--service-account`, or as the default compute account,
49
+ which may lack the role (a 403 on `aiplatform.endpoints.predict`): with the user's
50
+ approval, run `agents-cli infra single-project --apply` and deploy with
51
+ `--service-account <name>-app@<project>.iam.gserviceaccount.com`, or grant the role.
52
+
53
+ Subagents often ask for an alias (`model: sonnet`). If that model isn't enabled, map
54
+ the alias: `env={"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-haiku-4-5"}`.
55
+
56
+ Model calls send `x-goog-api-client: agents-cli-app/<version>+claude-agent-sdk`, so
57
+ Google can count usage from agents-cli projects. `_traffic_tag_env` in
58
+ `app/app_utils/turn_options.py` appends it to `ANTHROPIC_CUSTOM_HEADERS`, after any
59
+ headers the agent or the server sets. `DO_NOT_TRACK=1` or `AGENTS_CLI_TELEMETRY=0`, in
60
+ the server's environment or the agent's `env`, turns it off.
61
+
62
+ The Claude Code CLI, and every tool, hook and stdio MCP server it runs, inherits the
63
+ server's environment, including the values passed with `--secrets`. Give an agent with
64
+ `Bash` or file tools only the secrets it needs.
65
+
66
+ ## Project settings (agent_config/)
67
+
68
+ The served agent's Claude Code files live in `agent_config/`: `CLAUDE.md`,
69
+ `CLAUDE.local.md`, `.claude/` (settings, output styles, skills, subagents, hooks) and
70
+ `.mcp.json`. They are copied into every conversation's working directory and loaded as
71
+ project settings whenever `setting_sources` is unset or includes `"project"`/`"local"`.
72
+ With `setting_sources=[]` nothing is loaded; `~/.claude` is never loaded unless the agent
73
+ asks for `"user"`. The same files at the project root belong to your coding assistant:
74
+ the served agent never reads them, and they are left out of the image. Each turn
75
+ replaces the working directory's copy, so settings the agent writes there don't load on
76
+ the next turn.
77
+ A `root_agent` with its own `cwd` is left alone: nothing is copied into or deleted from
78
+ that directory, and its own settings load only if `setting_sources` asks for them.
79
+
80
+ `permissions.allow` rules in `agent_config/.claude/settings.json` (and
81
+ `settings.local.json` with `"local"`) are added to `allowed_tools`. The CLI still logs
82
+ "Ignoring N permissions.allow entries ... not been trusted"; the rules apply anyway.
83
+
84
+ Shell hooks run in the container: a hook that calls a desktop tool (`afplay`,
85
+ `osascript`) fails there and is skipped. Python `hooks` and `can_use_tool` in
86
+ `root_agent` run in the server process unchanged; `can_use_tool` decides tools that are
87
+ not in `allowed_tools`.
88
+
89
+ ## Sessions
90
+
91
+ A conversation (an A2A `context_id`, or one eval case) maps to a Claude session. A UUID
92
+ `context_id` is the session id itself, so callers, transcripts and traces share one id.
93
+ Sessions are keyed by `AGENT_NAME` in `app/app_utils/settings.py`: give each agent its
94
+ own name; renaming it starts its conversations afresh.
95
+
96
+ With an authenticated A2A caller, a conversation is scoped to that caller. Without one
97
+ (the default on Cloud Run and Agent Runtime), anyone who sends a `context_id` resumes
98
+ and reads that conversation: treat it as a secret and never derive it from guessable
99
+ values.
100
+
101
+ Transcripts live on the instance's disk unless a session store is configured, so a
102
+ conversation ends when its instance restarts or a turn lands on another one. A bare
103
+ deploy scales to zero (`--min-instances 1` keeps one warm); the Agent Runtime engine
104
+ `infra single-project` creates keeps one instance always on, billed while idle.
105
+
106
+ On Cloud Run, scaffold with `--session-type cloud_sql` (or add it later with
107
+ `agents-cli scaffold enhance --session-type cloud_sql`): `infra single-project --apply`
108
+ then creates a Cloud SQL for PostgreSQL instance (billed while it exists) and wires it
109
+ into the service, and transcripts are mirrored to its `claude_session_store` table, so
110
+ conversations survive restarts and move between instances. Deployed without `infra`
111
+ first, the service has no database. Locally, transcripts stay on disk.
112
+
113
+ An agent can pass its own `session_store` in `root_agent`; it wins over Cloud SQL. If a
114
+ write to the store still fails after the SDK's retries, the turn fails, and the store
115
+ keeps the conversation without that turn: later turns, on any instance, resume as if it
116
+ didn't happen, though its tool calls did run. Rows are never deleted: schedule a
117
+ `DELETE ... WHERE mtime < <cutoff ms>` if transcripts must expire.
118
+
119
+ At most `CLAUDE_MAX_WORKSPACES` (default 100) conversation directories are kept per
120
+ instance; the least recently used beyond that are deleted. Without Cloud SQL an evicted
121
+ conversation starts fresh.
122
+
123
+ ### Cloud SQL on Agent Runtime (manual setup)
124
+
125
+ Agent Runtime has no `/cloudsql` socket, so the engine reaches a private-IP instance
126
+ through a PSC interface and the Cloud SQL Python Connector:
127
+
128
+ 1. Network: a VPC with a subnet of at least `/28` in the engine's region, and a network
129
+ attachment on it created with `--connection-preference=ACCEPT_MANUAL`
130
+ (`ACCEPT_AUTOMATIC` fails the deploy). With the user's approval, grant the Vertex AI
131
+ service agent (`service-<project-number>@gcp-sa-aiplatform.iam.gserviceaccount.com`)
132
+ `roles/compute.networkAdmin`.
133
+ 2. Database: a Cloud SQL for PostgreSQL instance with a private IP on that VPC through
134
+ Private Service Access (`--network=<vpc> --no-assign-ip`; the peering needs
135
+ `roles/servicenetworking.networksAdmin`), a database, and a password user whose
136
+ password is in Secret Manager.
137
+ 3. Code: `uv add "cloud-sql-python-connector[asyncpg]"`, and in `app/agent.py`:
138
+
139
+ ```python
140
+ import asyncio
141
+ import os
142
+
143
+ from app.app_utils.session_store import PostgresSessionStore
144
+
145
+
146
+ def _cloud_sql_store() -> PostgresSessionStore | None:
147
+ if not os.environ.get("INSTANCE_CONNECTION_NAME"):
148
+ return None # local runs keep transcripts on disk
149
+ state = {}
150
+
151
+ async def connect(*_args, **_kwargs):
152
+ from google.cloud.sql.connector import create_async_connector
153
+
154
+ # A connector belongs to the event loop that created it.
155
+ if state.get("loop") is not asyncio.get_running_loop():
156
+ state["connector"] = await create_async_connector(
157
+ ip_type="PRIVATE", refresh_strategy="lazy"
158
+ )
159
+ state["loop"] = asyncio.get_running_loop()
160
+ return await state["connector"].connect_async(
161
+ os.environ["INSTANCE_CONNECTION_NAME"],
162
+ "asyncpg",
163
+ user=os.environ["DB_USER"],
164
+ password=os.environ["DB_PASS"],
165
+ db=os.environ["DB_NAME"],
166
+ )
167
+
168
+ return PostgresSessionStore(connect=connect)
169
+ ```
170
+
171
+ and pass `session_store=_cloud_sql_store()` to `root_agent`.
172
+ 4. Deploy. The agent's identity exists only after the first deploy: deploy once, grant
173
+ its principal `roles/cloudsql.client` and `roles/secretmanager.secretAccessor` on the
174
+ secret, then deploy again with:
175
+
176
+ ```bash
177
+ agents-cli deploy \
178
+ --network-attachment projects/<project>/regions/<region>/networkAttachments/<name> \
179
+ --env-vars INSTANCE_CONNECTION_NAME=<project>:<region>:<instance>,DB_NAME=<db>,DB_USER=<user>,GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false \
180
+ --secrets DB_PASS=<secret>
181
+ ```
182
+
183
+ `GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false` is required with Agent Identity: the
184
+ connector's API calls fail with `401` on bound tokens. Later deploys keep the network
185
+ attachment.
186
+
187
+ ## Memory Bank (`--memory-bank`)
188
+
189
+ With `MEMORY_BANK_ENABLED=true` (what `--memory-bank` writes to `.env`, which `deploy`
190
+ sends to the agent), `app/app_utils/memory_bank.py` gives the agent memory of each user
191
+ across conversations, as ADK's memory tools do:
192
+
193
+ - Each turn, the user's memories that match the prompt are added to the system prompt.
194
+ BigQuery `LLM_REQUEST` rows and prompt logs show them; `AGENT_STARTING` shows only
195
+ the agent's own system prompt, as in ADK.
196
+ - After a turn succeeds, its prompt and the main agent's text, tool calls and tool results
197
+ (not its subagents') go to Memory Bank, which extracts memories from them.
198
+ - The model can search the memories with `search_memory`, which `app/feature_tools.py`
199
+ adds to `root_agent`.
200
+ - Memories are scoped to `AGENT_NAME` and the user: the authenticated A2A caller, else
201
+ `A2A_USER_<context_id>`, or the `user_id` of an Agent Runtime query. Without an
202
+ authenticated caller, an A2A conversation's memories serve only that conversation.
203
+ - On Agent Runtime, the agent's own engine holds the memories. Elsewhere, the Agent
204
+ Runtime engine named `MEMORY_BANK_ENGINE_NAME` (default `AGENT_NAME`) does; it is
205
+ created when missing, in `GOOGLE_CLOUD_LOCATION`, or `us-east1` when that is `global`.
206
+ - Memory Bank errors are logged and never fail a turn.
207
+
208
+ ## MCP servers and tools
209
+
210
+ In-process `@tool` functions run in the server process, from the project root, so
211
+ relative paths such as `db/products.json` keep working. stdio MCP servers run as
212
+ subprocesses: `npx`-based ones need the Node line in the Dockerfile uncommented. Servers
213
+ in `agent_config/.mcp.json` load when project settings do; their tools still need to be in
214
+ `allowed_tools` (`mcp__<server>__<tool>`).
215
+
216
+ ## Sizing
217
+
218
+ A tool-using turn takes about 200 MiB for the CLI subprocess plus ~70 MiB for the
219
+ server, so the default Cloud Run shape (4 GiB, concurrency 8) fits tool agents. Agents
220
+ that work with many files or run long sessions need more: deploy with `--memory 8Gi`
221
+ or `--concurrency 4`.
222
+
223
+ ## Eval traces
224
+
225
+ `agents-cli eval generate` runs each case in process, for `eval grade` and its tool
226
+ metrics. A failing case is dropped and reported. `TOOL_USE_QUALITY` errors on cases where
227
+ the agent called no tool; grade those in a dataset without it.
228
+
229
+ ## Serving (A2A protocol)
230
+
231
+ - Entrypoint: `uvicorn app.fast_api_app:app`. JSON-RPC at `POST /a2a/app`; Agent Card at
232
+ `/a2a/app/.well-known/agent-card.json`.
233
+ - Keep the card's `description` and skill in `_agent_card()` (`app/app_utils/a2a.py`)
234
+ describing what the agent does: callers read them to decide whether to call it.
235
+ - A failed turn ends the A2A task as `failed` with the error text.
236
+ - The reply is the text after the last tool call; text before a tool call ("Let me
237
+ check that.") streams but is not part of the reply. With `output_format` set, the
238
+ reply is the structured output as JSON, in one chunk.
239
+
240
+ On Agent Runtime, `:query` serves `async_create_session` and `:streamQuery` serves
241
+ `async_stream_query` (`app/app_utils/reasoning_engine.py`); other methods return 404. A
242
+ session id is a conversation id, scoped to the request's `user_id`, which the caller
243
+ chooses: anyone allowed to query the engine can resume a conversation whose id and
244
+ `user_id` they know. A turn without a session id starts a new conversation. A failed turn
245
+ ends with an event carrying `error_code` and `error_message`.
246
+
247
+ Query a served agent with `--url`:
248
+
249
+ ```bash
250
+ agents-cli run --url https://<service-url> --mode a2a --app-name app "hello"
251
+ # Agent Runtime: the engine's resource URL; the client finds the passthrough itself
252
+ agents-cli run --url https://<location>-aiplatform.googleapis.com/v1/projects/<project>/locations/<location>/reasoningEngines/<id> --mode a2a "hello"
253
+ # Agent Runtime, through :streamQuery
254
+ agents-cli run --url https://<location>-aiplatform.googleapis.com/v1/projects/<project>/locations/<location>/reasoningEngines/<id> --mode adk "hello"
255
+ ```
256
+
257
+ ## Calling other agents (A2A)
258
+
259
+ `remote_agent` in `app/app_utils/remote_agents.py` turns an agent served over A2A
260
+ (Claude, ADK or LangChain) into an in-process MCP server with one tool, `ask`:
261
+
262
+ ```python
263
+ from app.app_utils.remote_agents import remote_agent
264
+
265
+ billing = remote_agent(
266
+ "billing",
267
+ "https://billing-xyz.a.run.app/a2a/app", # where its agent card is served
268
+ description="Answers billing questions.",
269
+ )
270
+ root_agent = ClaudeAgentOptions(
271
+ ...,
272
+ mcp_servers={"billing": billing},
273
+ allowed_tools=["mcp__billing__ask"],
274
+ )
275
+ ```
276
+
277
+ - The URL is where the agent card is served: `https://<service>/a2a/app` for an agent
278
+ from this template, the service root for an ADK agent served with `to_a2a`. For an
279
+ Agent Runtime agent, its passthrough URL plus that path:
280
+ `https://<location>-aiplatform.googleapis.com/reasoningEngines/v1/projects/<project>/locations/<location>/reasoningEngines/<id>/api/a2a/app`.
281
+ - By default only Google-hosted agents get a token: an OAuth access token for an Agent
282
+ Runtime passthrough URL, a Google ID token for a `https://*.run.app` URL, nothing for
283
+ other hosts. What the caller needs, with the user's approval:
284
+ - Callee on Agent Runtime: `roles/aiplatform.user` in the callee's project (the
285
+ `infra` service account and Agent Identity already have it).
286
+ - Callee on Cloud Run: `roles/run.invoker` on the callee, granted to the caller's
287
+ service account or, from Agent Runtime, to the Agent Identity principal
288
+ `agents-cli deploy` prints. From Agent Runtime also pass `bind_id_token=False`:
289
+ Cloud Run rejects a bound token with a 401.
290
+ - `auth=True` sends the ID token to another host (custom domain, load balancer, IAP).
291
+ With user credentials that token works for any Cloud Run service you can call, so
292
+ run as a service account to call a host you don't trust. `auth=False` sends none;
293
+ `headers={...}` adds an API key or your own `Authorization`.
294
+ - A failed remote task, transport error or timeout (`timeout=`, default 300 s) reaches
295
+ the model as a tool error, not a failed turn. Follow-ups in the same conversation
296
+ continue the remote conversation.
297
+
298
+ ## Telemetry
299
+
300
+ `app/app_utils/telemetry/` exports to Cloud Trace, Cloud Logging and Cloud Monitoring
301
+ through the Telemetry API, using the standard GenAI span, log and metric names. Each
302
+ turn is an `invoke_agent` span, each tool call an `execute_tool` span, and the CLI's own
303
+ spans (`claude_code.llm_request` per model call, with tokens) nest under the turn.
304
+ Spans and metrics carry `gen_ai.agent.name`, which is `AGENT_NAME`; to rename the
305
+ agent, change it and `create_params.root_agent_name` in `agents-cli-manifest.yaml`
306
+ together.
307
+
308
+ Settings (also read from `.env`):
309
+
310
+ - `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` records prompts, replies
311
+ and tool arguments and results in spans; they are redacted otherwise. It also records
312
+ the system prompt the model got, recalled memories included, on the turn span.
313
+ - `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=0.1`
314
+ sample traces; every request is traced by default.
315
+ - `OTEL_SERVICE_NAME` sets the service name (`infra` sets it to the project name).
316
+ - `GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false` turns Cloud export off.
317
+ - Setting `CLAUDE_CODE_ENABLE_TELEMETRY`, `OTEL_TRACES_EXPORTER` or
318
+ `OTEL_EXPORTER_OTLP_(TRACES_)ENDPOINT` leaves the CLI's telemetry to you. Never use
319
+ the `console` exporter: it writes into the SDK's message stream.
320
+
321
+ The project is `GOOGLE_CLOUD_PROJECT`, else the ADC project. The identity needs
322
+ `roles/cloudtrace.agent`, `roles/logging.logWriter` and
323
+ `roles/monitoring.metricWriter`.
324
+
325
+ Metrics, as `prometheus.googleapis.com/<name>/histogram`: `gen_ai.invoke_agent.duration`,
326
+ `gen_ai.execute_tool.duration`, `gen_ai.invoke_agent.inference_calls`,
327
+ `gen_ai.invoke_agent.tool_calls` and `gen_ai.client.token.usage`.
328
+
329
+ ### Prompt-response logging
330
+
331
+ The `infra single-project` Terraform sets
332
+ `OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload` and
333
+ `OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH` on the deployed agent, and
334
+ `app/app_utils/completions.py` uploads each model call's inputs, outputs and system
335
+ prompt as JSONL there, in full whatever the capture setting says. The `completions`
336
+ table in the `<project>_telemetry` dataset reads them. A model call's inputs are the turn
337
+ so far, without earlier turns. On Agent Runtime the agent's identity needs write access
338
+ to the bucket, which a project Editor's `infra` run can't grant (uploads then fail with
339
+ a 403).
340
+
341
+ ### BigQuery Agent Analytics (`--bq-analytics`)
342
+
343
+ With `BQ_ANALYTICS_DATASET_ID` set (the `--bq-analytics` Terraform sets it on the
344
+ deployed agent), `app/app_utils/bq_analytics/` writes each turn's events to an
345
+ `agent_events` table with BigQuery Agent Analytics' schema, event types and `v_*` views,
346
+ so its SDK and Looker dashboards work. With the user's approval,
347
+ run `agents-cli infra single-project --apply` before the first deploy: it creates the
348
+ dataset and grants write access, which a bare `agents-cli deploy` does not.
349
+
350
+ - Subagents get their own `AGENT_*` and `LLM_*` rows; tool rows carry `tool_origin`
351
+ (`LOCAL`, `MCP`, `SUB_AGENT`, `A2A`). `INVOCATION_*` rows carry `session_cost_usd`,
352
+ the session's cost so far (don't sum it across turns).
353
+ - `session_id` is the A2A `context_id`; `trace_id` joins rows to Cloud Trace.
354
+ - `LLM_REQUEST` holds only the inputs new since the last call.
355
+ - Prompts, replies and tool arguments and results are logged up to 500 KB per field,
356
+ whatever the span capture setting says. Credentials are redacted: values under keys
357
+ such as `password`, `token`, `api_key` or `authorization`, and `key=value` pairs,
358
+ `Authorization` headers and `Bearer`/`Basic` tokens in text.
359
+ - Writes never fail a turn; failures are logged. Uncomment `BQ_ANALYTICS_DATASET_ID` in
360
+ `.env` to log local runs.
361
+
362
+ ## Logs
363
+
364
+ Python log records, the CLI's stderr included, go to Cloud Logging with their severity
365
+ and trace: on Cloud Run to `adk-otel`, on Agent Runtime to
366
+ `aiplatform.googleapis.com/reasoning_engine_stdout`. Find a turn's records with
367
+ `logName:"adk-otel" AND trace="<trace id>"`. The platform also keeps a plain-text copy
368
+ in the container's stderr, without severity. On Agent Runtime:
369
+
370
+ ```bash
371
+ gcloud logging read 'resource.type="aiplatform.googleapis.com/ReasoningEngine" AND resource.labels.reasoning_engine_id="ENGINE_ID" AND (log_id("aiplatform.googleapis.com/reasoning_engine_stdout") OR log_id("aiplatform.googleapis.com/reasoning_engine_stderr"))' --project=PROJECT --freshness=1h --limit=50 --format="table(timestamp,log_name.basename(),text_payload)"
372
+ ```
373
+
374
+ `ENGINE_ID` is the last segment of the engine's resource name. On Cloud Run filter on
375
+ `resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE"`.
376
+
377
+ ## Pitfalls
378
+
379
+ - To run the built-in instead of the override: `AGENTS_CLI_DISABLE_OVERRIDES=1 agents-cli <cmd>`.
380
+ - Each turn starts a CLI subprocess: allow a few seconds of startup.
381
+ - An instance runs a conversation's turns one at a time. Two instances can't coordinate
382
+ this: with more than one instance, send a conversation's turns one at a time, or one
383
+ of two concurrent turns is lost.
384
+ - `scaffold enhance` (e.g. `-d cloud_run --cicd-runner github_actions`) re-renders from
385
+ the template in `agents-cli-manifest.yaml` and leaves `app/` alone.
386
+ - Deployment depends on `app/fast_api_app.py` exposing `app`; keep that import working.