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/langchain/README.md
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# LangChain extension
|
|
2
|
+
|
|
3
|
+
> **Experimental.** Cloud Run and GKE are the supported deployment targets.
|
|
4
|
+
|
|
5
|
+
Run a [LangChain](https://python.langchain.com) agent, LangGraph graph, or Deep Agent through the `agents-cli` lifecycle: scaffold, run, evaluate, and deploy. The template scaffolds a Gemini ReAct agent 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 LangChain project |
|
|
8
|
+
|---------|---------------------------------|
|
|
9
|
+
| `playground` | Starts the local LangGraph dev server (`langgraph dev`). |
|
|
10
|
+
| `run` | Invokes the compiled graph in-process. |
|
|
11
|
+
| `eval generate` | Generates eval traces in the standard `EvaluationDataset` shape, so `eval grade` works unchanged. |
|
|
12
|
+
| `publish gemini` | Registers over A2A; refused on Agent Runtime, which needs ADK. |
|
|
13
|
+
| `eval dataset`, `eval optimize` | Refused with an explanation: both need an ADK agent. |
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
Install [Agents CLI](https://github.com/google/agents-cli) first, then scaffold a project from the template:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
agents-cli create my-agent --agent google/agents-cli-extensions/core/langchain/template -d cloud_run
|
|
21
|
+
cd my-agent && agents-cli install
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
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.
|
|
25
|
+
|
|
26
|
+
Then try it:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
agents-cli run "What's the weather in San Francisco?"
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`run` and `eval` call Gemini, so they need credentials: `GOOGLE_CLOUD_PROJECT` with Application Default Credentials, or `GOOGLE_API_KEY` / `GEMINI_API_KEY` for AI Studio.
|
|
33
|
+
|
|
34
|
+
### Add to an existing project
|
|
35
|
+
|
|
36
|
+
To use the overrides in a project you already have, install the extension instead of scaffolding:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
agents-cli extension add google/agents-cli-extensions#core/langchain/template --ref <tag|branch|sha>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Or install a release from PyPI (see the [root README](../../README.md#installing-from-pypi)):
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
agents-cli extension add 'pypi@agents-cli-extensions==<version>#core/langchain/template'
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
This installs only the command overrides, not the template's agent code or dependencies. The project must already provide what the overridden commands use:
|
|
49
|
+
|
|
50
|
+
- `app/agent.py` exposing `root_agent`, a compiled LangGraph graph (used by `run` and `eval generate`).
|
|
51
|
+
- `langgraph.json` pointing at that graph (used by `playground`).
|
|
52
|
+
- `langgraph`, `langchain`, and `langgraph-cli[inmem]` in the project's dependencies.
|
|
53
|
+
|
|
54
|
+
The extension is installed at project scope: it is recorded in `agents-cli-extensions.yaml` and vendored under `extensions/`, so commit both. `extension add` prompts before installing; pass `--yes` to skip the prompt in automation. See the [root README](../../README.md#managing-extensions) for updating and removing extensions.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agents-cli-langchain
|
|
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 LangChain/LangGraph
|
|
7
|
+
scaffolded by agents-cli, so ADK-specific instructions do not apply.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# LangChain project (agents-cli)
|
|
11
|
+
|
|
12
|
+
The agent is a compiled LangGraph graph 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, and Agent Runtime is degraded.** Deploy to cloud_run or gke. On
|
|
18
|
+
agent_runtime the app serves, but `publish gemini` is refused, the Console
|
|
19
|
+
playground cannot invoke it, and Console sessions/traces stay empty: all three want the
|
|
20
|
+
ADK `reasoning_engine` routes this project does not serve. Say so before recommending it.
|
|
21
|
+
|
|
22
|
+
## What ADK guidance maps to here
|
|
23
|
+
|
|
24
|
+
| ADK guidance | This project |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `LlmAgent`, `Agent`, `google.adk.tools` | `langchain.agents.create_agent`, plain Python functions as tools, or any compiled `StateGraph` |
|
|
27
|
+
| `adk web`, `adk run` | `agents-cli playground` (runs `langgraph dev`) |
|
|
28
|
+
| ADK runner behind `agents-cli run` | `agents-cli run` invokes the graph in-process |
|
|
29
|
+
| `agents-cli eval dataset synthesize`, `eval optimize` | Unavailable: both drive the agent through ADK. The command says so and exits |
|
|
30
|
+
| Add an `LlmAgent` in `app/agent.py` | Change the graph in `app/agent.py`; keep the name `root_agent` |
|
|
31
|
+
|
|
32
|
+
## The contract
|
|
33
|
+
|
|
34
|
+
Keep these two, whatever you build inside them:
|
|
35
|
+
|
|
36
|
+
- `app/agent.py` exports `root_agent`, a compiled graph with `messages` state.
|
|
37
|
+
Callers only use `root_agent.invoke({"messages": [...]})` and
|
|
38
|
+
`root_agent.astream(stream_mode="messages")`.
|
|
39
|
+
- `app/fast_api_app.py` exposes `app`. Every deployment target runs
|
|
40
|
+
`uvicorn app.fast_api_app:app`.
|
|
41
|
+
|
|
42
|
+
Adding a tool means writing a typed function with a docstring and passing it in
|
|
43
|
+
`tools=[...]`. Switching frameworks (LangGraph `StateGraph`,
|
|
44
|
+
`deepagents.create_deep_agent`) means rewriting `app/agent.py` only. Pre-1.0
|
|
45
|
+
LangChain (LCEL chains, `AgentExecutor`) is not supported: not compiled graphs.
|
|
46
|
+
|
|
47
|
+
## Commands
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
agents-cli install # uv sync
|
|
51
|
+
agents-cli playground # langgraph dev, port 8080
|
|
52
|
+
agents-cli run "hello" # invoke the graph in-process
|
|
53
|
+
agents-cli eval generate --dataset tests/eval/datasets/basic-dataset.json -o tests/eval/output/
|
|
54
|
+
agents-cli eval grade --traces tests/eval/output/<dataset>.json --config tests/eval/eval_config.yaml
|
|
55
|
+
agents-cli deploy # unchanged
|
|
56
|
+
agents-cli scaffold enhance -d cloud_run --cicd-runner github_actions # add infra later
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`playground`, `run` and `eval generate` are overridden by
|
|
60
|
+
`agents-cli-extension.yaml` at the project root. Prefix any command with
|
|
61
|
+
`AGENTS_CLI_DISABLE_OVERRIDES=1` to reach the built-in instead.
|
|
62
|
+
|
|
63
|
+
## Serving
|
|
64
|
+
|
|
65
|
+
A2A only: JSON-RPC at `POST /a2a/app`, card at
|
|
66
|
+
`/a2a/app/.well-known/agent-card.json`, health at `/health`. Token streaming
|
|
67
|
+
comes from `astream(stream_mode="messages")`.
|
|
68
|
+
|
|
69
|
+
## Common mistakes
|
|
70
|
+
|
|
71
|
+
- Renaming `root_agent` or `app`, which breaks `run`, eval and deploy.
|
|
72
|
+
- Reaching for `eval dataset synthesize` or `eval optimize`: they need ADK.
|
|
73
|
+
Write cases into `tests/eval/datasets/` and use `eval generate` + `eval grade`.
|
|
74
|
+
- Expecting `/run_sse` or ADK session routes; this server serves A2A.
|
|
75
|
+
- Running `agents-cli run --url ...` against a deployed agent without
|
|
76
|
+
`AGENTS_CLI_DISABLE_OVERRIDES=1`, which invokes the local graph instead.
|
|
77
|
+
- `run` and `eval generate` call Gemini on Gemini platform with ADC, so they need
|
|
78
|
+
`GOOGLE_CLOUD_PROJECT` and credentials, or `GOOGLE_API_KEY` / `GEMINI_API_KEY`
|
|
79
|
+
in `.env`.
|
|
80
|
+
|
|
81
|
+
## References
|
|
82
|
+
|
|
83
|
+
- `references/langchain.md` — framework contract and per-command detail.
|
|
84
|
+
- `references/samples.md` — agents worth copying from, by shape.
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# LangChain with agents-cli
|
|
2
|
+
|
|
3
|
+
This project was scaffolded from the LangChain template and carries
|
|
4
|
+
`agents-cli-extension.yaml` at its root, which overrides the framework-coupled
|
|
5
|
+
commands. Everything else (deploy, infra, eval grade) runs natively.
|
|
6
|
+
|
|
7
|
+
## What counts as "LangChain" here
|
|
8
|
+
|
|
9
|
+
The extension's only contract is that `app/agent.py` exports `root_agent` as a
|
|
10
|
+
compiled LangGraph graph with a `messages` state. Everything downstream (`run`,
|
|
11
|
+
`eval generate`, the A2A executor) uses just `root_agent.invoke({"messages": [...]})`
|
|
12
|
+
and `root_agent.astream(stream_mode="messages")`.
|
|
13
|
+
|
|
14
|
+
That covers the whole ecosystem, with no extension changes:
|
|
15
|
+
|
|
16
|
+
| You write | Import | Notes |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| **LangChain agent** | `from langchain.agents import create_agent` | The scaffolded default. LangChain 1.x compiles it to a graph. |
|
|
19
|
+
| **LangGraph graph** | `from langgraph.graph import StateGraph` | Hand-built graph; `.compile()` it and assign to `root_agent`. |
|
|
20
|
+
| **Deep Agent** | `from deepagents import create_deep_agent` | Also returns a `CompiledStateGraph` with `messages`; add `deepagents` to your deps. |
|
|
21
|
+
|
|
22
|
+
Legacy pre-1.0 LangChain (LCEL chains, `AgentExecutor`) is **not** supported:
|
|
23
|
+
those objects aren't compiled graphs, so `run` and A2A streaming won't work.
|
|
24
|
+
Wrap them in a `StateGraph` node if you need to bring one along.
|
|
25
|
+
|
|
26
|
+
## Adding deployment or CI/CD later
|
|
27
|
+
|
|
28
|
+
`create` writes the deployment target and CI/CD files, so pass them up front
|
|
29
|
+
when you can:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
agents-cli create my-lc-agent --agent google/agents-cli-extensions/core/langchain/template -d cloud_run --cicd-runner github_actions
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
For a project that skipped them, `agents-cli scaffold enhance -d cloud_run
|
|
36
|
+
--cicd-runner github_actions` re-renders from the template recorded in
|
|
37
|
+
`agents-cli-manifest.yaml` as `base_template`. It fetches that template, so it
|
|
38
|
+
needs network access, and it does not touch `app/`.
|
|
39
|
+
|
|
40
|
+
## Serving (A2A protocol)
|
|
41
|
+
|
|
42
|
+
The deployed agent is served over the Agent2Agent (A2A) protocol - the same
|
|
43
|
+
A2A contract the rest of the toolchain expects - so it works unchanged:
|
|
44
|
+
|
|
45
|
+
- Entrypoint: `uvicorn app.fast_api_app:app` (the scaffold Dockerfile CMD).
|
|
46
|
+
- A2A JSON-RPC endpoint: `POST /a2a/app`; Agent Card at
|
|
47
|
+
`/a2a/app/.well-known/agent-card.json`.
|
|
48
|
+
- `app/fast_api_app.py` wraps the compiled graph in an `AgentExecutor` and
|
|
49
|
+
mounts it with `add_a2a_routes_to_fastapi` (a2a-sdk 1.x).
|
|
50
|
+
- **Streaming**: the executor streams LLM token chunks via
|
|
51
|
+
`root_agent.astream(stream_mode="messages")` as incremental A2A task artifacts
|
|
52
|
+
(`capabilities.streaming=True`), so a real chat model streams token-by-token
|
|
53
|
+
to A2A clients. Graphs whose nodes don't stream tokens fall back to returning
|
|
54
|
+
the final reply as a single artifact.
|
|
55
|
+
|
|
56
|
+
The default `app/agent.py` is a Gemini ReAct agent (`langchain.agents.create_agent`)
|
|
57
|
+
with a sample `get_weather` tool. It uses Gemini platform via Application Default
|
|
58
|
+
Credentials, or AI Studio when `GOOGLE_API_KEY` or `GEMINI_API_KEY` is set in the
|
|
59
|
+
environment or `.env` (the scaffolded `.env.example` names the latter).
|
|
60
|
+
|
|
61
|
+
Query a deployed (or locally served) agent over A2A. The extension overrides `run`
|
|
62
|
+
with in-process invocation, so bypass it to reach the built-in A2A client:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
AGENTS_CLI_DISABLE_OVERRIDES=1 agents-cli run --url https://<service-url> --mode a2a --app-name app "hello"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## What stays native (do NOT override)
|
|
69
|
+
|
|
70
|
+
- `deploy` - native `agents-cli deploy`; dispatches to the project's configured deployment target.
|
|
71
|
+
- `eval grade`, `eval compare`, `eval analyze` - framework-agnostic.
|
|
72
|
+
- `infra`.
|
|
73
|
+
- `publish gemini` - overridden only to refuse on Agent Runtime, where
|
|
74
|
+
registration invokes the agent through ADK's `:streamQuery`. On cloud_run and gke
|
|
75
|
+
it runs the built-in, which registers over A2A. To register a LangChain agent,
|
|
76
|
+
deploy it to Cloud Run or GKE and publish from there.
|
|
77
|
+
|
|
78
|
+
## Journey
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
agents-cli create my-lc-agent --agent google/agents-cli-extensions/core/langchain/template -d cloud_run
|
|
82
|
+
cd my-lc-agent && agents-cli install
|
|
83
|
+
agents-cli run "hello" # in-process graph invocation
|
|
84
|
+
agents-cli eval generate --dataset tests/eval/datasets/basic-dataset.json -o tests/eval/output/
|
|
85
|
+
agents-cli eval grade --traces tests/eval/output/<dataset>.json --config tests/eval/eval_config.yaml
|
|
86
|
+
agents-cli deploy # native deploy (by deployment target)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Nothing is installed machine-wide: the overrides ride in the project, so a
|
|
90
|
+
teammate who clones it gets them with no setup step.
|
|
91
|
+
|
|
92
|
+
## Telemetry
|
|
93
|
+
|
|
94
|
+
`app/app_utils/telemetry.py` runs at startup from `app/fast_api_app.py` and reads
|
|
95
|
+
the same environment the ADK templates do, so the terraform in
|
|
96
|
+
`deployment/terraform/` configures both the same way:
|
|
97
|
+
|
|
98
|
+
| Variable | Effect |
|
|
99
|
+
|---|---|
|
|
100
|
+
| `LOGS_BUCKET_NAME` | Turns on prompt-response logging, uploaded under `gs://<bucket>/completions` |
|
|
101
|
+
| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `NO_CONTENT` records the exchange without message bodies; unset or `false` disables capture |
|
|
102
|
+
| `OTEL_SERVICE_NAME` | Service name on every span |
|
|
103
|
+
| `GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY` | Set by `agents-cli deploy` on Agent Runtime; `false` turns Cloud export off |
|
|
104
|
+
|
|
105
|
+
Cloud Trace works with no configuration once credentials resolve. Span names
|
|
106
|
+
differ from ADK's (`generate_content` comes from the shared google-genai
|
|
107
|
+
instrumentor either way; graph, agent and tool spans come from the LangChain
|
|
108
|
+
instrumentor rather than ADK's `invoke_agent`/`call_llm`).
|
|
109
|
+
|
|
110
|
+
## Pitfalls
|
|
111
|
+
|
|
112
|
+
- To run the built-in instead of the override: `AGENTS_CLI_DISABLE_OVERRIDES=1 agents-cli <cmd>`.
|
|
113
|
+
- The default `app/agent.py` calls Gemini on Gemini platform (ADC), so `run`/`eval`
|
|
114
|
+
need credentials (`GOOGLE_CLOUD_PROJECT` + ADC, or `GOOGLE_API_KEY` /
|
|
115
|
+
`GEMINI_API_KEY` for AI Studio).
|
|
116
|
+
- The deploy contract depends on `app/fast_api_app.py` exposing `app`; keep that
|
|
117
|
+
import working if you restructure the agent.
|
|
118
|
+
- Swapping in a different framework (Deep Agents, a hand-built graph) only means
|
|
119
|
+
rewriting `app/agent.py` and adding the dependency - leave `root_agent` and
|
|
120
|
+
`app/fast_api_app.py` alone.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Reference examples (LangChain ecosystem)
|
|
2
|
+
|
|
3
|
+
The examples are LangChain's own template and example repos, plus the LangChain docs. They are not
|
|
4
|
+
collected in one monorepo, so each entry below names its own repo.
|
|
5
|
+
|
|
6
|
+
**Reading this page is not studying an example.** Clone the repo and read its `README.md` (and
|
|
7
|
+
`AGENTS.md`, where there is one) before you write code.
|
|
8
|
+
|
|
9
|
+
**Study and adapt — don't scaffold from one.** Your project already has its scaffold: the example's
|
|
10
|
+
graph belongs in `app/agent.py` as `root_agent`, and `app/fast_api_app.py` stays as it is. Copy the
|
|
11
|
+
graph, tools and prompts; leave the repo's own serving, config and deploy layers behind.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
git clone --depth 1 https://github.com/langchain-ai/<repo> /tmp/<repo>
|
|
15
|
+
cat /tmp/<repo>/README.md
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
| You need | Study | Key files |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| The baseline shape: tools, prompt, state and config in a real layout | `react-agent`, the LangGraph project template | `src/react_agent/graph.py`, `tools.py`, `state.py`, `context.py` |
|
|
21
|
+
| Planning, sub-agents with isolated context, a virtual filesystem, runtime-loaded skills | `deepagents` (`create_deep_agent()` returns a compiled graph, so it drops into `root_agent`) | `AGENTS.md`, `examples/` (14 agents), `libs/deepagents/` |
|
|
22
|
+
| To understand that harness rather than adopt it | `deep-agents-from-scratch`, the same ideas as notebooks | `notebooks/1_todo.ipynb` → `4_full_agent.ipynb` |
|
|
23
|
+
| Iterative research with cited sources | `open_deep_research` | `src/open_deep_research/deep_researcher.py`, `configuration.py`, `prompts.py` |
|
|
24
|
+
| Web research into a fixed output schema | `data-enrichment`, with a reflection loop that judges the result | `src/enrichment_agent/graph.py`, `tools.py`, `state.py` |
|
|
25
|
+
| Memory across conversations | `langmem` (extraction, consolidation, retrieval over a store), or the [long-term memory](https://docs.langchain.com/oss/python/langchain/long-term-memory) docs | `docs/docs/hot_path_quickstart.md`, `background_quickstart.md` |
|
|
26
|
+
| Resuming a thread, durable state, time travel | [persistence](https://docs.langchain.com/oss/python/langgraph/persistence) | |
|
|
27
|
+
| Approval gate before a risky action | [interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) | |
|
|
28
|
+
| Multi-agent topologies | `langgraph-supervisor-py` (central router) · `langgraph-swarm-py` (peer handoff); both small | `supervisor.py` / `swarm.py`, `handoff.py` |
|
|
29
|
+
| An agent with hundreds of tools | `langgraph-bigtool` (retrieve tools instead of listing them) | |
|
|
30
|
+
| Retrieval over your own documents | [knowledge base](https://docs.langchain.com/oss/python/langchain/knowledge-base) · `rag-from-scratch` for technique | |
|
|
31
|
+
| Running untrusted code, a per-user sandbox | `deepagents` filesystem backends | |
|
|
32
|
+
| Moderating what the agent says | [middleware](https://docs.langchain.com/oss/python/langchain/middleware) | |
|
|
33
|
+
| Speaking A2A to other agents | `references/langchain.md` — your scaffold already serves A2A | |
|
|
34
|
+
|
|
35
|
+
Capabilities with no LangChain example: OAuth user consent, per-user credentials the model
|
|
36
|
+
must not see, event or schedule triggers, image and video generation. Those are application code
|
|
37
|
+
or infrastructure in a LangChain project — design them yourself.
|
|
38
|
+
|
|
39
|
+
Gemini models: your scaffold already wires up `ChatGoogleGenerativeAI` from `langchain-google-genai`,
|
|
40
|
+
which talks to Gemini platform with your ADC when `GOOGLE_GENAI_USE_VERTEXAI=True` is set (`app/agent.py`
|
|
41
|
+
sets it). Most of these repos default to Anthropic or OpenAI, so swap the model line and keep the
|
|
42
|
+
rest. Watch for embeddings too: memory and RAG examples often hardcode an OpenAI embedding model.
|
|
@@ -0,0 +1,32 @@
|
|
|
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
|
+
# Read by the CLI when this template is fetched; never copied into the
|
|
16
|
+
# generated project, because the overlay skips .template/.
|
|
17
|
+
name: "langchain"
|
|
18
|
+
description: "LangChain agent (LangGraph graph, A2A serving) — experimental; cloud_run and gke are the supported targets"
|
|
19
|
+
# empty_py leaves out the ADK agent layer, so this template supplies its own
|
|
20
|
+
# agent, server and tests.
|
|
21
|
+
base_template: "empty_py"
|
|
22
|
+
example_question: "What's the weather in San Francisco?"
|
|
23
|
+
# Files that get the scaffold's values filled in, such as the agent name.
|
|
24
|
+
render_files: ["app/agent.py"]
|
|
25
|
+
settings:
|
|
26
|
+
language: "python"
|
|
27
|
+
requires_session: false
|
|
28
|
+
deployment_targets: ["agent_runtime", "cloud_run", "gke", "none"]
|
|
29
|
+
agent_directory: "app"
|
|
30
|
+
extra_dependencies: []
|
|
31
|
+
tags: ["langchain", "a2a"]
|
|
32
|
+
frontend_type: "None"
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Coding Agent Guide
|
|
2
|
+
|
|
3
|
+
This is a LangChain project, not an ADK one: `app/agent.py`
|
|
4
|
+
compiles a LangGraph graph and `app/fast_api_app.py` serves it
|
|
5
|
+
over A2A. Read `.agents/skills/agents-cli-langchain/SKILL.md` before changing either.
|
|
6
|
+
|
|
7
|
+
> **Experimental.** Cloud Run and GKE are the supported targets. On Agent Runtime the
|
|
8
|
+
> container serves and traces normally, but everything that expects an ADK app is broken,
|
|
9
|
+
> because this project serves A2A and no `reasoning_engine` routes:
|
|
10
|
+
>
|
|
11
|
+
> - `agents-cli publish gemini` is refused: registration invokes the agent
|
|
12
|
+
> through `:streamQuery`. Publish from a Cloud Run or GKE deployment instead.
|
|
13
|
+
> - The Console playground cannot invoke the agent.
|
|
14
|
+
> - The Console's session and trace views stay empty (no managed Agent Runtime sessions;
|
|
15
|
+
> traces still reach Cloud Trace).
|
|
16
|
+
|
|
17
|
+
## The loop
|
|
18
|
+
|
|
19
|
+
1. Build in `app/`, try it with `agents-cli playground`
|
|
20
|
+
(LangGraph Studio) or `agents-cli run "prompt"`.
|
|
21
|
+
2. Write eval cases by hand in `tests/eval/datasets/`, then `agents-cli eval run` until it
|
|
22
|
+
holds up. `agents-cli eval compare` shows regressions; `agents-cli eval analyze` clusters
|
|
23
|
+
failures. `eval dataset synthesize` and `eval optimize` need an ADK agent to introspect,
|
|
24
|
+
so this project refuses them.
|
|
25
|
+
3. `uv run pytest tests/unit tests/integration` before deploying.
|
|
26
|
+
4. `agents-cli deploy` **only after the user approves it.**
|
|
27
|
+
|
|
28
|
+
## Rules
|
|
29
|
+
|
|
30
|
+
- Change only what was asked. Keep surrounding code, comments, and config values.
|
|
31
|
+
- **Never change the model** unless asked. On a model 404, fix `GOOGLE_CLOUD_LOCATION`
|
|
32
|
+
(try `global`), not the model name.
|
|
33
|
+
- Run Python through uv: `uv run python script.py`, after `agents-cli install`.
|
|
34
|
+
- Same error three times means fix the cause, not retry.
|
|
35
|
+
- Terraform 409: `terraform import`, don't recreate.
|
|
@@ -0,0 +1,54 @@
|
|
|
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
|
+
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/agents-cli/main/schemas/agents-cli-extension-v1alpha1.schema.json
|
|
16
|
+
|
|
17
|
+
# Scaffolded into every project made from this template, so the lifecycle
|
|
18
|
+
# commands that assume ADK run the LangChain equivalent instead.
|
|
19
|
+
schema: agents-cli-extension/v1alpha1
|
|
20
|
+
name: langchain
|
|
21
|
+
description: Run LangChain agents, LangGraph graphs, and Deep Agents through the agents-cli lifecycle.
|
|
22
|
+
|
|
23
|
+
requires:
|
|
24
|
+
agents_cli: ">=1.14,<2"
|
|
25
|
+
|
|
26
|
+
commands:
|
|
27
|
+
override:
|
|
28
|
+
playground:
|
|
29
|
+
run: ["uv", "run", "langgraph", "dev", "--no-browser", "--port", "8080"]
|
|
30
|
+
description: Start the local LangGraph dev server.
|
|
31
|
+
|
|
32
|
+
run:
|
|
33
|
+
run: ["uv", "run", "python", "scripts/run.py"]
|
|
34
|
+
description: Run the compiled agent graph with a single prompt.
|
|
35
|
+
|
|
36
|
+
# Claimed under the pre-rename name so CLIs that predate `publish gemini`
|
|
37
|
+
# still apply it; newer CLIs mirror the override onto `publish gemini`.
|
|
38
|
+
publish.gemini-enterprise:
|
|
39
|
+
run: ["uv", "run", "--with", "pyyaml", "python", "scripts/publish.py"]
|
|
40
|
+
description: Register over A2A; refuse on Agent Runtime, which needs ADK.
|
|
41
|
+
|
|
42
|
+
eval.generate:
|
|
43
|
+
run: ["uv", "run", "python", "scripts/eval_generate.py"]
|
|
44
|
+
description: Generate eval traces from the agent (EvaluationDataset shape).
|
|
45
|
+
|
|
46
|
+
# Both introspect an ADK agent object to build their dataset, so there is
|
|
47
|
+
# nothing to point them at here.
|
|
48
|
+
eval.dataset:
|
|
49
|
+
run: ["uv", "run", "python", "scripts/unsupported.py", "eval dataset"]
|
|
50
|
+
description: Unsupported for LangChain agents (needs an ADK agent to introspect).
|
|
51
|
+
|
|
52
|
+
eval.optimize:
|
|
53
|
+
run: ["uv", "run", "python", "scripts/unsupported.py", "eval optimize"]
|
|
54
|
+
description: Unsupported for LangChain agents (needs an ADK agent to introspect).
|
|
@@ -0,0 +1,19 @@
|
|
|
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
|
+
"""LangChain agent package."""
|
|
16
|
+
|
|
17
|
+
from .agent import root_agent
|
|
18
|
+
|
|
19
|
+
__all__ = ["root_agent"]
|
|
@@ -0,0 +1,61 @@
|
|
|
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
|
+
# ruff: noqa
|
|
15
|
+
|
|
16
|
+
"""LangChain agent: a Gemini ReAct agent with a sample tool.
|
|
17
|
+
|
|
18
|
+
Uses Gemini platform with Application Default Credentials, or AI Studio when
|
|
19
|
+
`GOOGLE_API_KEY` or `GEMINI_API_KEY` is set in the environment or a `.env` file.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
import os
|
|
23
|
+
|
|
24
|
+
from dotenv import load_dotenv
|
|
25
|
+
from langchain.agents import create_agent
|
|
26
|
+
from langchain_google_genai import ChatGoogleGenerativeAI
|
|
27
|
+
from langgraph.graph.state import CompiledStateGraph
|
|
28
|
+
|
|
29
|
+
load_dotenv()
|
|
30
|
+
|
|
31
|
+
if not (os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY")):
|
|
32
|
+
import google.auth
|
|
33
|
+
|
|
34
|
+
_, project_id = google.auth.default()
|
|
35
|
+
if project_id and "GOOGLE_CLOUD_PROJECT" not in os.environ:
|
|
36
|
+
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
|
|
37
|
+
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
|
|
38
|
+
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")
|
|
39
|
+
|
|
40
|
+
LLM = "gemini-3.8-flash"
|
|
41
|
+
|
|
42
|
+
llm = ChatGoogleGenerativeAI(model=LLM, temperature=0)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def get_weather(query: str) -> str:
|
|
46
|
+
"""Simulates a web search. Use it get information on weather."""
|
|
47
|
+
if "sf" in query.lower() or "san francisco" in query.lower():
|
|
48
|
+
return "It's 60 degrees and foggy."
|
|
49
|
+
return "It's 90 degrees and sunny."
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
root_agent: CompiledStateGraph = create_agent(
|
|
53
|
+
model=llm,
|
|
54
|
+
tools=[get_weather],
|
|
55
|
+
system_prompt="You are a helpful assistant",
|
|
56
|
+
# Keep in sync with create_params.root_agent_name in agents-cli-manifest.yaml:
|
|
57
|
+
# telemetry reports this name as gen_ai.agent.name, and agents-cli reports the
|
|
58
|
+
# manifest's value. Renaming the agent only here makes the two disagree, and
|
|
59
|
+
# anything selecting traces by name stops finding this agent's.
|
|
60
|
+
name="{{cookiecutter.root_agent_name}}",
|
|
61
|
+
)
|