agentme 0.14.0 → 0.15.0

package/.filedist-package.yml

@@ -1,5 +1,5 @@
 sets:
-  - package: xdrs-core@0.28.1
+  - package: xdrs-core@0.28.3
   # - package: git:https://github.com/flaviostutz/xdrs-core.git@main
     selector:
       files:

package/.xdrs/agentme/edrs/application/003-javascript-project-tooling.md

@@ -82,7 +82,7 @@ Builds that miss the threshold must not be merged.
 │   ├── dist/              # compiled files and packed .tgz artifacts
 │   └── src/               # all TypeScript source files
 │       ├── index.ts       # public API re-exports from app/
-│       ├── adapters/      # I/O boundary layer (following agentme-edr-021)
+│       ├── adapters/      # I/O boundary layer (following agentme-edr-026)
 │       │   ├── cli/       # inbound: CLI bootstrap and entry point
 │       │   ├── http/      # inbound: HTTP server bootstrap and handlers
 │       │   └── connectors/ # outbound: one folder per external resource
@@ -101,7 +101,7 @@ Builds that miss the threshold must not be merged.
 
 The root `Makefile` delegates every target to `/lib` then `/examples` in sequence. Parent Makefiles should call child Makefiles directly, and each module Makefile is responsible for running its actual tool commands through `mise exec --`.
 
-Internal source code MUST be organized following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities). The public API entry point (`index.ts`) re-exports from `app/`.
+Internal source code MUST be organized following [agentme-edr-026](026-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities). The public API entry point (`index.ts`) re-exports from `app/`.
 
 When a repository contains multiple JavaScript/TypeScript packages, each package MUST live in its own module folder such as `lib/my-package/` or `services/my-service/`, each with its own `Makefile`, `README.md`, `dist/`, and `.cache/`.
 
@@ -155,6 +155,6 @@ The examples folder MUST exist for any libraries and utilities that are publishe
 ## References
 
 - [agentme-edr-004](../principles/004-unit-test-requirements.md) — Coverage and unit-test baseline
-- [agentme-edr-021](021-pragmatic-hexagonal-architecture.md) — Internal adapter/application layer separation for applications
+- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Internal adapter/application layer separation for applications
 - [001-create-javascript-project](skills/001-create-javascript-project/SKILL.md) — scaffolds a new project following this structure
 

package/.xdrs/agentme/edrs/application/010-golang-project-tooling.md

@@ -47,7 +47,7 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 ├── main.go                    # binary entry point — argument dispatch only, no logic
 ├── .cache/                    # GOCACHE, GOMODCACHE, golangci-lint cache, coverage
 ├── dist/                      # built binaries and packaged outputs
-├── adapters/                  # I/O boundary layer (following agentme-edr-021)
+├── adapters/                  # I/O boundary layer (following agentme-edr-026)
 │   ├── cli/                   # inbound: CLI wiring — flag parsing, output formatting
 │   │   └── *.go               # subfolders per feature only when complexity warrants it
 │   ├── http/                  # inbound: HTTP server bootstrap and handlers
@@ -73,7 +73,7 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 
 **Key layout rules:**
 
