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
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.
|