From b761a797ef40f7fe4ac5a5996e7c7a60e4868de1 Mon Sep 17 00:00:00 2001 From: mmontan Date: Wed, 11 Feb 2026 20:10:05 -0800 Subject: [PATCH] docs: Expand CLAUDE.md with detailed architecture and testing patterns Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c900603..2f09770 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -Agent Engine CLI (`ae`) is a command-line interface for managing Agent Engine. Built with Python using Typer for CLI framework and Rich for terminal output. +Agent Engine CLI (`ae`) is a command-line interface for managing Google Cloud Vertex AI Agent Engine deployments. Built with Python 3.11+ using Typer for CLI framework and Rich for terminal output. Wraps the `google-cloud-aiplatform` / `vertexai` SDK. ## Development Commands @@ -18,12 +18,33 @@ uv run ae --help # Run all tests uv run pytest +# Run a specific test file +uv run pytest tests/test_main.py + # Run a specific test -uv run pytest tests/test_main.py::test_version +uv run pytest tests/test_main.py::TestListCommand::test_list_with_agents ``` ## Architecture -- **Entry point**: `src/agent_engine_cli/main.py` - Contains the Typer app instance and all CLI commands -- **CLI binary**: Installed as `ae` via `[project.scripts]` in pyproject.toml -- **Testing**: Uses Typer's `CliRunner` for CLI command testing +### Module Layout (`src/agent_engine_cli/`) + +- **`main.py`** — Typer app instance with all CLI commands. Top-level commands: `version`, `list`, `get`, `create`, `delete`, `chat`. Subcommand groups: `sessions list`, `sandboxes list`, `memories list`. Every command accepts `--project/-p`, `--location/-l`, `--base-url`, and `--api-version`. +- **`client.py`** — `AgentEngineClient` wraps `vertexai.Client` and exposes typed methods (`list_agents`, `get_agent`, `create_agent`, `delete_agent`, `list_sessions`, `list_sandboxes`, `list_memories`). Agent IDs are resolved to full resource names (`projects/.../reasoningEngines/...`) via `_resolve_resource_name`. +- **`dependencies.py`** — `get_client()` factory function that serves as the DI seam. Tests patch `agent_engine_cli.main.get_client` to inject `FakeAgentEngineClient`. +- **`config.py`** — `resolve_project()` resolves `--project` or falls back to Application Default Credentials (ADC). Raises `ConfigurationError` on failure. +- **`chat.py`** — `run_chat()` async function for interactive streaming chat with an agent. Monkey-patches `google.genai._api_client` for debug logging. + +### Testing Patterns + +- Tests use `typer.testing.CliRunner` to invoke CLI commands. +- `tests/fakes.py` provides `FakeAgentEngineClient` — an in-memory fake that mirrors the real client interface. Tests populate its `_agents`, `_sessions`, `_sandboxes`, and `_memories` dicts directly. +- Commands are tested by patching `agent_engine_cli.main.get_client` to return a `FakeAgentEngineClient`. The `chat` command patches `agent_engine_cli.main.run_chat` instead. +- `test_client.py` mocks `vertexai` at the module level via `sys.modules` patching. +- The `CliRunner` is configured with `env={"COLUMNS": "200", "NO_COLOR": "1", "TERM": "dumb"}` to get stable output for assertions. + +### Key Design Decisions + +- `vertexai` is imported lazily inside `AgentEngineClient.__init__` and `chat.py` to keep CLI startup fast. +- The Vertex AI v1beta1 API uses `name` instead of `resource_name` on agent objects — the code uses `getattr` fallbacks to handle both. +- Agent spec data is accessed through `agent.api_resource.spec` first, falling back to `agent.spec`.