-- Internal source code is organized following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
+- Internal source code is organized following [agentme-edr-026](026-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
 - One Go module per project (`go.mod` at the project root). In a monorepo, each Go project has its own `go.mod` in its subdirectory. No nested modules within a single project unless explicitly justified.
 - In a multi-module repository, each Go module MUST live in its own folder root with its own `Makefile`, `README.md`, `dist/`, and `.cache/`.
 - `main.go` is solely an argument dispatcher — it reads `os.Args[1]` and delegates to an `adapters/cli/<feature>/Run*()` function. No domain logic lives in `main.go`.
@@ -178,5 +178,5 @@ Use the standard library `flag` package for CLI flags. Each `adapters/cli/<featu
 
 ## References
 
-- [agentme-edr-021](021-pragmatic-hexagonal-architecture.md) — Defines the adapter/application separation that this layout follows
+- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Defines the adapter/application separation that this layout follows
 - [003-create-golang-project](skills/003-create-golang-project/SKILL.md) — scaffolds a new Go project following this structure

package/.xdrs/agentme/edrs/application/014-python-project-tooling.md

@@ -71,7 +71,7 @@ No tool MUST write cache or state files to the project root, `src/`, `tests/`, o
 │   ├── src/
 │   │   └── <package_name>/
 │   │       ├── __init__.py
-│   │       ├── adapters/       # I/O boundary layer (following agentme-edr-021)
+│   │       ├── adapters/       # I/O boundary layer (following agentme-edr-026)
 │   │       │   ├── cli/        # inbound: CLI bootstrap and entry point
 │   │       │   ├── http/       # inbound: HTTP server bootstrap
 │   │       │   └── connectors/ # outbound: one folder per external resource
@@ -96,7 +96,7 @@ Keep the repository root clean: source code, tests, distribution artifacts, and
 
 Use the `lib/src/` layout for import safety and packaging clarity. Keep tests under `lib/tests/` and shared test setup in `lib/tests/conftest.py`. Do not introduce `requirements.txt`, `setup.py`, `setup.cfg`, `tox.ini`, `ruff.toml`, or `ty.toml` by default; keep project metadata and tool configuration in `lib/pyproject.toml`.
 
-Internal source code MUST be organized following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
+Internal source code MUST be organized following [agentme-edr-026](026-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
 
 Libraries and shared utilities must include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../principles/007-project-quality-standards.md). Each example directory is its own Python project with its own `pyproject.toml`, and examples must import the library as a consumer would rather than reaching back into `lib/src/` with relative imports. Local example verification must install the wheel built into `lib/dist/`; do not use editable or path-based dependencies back to `lib/`.
 

package/.xdrs/agentme/edrs/application/015-cli-tool-standards.md

@@ -34,7 +34,7 @@ This keeps the user-facing command predictable while preserving a clean library
 
 #### CLI to application separation
 
-- Structure the software as `cli -> app` — the CLI adapter delegates to the application layer, following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md).
+- Structure the software as `cli -> app` — the CLI adapter delegates to the application layer, following [agentme-edr-026](026-pragmatic-hexagonal-architecture.md).
 - The CLI layer must only parse arguments, load config, call the application layer, and format output.
 - Domain logic must live in the application layer and be usable without CLI globals such as `argv`, `stdout`, or process exit handlers.
 - Every feature available through the CLI must also be available through the application API.
@@ -99,7 +99,7 @@ This keeps the user-facing command predictable while preserving a clean library
 
 ## References
 
-- [agentme-edr-021](021-pragmatic-hexagonal-architecture.md) - Defines the adapter/application separation that the CLI layer follows
+- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) - Defines the adapter/application separation that the CLI layer follows
 - [agentme-edr-003](003-javascript-project-tooling.md) - JavaScript project packaging and structure
 - [agentme-edr-007](../principles/007-project-quality-standards.md) - README and examples baseline
 - [agentme-edr-008](../devops/008-common-targets.md) - Standard command names for project entry points

package/.xdrs/agentme/edrs/application/018-ai-llm-development-standards.md

@@ -0,0 +1,180 @@
+---
+name: agentme-edr-policy-018-ai-llm-development-standards
+description: Defines the standard framework, provider configuration, observability approach, and LLM mocking patterns for simple LLM calls in Python. Use when building, reviewing, or scaffolding any code that makes direct LLM calls using LangChain, manages prompt context, or handles conversation history. For agentic patterns see agentme-edr-019, for workflow patterns see agentme-edr-020.
+apply-to: Python projects that make direct LLM calls, manage prompt context, or handle conversation threads
+valid-from: 2026-06-05
+---
+
+# agentme-edr-policy-018: AI LLM development standards
+
+## Context and Problem Statement
+
+LLM-based applications can be built at different levels of abstraction — from a single prompt call to a full autonomous agent or a complex multi-step workflow. Without a shared vocabulary and a prescribed framework, projects mix incompatible patterns for invoking models, managing context, and tracing requests.
+
+Which framework should be used for LLM calls, how should providers be configured, and what is the canonical meaning of "LLM", "agent", and "workflow" in this codebase?
+
+## Decision Outcome
+
+**Use LangChain as the standard framework for all direct LLM interactions. Adopt a strict three-tier conceptual model — LLM / Agent / Workflow — that maps each tier to a specific library.**
+
+### Conceptual model
+
+Three distinct tiers of LLM-based computation are recognized in this policy. Every component MUST be classified into exactly one tier:
+
+| Tier | What it is | Library |
+|---|---|---|
+| **LLM** | A request → response prompt exchange with a model. May include a conversation history or thread. No autonomous decision-making. | `langchain` / `langchain-openai` |
+| **Agent** | An LLM-based flow driven by a tool-invocation loop that the LLM itself plans and executes. The LLM decides which tools to call and when to stop. | `deepagents` |
+| **Workflow** | A directed graph of nodes that mixes LLM-based nodes (simple LLM calls or agentic loops) with deterministic algorithmic nodes. The graph topology is defined in code, not chosen by the LLM at runtime. | `langgraph` |
+
+These tiers nest: in general, a Workflow may contain Agent nodes; an Agent uses LLM calls internally. The tier of a component is determined by its outermost controlling structure.
+
+See [agentme-edr-019](019-ai-agents-development-standards.md) for Agent implementation standards and [agentme-edr-020](020-ai-workflow-development-standards.md) for Workflow implementation standards.
+
+### Details
+
+#### 01-conceptual-model
+
+Every component that interacts with an LLM MUST be classified as exactly one of the three tiers defined in the conceptual model table above: **LLM**, **Agent**, or **Workflow**.
+
+- Do NOT use the word "agent" to describe a component that only makes a single LLM call without a tool-invocation loop.
+- Do NOT use the word "workflow" to describe a component that is purely an LLM call with no graph structure.
+- When designing a new feature, identify the correct tier first. The tier determines which library and patterns apply (LangChain, deepagents, or LangGraph).
+
+**Function calling boundary:**
+
+- A **single** function call decided by the LLM (e.g., "call get_weather(location)") is still an LLM-tier interaction if the function is called once and the result is returned to the user.
+- An **iterative** function-calling loop where the LLM observes results and decides next actions autonomously is an Agent (see [agentme-edr-019](019-ai-agents-development-standards.md)).
+
+#### 02-llm-framework
+
+All direct LLM calls MUST use **LangChain** via the `langchain` packages.
+
+- Use `langchain-openai` as the provider integration layer. It supports both OpenAI and Azure OpenAI.
+- **Always configure LLM providers using explicit library attributes** such as `api_key`, `base_url`, `model`, `api_version`, etc. Never rely on environment variables for LLM configuration.
+- Configuration MUST be passed via constructor parameters or configuration objects, making dependencies explicit and testable.
+
+**Example of explicit configuration:**
+
+```python
+# Azure OpenAI configuration (explicit)
+llm = ChatOpenAI(
+    api_key=config.azure_api_key,
+    azure_endpoint=config.azure_endpoint,
+    api_version="2024-02-15-preview",
+    azure_deployment=config.azure_deployment
+)
+```
+
+#### 03-llm-observability
+
+Enable LangChain auto-tracing at every application entry point by calling `mlflow.langchain.autolog()` during startup, before any LLM call is made.
+
+- This captures inputs, outputs, token counts, and latency for every LangChain chain or runnable automatically.
+
+#### 04-unit-test-mocking
+
+LLM provider calls are external API calls and MUST be mocked in unit tests. Mocking LLM providers enables offline test execution while testing the logic, routing, and state management of LLM calls, agents, and workflows.
+
+Use LangChain's built-in fake models from `langchain_core.language_models.fake_chat_models`. Choose the utility based on what the code under test expects from the model:
+
+| Utility | When to use |
+|---|---|
+| `FakeListChatModel` | The code only reads the text content of the response (`AIMessage.content`). Returns plain-text `AIMessage` objects from a pre-defined list, in order. |
+| `GenericFakeChatModel` | The code expects tool calls, structured outputs, or needs to inspect the message type beyond plain text. Accepts a list of pre-built `AIMessage` (or `AIMessageChunk`) objects, giving full control over the response structure. |
+
+**`FakeListChatModel` — plain text responses:**
+
+```python
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+
+def test_document_approval_routing():
+    fake_model = FakeListChatModel(responses=[
+        "APPROVE",
+        "The document meets all quality criteria."
+    ])
+
+    workflow = DocumentWorkflow(model=fake_model)
+    result = workflow.run(input_doc)
+
+    assert result.status == "approved"
+    assert "quality criteria" in result.reasoning
+```
+
+**`GenericFakeChatModel` — tool-call or structured responses:**
+
+```python
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage
+import json
+
+def test_agent_tool_invocation():
+    # Simulate the LLM requesting a tool call, then producing a final answer
+    tool_call_msg = AIMessage(
+        content="",
+        tool_calls=[{
+            "name": "search_files",
+            "args": {"pattern": "*.py"},
+            "id": "call_1"
+        }]
+    )
+    final_msg = AIMessage(content="Found 3 Python files.")
+
+    fake_model = GenericFakeChatModel(messages=iter([tool_call_msg, final_msg]))
+
+    agent = FileAnalyzerAgent(model=fake_model)
+    result = agent.run()
+
+    assert result.summary == "Found 3 Python files."
+```
+
+**Injectable LLM pattern (required for testability):**
+
+Whenever a workflow, agent, or node makes LLM calls, it MUST accept the LLM instance as a constructor parameter or configuration field so that unit tests can inject a fake:
+
+```python
+class DocumentWorkflow:
+    def __init__(self, model: Optional[BaseChatModel] = None):
+        self.model = model or ChatOpenAI(
+            api_key=config.openai_api_key,
+            model="gpt-4"
+        )
+```
+
+This allows unit tests to inject `FakeListChatModel` or `GenericFakeChatModel` while production code uses the real provider.
+
+#### 05-prompt-management
+
+Prompt templates MUST be managed explicitly and versioned:
+
+- Store prompt templates as separate files in `prompts/` directory when they exceed 10 lines or are reused across multiple components.
+- Use LangChain `PromptTemplate` or `ChatPromptTemplate` for parameterized prompts.
+
+**Example prompt file structure:**
+
+```text
+lib/src/<package_name>/
+  prompts/
+    summarize.txt
+    extract_entities.txt
+```
+
+**Example usage:**
+
+```python
+from langchain.prompts import PromptTemplate
+
+prompt = PromptTemplate.from_file(
+    "prompts/summarize_v1.0.0.txt",
+    input_variables=["document"]
+)
+```
+
+## References
+
+- [agentme-edr-019](019-ai-agents-development-standards.md) — Agent implementation standards (deepagents, tool-invocation loops)
+- [agentme-edr-020](020-ai-workflow-development-standards.md) — Workflow implementation standards (LangGraph, MLflow run-level tracking)
+- [agentme-edr-004](../principles/004-unit-test-requirements.md) — Unit test requirements including external API mocking guidance
+- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
+- [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
+- [agentme-edr-021](021-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking

package/.xdrs/agentme/edrs/application/019-ai-agents-development-standards.md

@@ -0,0 +1,284 @@
+---
+name: agentme-edr-policy-019-ai-agents-development-standards
+description: Defines the standard framework and patterns for building AI agents with tool-invocation loops using the deepagents framework. Use when building agents where the LLM autonomously decides which tools to call and when to stop. For simple LLM calls see agentme-edr-018, for workflow orchestration see agentme-edr-020.
+apply-to: AI agent projects that use tool-invocation loops where the LLM decides which tools to call and when to stop
+valid-from: 2026-06-05
+---
+
+# agentme-edr-policy-019: AI agents development standards
+
+## Context and Problem Statement
+
+AI applications often need to give LLMs the ability to autonomously choose and invoke tools to accomplish tasks. Without standardized patterns for agent implementation, projects end up with incompatible approaches to tool definition, state management, and runtime environments.
+
+Which framework should be used for building agents with tool-invocation loops, and what are the essential patterns for agent state, tools, and execution environments?
+
+## Decision Outcome
+
+**Use the deepagents framework for all agent implementations where an LLM autonomously decides which tools to call and when to stop.**
+
+### Conceptual model
+
+An **Agent** is an LLM-based flow driven by a tool-invocation loop that the LLM itself plans and executes. The LLM decides which tools to call and when to stop. The agent follows a perceive → plan → act → observe cycle autonomously until it reaches a terminal state.
+
+### Details
+
+#### 01-agent-framework
+
+All agent implementations MUST use the **deepagents** framework.
+
+- Use deepagents whenever the LLM needs to autonomously select and invoke tools to accomplish a task.
+- The agent MUST follow the perceive → plan → act → observe cycle where the LLM observes tool outputs and decides the next action.
+- All LLM calls within agents MUST follow [agentme-edr-018](018-ai-llm-development-standards.md) for LangChain configuration and observability.
+
+**When to use agents vs workflows:**
+
+- Use an **agent** when the LLM should autonomously decide the sequence of tool calls based on runtime observations.
+- Use a **workflow** when the execution path is predefined in code, even if individual nodes involve LLM calls or agent subgraphs.
+- When in doubt, prefer workflows (explicit control flow) over agents (autonomous control flow) for maintainability and predictability.
+
+#### 02-local-sandbox
+
+When an agent requires a **local sandbox** — an isolated environment where the agent can read files, glob-search directories, and execute shell commands — use the **[deepagents](https://github.com/deepagents/deepagents) framework** to provide that sandbox.
+
+**When to apply this rule:**
+
+Use deepagents sandbox whenever ANY of the following is true:
+- The agent needs to execute shell commands or scripts in a controlled environment.
+- The agent needs to list, read, or search files across multiple directories at runtime.
+- The agent operates on user-supplied or generated file trees that must not escape a sandboxed boundary.
+
+**Integration requirements:**
+
+- Initialize the sandbox at the start of the agent run and shut it down in the same `try/finally` block.
+- Pass the sandbox handle into the agent's state so all tool calls share the same sandbox instance.
+- If the host-side code needs to pass files into the sandbox (e.g. generated config or input data), create a temporary directory with `tempfile.mkdtemp()`, write the files there, and mount it into the sandbox. Clean it up in the `finally` block.
+- Replace hand-rolled `read_file`, `search_files`, and `grep_file` tool implementations with the equivalent tools provided by deepagents.
+
+**Example:**
+
+```python
+import tempfile
+from deepagents import Sandbox
+
+def run_file_analysis_agent(input_files: List[Path]) -> AnalysisResult:
+    tmp_dir = tempfile.mkdtemp()
+    try:
+        # Copy input files to temp directory
+        for f in input_files:
+            shutil.copy(f, tmp_dir)
+        
+        # Initialize sandbox with mounted directory
+        sandbox = Sandbox(mount_paths={tmp_dir: "/workspace"})
+        
+        # Run agent with sandbox
+        agent = FileAnalysisAgent(sandbox=sandbox)
+        result = agent.run()
+        
+        return result
+    finally:
+        sandbox.shutdown()
+        shutil.rmtree(tmp_dir)
+```
+
+#### 03-agent-state-management
+
+**State type naming:**
+
+- Agent state types MUST end with `_agent_state` suffix (e.g., `file_analyzer_agent_state`)
+- Follow [agentme-edr-020](020-ai-workflow-development-standards.md) rule `11-state-type-conventions` when agents are used as workflow nodes
+
+#### 04-tool-definition-patterns
+
+Tools provided to agents MUST follow these patterns:
+
+**Tool signature:**
+
+```python
+from typing import Any, Dict
+
+def tool_name(arg1: str, arg2: int) -> Dict[str, Any]:
+    """
+    Brief description of what the tool does.
+    
+    Args:
+        arg1: Description of arg1
+        arg2: Description of arg2
+    
+    Returns:
+        Dictionary with tool execution results
+    """
+    # Tool implementation
+    return {"status": "success", "result": ...}
+```
+
+**Tool requirements:**
+
+- Tool names MUST be descriptive action verbs (e.g., `search_files`, `execute_command`, `read_document`)
+- Tool docstrings MUST clearly describe the tool's purpose, arguments, and return value (the LLM reads these)
+- Tools MUST return structured data (dictionaries or dataclasses), not bare strings or untyped values
+- Tools MUST handle errors gracefully and return error information in the result structure, not raise exceptions
+- Tools that interact with external systems MUST be placed in `adapters/connectors/` per [agentme-edr-026](026-pragmatic-hexagonal-architecture.md)
+
+**Error handling in tools:**
+
+```python
+def search_files(pattern: str, directory: str = ".") -> Dict[str, Any]:
+    """Search for files matching a glob pattern."""
+    try:
+        matches = list(Path(directory).glob(pattern))
+        return {
+            "status": "success",
+            "matches": [str(m) for m in matches],
+            "count": len(matches)
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error_message": str(e),
+            "error_type": type(e).__name__
+        }
+```
+
+#### 05-agent-error-handling-and-recovery
+
+Agents MUST implement robust error handling:
+
+**Maximum iteration limits:**
+
+- Every agent MUST have a maximum iteration limit to prevent infinite loops
+- The default maximum SHOULD be configurable and logged when reached
+- When the maximum is reached, the agent MUST return a structured failure result, not raise an exception
+
+**Tool failure handling:**
+
+- When a tool returns an error, the agent MUST be able to observe the error and decide on recovery actions
+- Tools MUST NOT raise exceptions for expected failures (network errors, file not found, etc.)
+- Agents MAY implement retry logic with exponential backoff for transient failures
+
+**Terminal states:**
+
+Agents MUST recognize and handle three terminal states:
+- **Success**: Goal achieved, task complete
+- **Failure**: Goal cannot be achieved, give up gracefully
+- **Timeout**: Maximum iterations reached, return partial results if possible
+
+#### 06-agent-naming-conventions
+
+Agent class names MUST follow the pattern `<Purpose>Agent` where `<Purpose>` describes what the agent does:
+
+**Good names:**
+- `FileAnalyzerAgent` — analyzes files
+- `CodeReviewerAgent` — reviews code
+- `DataExtractorAgent` — extracts data from documents
+
+**Bad names (FORBIDDEN):**
+- `Agent` (too generic)
+- `MainAgent` (not descriptive)
+- `MyAgent` (not descriptive)
+- `Agent1` (numbered, not semantic)
+
+When agents are used as nodes in workflows, the node name MUST use the `_agent` suffix per [agentme-edr-020](020-ai-workflow-development-standards.md) rule `09-node-naming-conventions`.
+
+#### 07-agent-observability
+
+Agent execution MUST be observable through logging and tracing:
+
+- Log each iteration of the perceive → plan → act → observe cycle with iteration number and tool selection.
+- Use structured logging (JSON) with fields: `iteration`, `tool_selected`, `tool_result_status`, `decision`.
+- For LLM calls within agents, follow [agentme-edr-018](018-ai-llm-development-standards.md) rule `03-llm-observability`.
+- When agents run as workflow nodes, MLflow tracking from the parent workflow automatically captures agent-level traces.
+
+**Example structured log entry:**
+
+```json
+{
+  "timestamp": "2026-06-05T10:30:45Z",
+  "agent": "FileAnalyzerAgent",
+  "iteration": 3,
+  "tool_selected": "search_files",
+  "tool_args": {"pattern": "*.py"},
+  "tool_result_status": "success",
+  "decision": "continue"
+}
+```
+
+#### 08-agent-unit-testing
+
+Agent LLM calls are external API calls and MUST be mocked in unit tests per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking`.
+
+Because agents drive a tool-invocation loop — where the LLM decides which tools to call — the fake model must return **tool-call messages** followed by a final answer. Use **`GenericFakeChatModel`** for this:
+
+```python
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage
+
+def test_file_analyzer_agent_calls_search_then_stops():
+    # Iteration 1: LLM requests a tool call
+    tool_call_msg = AIMessage(
+        content="",
+        tool_calls=[{
+            "name": "search_files",
+            "args": {"pattern": "*.py", "directory": "/workspace"},
+            "id": "call_1"
+        }]
+    )
+    # Iteration 2: LLM produces a final answer after observing the tool result
+    final_msg = AIMessage(content="Found 3 Python files matching the pattern.")
+
+    fake_model = GenericFakeChatModel(messages=iter([tool_call_msg, final_msg]))
+
+    agent = FileAnalyzerAgent(model=fake_model)
+    result = agent.run(directory="/workspace")
+
+    assert result.status == "success"
+    assert "3 Python files" in result.summary
+```
+
+Agents MUST be designed so that the LLM instance is injectable (constructor parameter) to allow test doubles. See [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking` for the injectable LLM pattern.
+
+**`mock_deep_agent`**
+
+Place `mock_deep_agent` in a shared test utilities module (e.g., `tests/helpers.py`) so all test files that need it can import it from one location and mock deep_agent instances when needed.
+
+**Example usage:**
+
+```python
+from tests.helpers import mock_deep_agent
+
+def test_workflow_calls_subagent(mocker):
+    mock_deep_agent(
+        mocker,
+        "mypackage.nodes.analysis_node.create_workflow_agent",
+        output={"status": "success", "findings": ["issue A"]}
+    )
+
+    result = run_analysis_workflow(input_data)
+
+    assert result.findings == ["issue A"]
+```
+
+#### 09-agent-composition
+
+When multiple agents are needed:
+
+- **Single agent with multiple tools:** Use when tools share a common goal and context (e.g., a code analysis agent with `read_file`, `search_code`, and `analyze_pattern` tools).
+- **Multiple agents as workflow nodes:** Use when agents have distinct responsibilities and outputs that feed into each other. Orchestrate them using LangGraph per [agentme-edr-020](020-ai-workflow-development-standards.md).
+- Do NOT create nested agent loops (agent calling agent autonomously). Use workflows for multi-agent orchestration.
+
+**Decision criteria:**
+
+| Pattern | When to use |
+|---|---|
+| Single agent + tools | All tools serve the same goal; agent completes in one session |
+| Multiple workflow-orchestrated agents | Each agent has a distinct goal; outputs flow between agents; deterministic sequencing needed |
+| Nested agents (FORBIDDEN) | Never — always use workflow orchestration instead |
+
+## References
+
+- [agentme-edr-018](018-ai-llm-development-standards.md) — LLM development standards (LangChain configuration, mocking patterns)
+- [agentme-edr-020](020-ai-workflow-development-standards.md) — Workflow development standards (using agents as workflow nodes)
+- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Hexagonal architecture (tool placement in adapters/connectors)
+- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
+- [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
+- [agentme-edr-021](021-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking