agentme 0.26.0 → 0.28.1
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.
- package/.filedist-package.yml +1 -1
- package/.xdrs/agentme/edrs/{principles → application}/002-coding-best-practices.md +1 -10
- package/.xdrs/agentme/edrs/application/003-javascript-project-tooling.md +3 -3
- package/.xdrs/agentme/edrs/application/010-golang-project-tooling.md +1 -1
- package/.xdrs/agentme/edrs/application/014-python-project-tooling.md +7 -7
- package/.xdrs/agentme/edrs/application/015-cli-tool-standards.md +5 -5
- package/.xdrs/agentme/edrs/{principles → application}/022-secrets-management.md +1 -1
- package/.xdrs/agentme/edrs/application/026-pragmatic-hexagonal-architecture.md +6 -6
- package/.xdrs/agentme/edrs/application/{018-ai-llm-development-standards.md → 040-ai-llm-development-standards.md} +13 -11
- package/.xdrs/agentme/edrs/application/{019-ai-agents-development-standards.md → 041-ai-agents-development-standards.md} +10 -10
- package/.xdrs/agentme/edrs/application/{020-ai-agents-quality-standards.md → 042-ai-agents-quality-standards.md} +14 -12
- package/.xdrs/agentme/edrs/application/{021-ai-workflow-development-standards.md → 043-ai-workflow-development-standards.md} +25 -22
- package/.xdrs/agentme/edrs/application/{029-ai-workflow-naming-conventions.md → 044-ai-workflow-naming-conventions.md} +9 -9
- package/.xdrs/agentme/edrs/application/{025-ai-agent-xdrs-knowledge-layer.md → 045-ai-agent-xdrs-knowledge-layer.md} +7 -7
- package/.xdrs/agentme/edrs/application/051-ai-eval-core-standards.md +121 -0
- package/.xdrs/agentme/edrs/application/052-ai-test-types-taxonomy.md +116 -0
- package/.xdrs/agentme/edrs/application/053-ai-eval-script.md +136 -0
- package/.xdrs/agentme/edrs/application/054-ai-eval-report-format.md +171 -0
- package/.xdrs/agentme/edrs/application/055-ai-eval-repeatability.md +75 -0
- package/.xdrs/agentme/edrs/application/skills/004-select-relevant-xdrs/SKILL.md +7 -7
- package/.xdrs/agentme/edrs/{application/024-ml-dataset-structure.md → data/050-ml-dataset-structure.md} +4 -4
- package/.xdrs/agentme/edrs/{principles → governance}/007-project-quality-standards.md +26 -21
- package/.xdrs/agentme/edrs/governance/013-contributing-guide-requirements.md +2 -2
- package/.xdrs/agentme/edrs/index.md +46 -25
- package/.xdrs/agentme/edrs/{devops → platform}/005-monorepo-structure.md +2 -0
- package/.xdrs/agentme/edrs/{devops → platform}/008-common-targets.md +13 -13
- package/.xdrs/agentme/edrs/{devops → platform}/027-environment-variable-configuration.md +2 -2
- package/.xdrs/agentme/edrs/principles/016-cross-language-module-structure.md +4 -4
- package/package.json +2 -2
- package/.xdrs/agentme/edrs/application/028-ai-eval-standards.md +0 -257
- package/.xdrs/agentme/edrs/application/030-ai-test-types-taxonomy.md +0 -98
- /package/.xdrs/agentme/edrs/{principles → application}/004-unit-test-requirements.md +0 -0
- /package/.xdrs/agentme/edrs/{principles → application}/009-error-handling.md +0 -0
- /package/.xdrs/agentme/edrs/{principles → application}/023-coding-abstraction-practices.md +0 -0
- /package/.xdrs/agentme/edrs/{observability → operations}/011-service-health-check-endpoint.md +0 -0
- /package/.xdrs/agentme/edrs/{devops → platform}/006-github-pipelines.md +0 -0
- /package/.xdrs/agentme/edrs/{devops → platform}/017-tool-execution-and-scripting.md +0 -0
- /package/.xdrs/agentme/edrs/{devops → platform}/skills/002-monorepo-setup/SKILL.md +0 -0
package/.filedist-package.yml
CHANGED
|
@@ -116,13 +116,4 @@ Types used in only **one** file MUST be declared in that same file. Move a type
|
|
|
116
116
|
|
|
117
117
|
#### 06-keep-test-files-next-to-source
|
|
118
118
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
**Recommended naming conventions:**
|
|
122
|
-
|
|
123
|
-
| Language / ecosystem | Source file | Test file |
|
|
124
|
-
|----------------------|------------------|------------------------|
|
|
125
|
-
| TypeScript / JS | `app.ts` | `app.test.ts` |
|
|
126
|
-
| Go | `handler.go` | `handler_test.go` |
|
|
127
|
-
| Rust | `parser.rs` | inline `#[cfg(test)]` |
|
|
128
|
-
| Python | `service.py` | `service_test.py` (same directory, or `tests/` when the ecosystem convention dictates otherwise) |
|
|
119
|
+
Test files MUST be placed beside the source file they cover, following the co-location and naming conventions defined in [agentme-edr-004 rule 04](004-unit-test-requirements.md). For Rust, use inline `#[cfg(test)]` modules instead of a separate test file.
|
|
@@ -32,7 +32,7 @@ Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelin
|
|
|
32
32
|
| **eslint** | Linting — code style and quality enforcement |
|
|
33
33
|
| **jest** | Testing — unit and integration test runner |
|
|
34
34
|
|
|
35
|
-
All commands are run exclusively through Makefiles, not through `package.json` scripts. The repository root MUST define a `.mise.toml` that pins at least Node.js and pnpm. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../
|
|
35
|
+
All commands are run exclusively through Makefiles, not through `package.json` scripts. The repository root MUST define a `.mise.toml` that pins at least Node.js and pnpm. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../platform/017-tool-execution-and-scripting.md). Calling project tools directly in docs, CI, or daily workflows instead of `make <target>` is not allowed.
|
|
36
36
|
|
|
37
37
|
#### ESLint
|
|
38
38
|
|
|
@@ -48,7 +48,7 @@ When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `modu
|
|
|
48
48
|
|
|
49
49
|
#### Coverage
|
|
50
50
|
|
|
51
|
-
Jest must enforce 80% line and branch coverage, following [agentme-edr-004](
|
|
51
|
+
Jest must enforce 80% line and branch coverage, following [agentme-edr-004](004-unit-test-requirements.md). Configure thresholds in `lib/jest.config.js`:
|
|
52
52
|
|
|
53
53
|
```js
|
|
54
54
|
coverageThreshold: {
|
|
@@ -154,7 +154,7 @@ The examples folder MUST exist for any libraries and utilities that are publishe
|
|
|
154
154
|
|
|
155
155
|
## References
|
|
156
156
|
|
|
157
|
-
- [agentme-edr-004](
|
|
157
|
+
- [agentme-edr-004](004-unit-test-requirements.md) — Coverage and unit-test baseline
|
|
158
158
|
- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Internal adapter/application layer separation for applications
|
|
159
159
|
- [001-create-javascript-project](skills/001-create-javascript-project/SKILL.md) — scaffolds a new project following this structure
|
|
160
160
|
|
|
@@ -30,7 +30,7 @@ A predictable layout and minimal external tooling keep Go projects approachable,
|
|
|
30
30
|
| **golangci-lint** | Linting — aggregates many linters in one fast run; configured via `.golangci.yml` |
|
|
31
31
|
| **monotag** | Version tagging from git history for the `publish` target |
|
|
32
32
|
|
|
33
|
-
All commands MUST be run exclusively through the Makefile and MUST NOT be called ad-hoc. The project root **MUST** define a `.mise.toml` that pins `go`, `golangci-lint`, and any other Go-related CLIs used by the project. Contributors and CI **MUST** bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe **MUST** execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../
|
|
33
|
+
All commands MUST be run exclusively through the Makefile and MUST NOT be called ad-hoc. The project root **MUST** define a `.mise.toml` that pins `go`, `golangci-lint`, and any other Go-related CLIs used by the project. Contributors and CI **MUST** bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe **MUST** execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../platform/017-tool-execution-and-scripting.md).
|
|
34
34
|
Direct installation of project-required Go CLIs with `go install ...@latest` as a repair step is **NOT** allowed unless an XDR for that repository explicitly permits it.
|
|
35
35
|
|
|
36
36
|
#### Project structure
|
|
@@ -36,7 +36,7 @@ A single dependency manager, isolated package internals under `lib/`, and a stan
|
|
|
36
36
|
|
|
37
37
|
All routine commands MUST run through the project `Makefile`. MUST NOT call `uv`, `ruff`, `pytest`, or `ty` directly in docs, CI, or daily development workflows.
|
|
38
38
|
|
|
39
|
-
The repository root MUST define a `.mise.toml` that pins Python and uv. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../
|
|
39
|
+
The repository root MUST define a `.mise.toml` that pins Python and uv. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../platform/017-tool-execution-and-scripting.md). Using routine project CLI commands directly outside the Makefile contract is not allowed.
|
|
40
40
|
|
|
41
41
|
The root `.venv/` is the canonical environment location for both the library and all examples. Subdirectory commands MUST set `UV_PROJECT_ENVIRONMENT` to the workspace root `.venv/` instead of creating nested virtual environments.
|
|
42
42
|
|
|
@@ -98,7 +98,7 @@ Use the `lib/src/` layout for import safety and packaging clarity. Keep tests un
|
|
|
98
98
|
|
|
99
99
|
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).
|
|
100
100
|
|
|
101
|
-
Libraries and shared utilities MUST include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../
|
|
101
|
+
Libraries and shared utilities MUST include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../governance/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/`.
|
|
102
102
|
|
|
103
103
|
Python keeps unit tests under `lib/tests/` by default because that remains the more common and maintainable convention for typed/package-based projects than co-locating tests beside every source file. Integration tests belong in `lib/tests_integration/`, and benchmark harnesses belong in `lib/tests_benchmark/` when they are more than a single micro-benchmark helper.
|
|
104
104
|
|
|
@@ -159,7 +159,7 @@ Adjust `target-version` to match the project's minimum supported Python version.
|
|
|
159
159
|
|
|
160
160
|
ty MUST run on every lint pass. The default rule set is the minimum baseline; projects may enable stricter rules as the codebase matures.
|
|
161
161
|
|
|
162
|
-
Pytest coverage MUST fail below 80% line and branch coverage, following [agentme-edr-004](
|
|
162
|
+
Pytest coverage MUST fail below 80% line and branch coverage, following [agentme-edr-004](004-unit-test-requirements.md).
|
|
163
163
|
|
|
164
164
|
#### Makefile targets
|
|
165
165
|
|
|
@@ -198,7 +198,7 @@ The root `Makefile` is the only contract for CI and contributors. It delegates l
|
|
|
198
198
|
| `dev` | Same as `run`, optionally with repository-specific dev defaults |
|
|
199
199
|
| `publish` | `mise exec -- uv publish --project .` after versioning and packaging are complete |
|
|
200
200
|
|
|
201
|
-
The root `Makefile` MUST remain the only contract for CI and contributors, in line with [agentme-edr-008](../
|
|
201
|
+
The root `Makefile` MUST remain the only contract for CI and contributors, in line with [agentme-edr-008](../platform/008-common-targets.md).
|
|
202
202
|
|
|
203
203
|
## Considered Options
|
|
204
204
|
|
|
@@ -209,7 +209,7 @@ The root `Makefile` MUST remain the only contract for CI and contributors, in li
|
|
|
209
209
|
|
|
210
210
|
## References
|
|
211
211
|
|
|
212
|
-
- [agentme-edr-004](
|
|
213
|
-
- [agentme-edr-007](../
|
|
214
|
-
- [agentme-edr-008](../
|
|
212
|
+
- [agentme-edr-004](004-unit-test-requirements.md) - Coverage and unit-test baseline
|
|
213
|
+
- [agentme-edr-007](../governance/007-project-quality-standards.md) - Examples and quality requirements
|
|
214
|
+
- [agentme-edr-008](../platform/008-common-targets.md) - Standard Makefile target names
|
|
215
215
|
- [005-create-python-project](skills/005-create-python-project/SKILL.md) - Scaffold a project following this EDR
|
|
@@ -53,7 +53,7 @@ This keeps the user-facing command predictable while preserving a clean library
|
|
|
53
53
|
#### Configuration
|
|
54
54
|
|
|
55
55
|
- Prefer flags and positional arguments for simple inputs.
|
|
56
|
-
- When configuration becomes long, nested, or repetitive, use a YAML config file instead of pushing all values into flags. See [agentme-edr-027](../
|
|
56
|
+
- When configuration becomes long, nested, or repetitive, use a YAML config file instead of pushing all values into flags. See [agentme-edr-027](../platform/027-environment-variable-configuration.md) for when `.env` values should be referenced from within that file.
|
|
57
57
|
- By default, config-file discovery and loading MUST happen in the CLI layer, not in the application layer.
|
|
58
58
|
- When a config file is supported, the CLI MUST try to load a YAML file from `[cwd]/[tool-name].yml` by default.
|
|
59
59
|
- The CLI MUST also support an explicit config path flag such as `--config`.
|
|
@@ -100,9 +100,9 @@ This keeps the user-facing command predictable while preserving a clean library
|
|
|
100
100
|
|
|
101
101
|
- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) - Defines the adapter/application separation that the CLI layer follows
|
|
102
102
|
- [agentme-edr-003](003-javascript-project-tooling.md) - JavaScript project packaging and structure
|
|
103
|
-
- [agentme-edr-007](../
|
|
104
|
-
- [agentme-edr-008](../
|
|
105
|
-
- [agentme-edr-009](
|
|
103
|
+
- [agentme-edr-007](../governance/007-project-quality-standards.md) - README and examples baseline
|
|
104
|
+
- [agentme-edr-008](../platform/008-common-targets.md) - Standard command names for project entry points
|
|
105
|
+
- [agentme-edr-009](009-error-handling.md) - Process error signaling and error handling expectations
|
|
106
106
|
- [agentme-edr-010](010-golang-project-tooling.md) - Go CLI structure and verbose logging baseline
|
|
107
107
|
- [agentme-edr-014](014-python-project-tooling.md) - Python packaging and CLI entry-point guidance
|
|
108
|
-
- [agentme-edr-027](../
|
|
108
|
+
- [agentme-edr-027](../platform/027-environment-variable-configuration.md) - Environment variable configuration files; defines how `.env` values are referenced from YAML config files
|
|
@@ -164,5 +164,5 @@ In library code (Python, JS/TS, Go), continue using the cross-platform libraries
|
|
|
164
164
|
|
|
165
165
|
## References
|
|
166
166
|
|
|
167
|
-
- [agentme-edr-008](../
|
|
167
|
+
- [agentme-edr-008](../platform/008-common-targets.md) - Common development script names (defines Makefile target conventions)
|
|
168
168
|
- [agentme-edr-009](009-error-handling.md) - Error handling (governs how the fallback exception should be raised)
|
|
@@ -102,7 +102,7 @@ mysystem/
|
|
|
102
102
|
#### 06-bootstrap-and-entry-points
|
|
103
103
|
|
|
104
104
|
- Each inbound adapter folder (`cli/`, `http/`, `grpc/`, etc.) MUST contain the bootstrap and entry point for that interface
|
|
105
|
-
- The project root Makefile must have targets to run the different inbound interfaces following [agentme-edr-008](../
|
|
105
|
+
- The project root Makefile must have targets to run the different inbound interfaces following [agentme-edr-008](../platform/008-common-targets.md) extension conventions (e.g. `run-http`, `run-grpc`)
|
|
106
106
|
- Bootstrap code lives in the adapter that receives inbound requests, not in a separate wiring layer
|
|
107
107
|
|
|
108
108
|
#### 07-minimum-complexity-threshold
|
|
@@ -133,7 +133,7 @@ Inbound adapters (`cli/`, `http/`, `grpc/`) are entry points and do not need to
|
|
|
133
133
|
|
|
134
134
|
#### 10-mock-file-strategy
|
|
135
135
|
|
|
136
|
-
When a mock implementation needs to be **reused across multiple tests or imported by an eval script** (e.g. `eval.py` using `mock_fixtures` from [agentme-edr-
|
|
136
|
+
When a mock implementation needs to be **reused across multiple tests or imported by an eval script** (e.g. `eval.py` using `mock_fixtures` from [agentme-edr-052](052-ai-test-types-taxonomy.md) rule `02`), define it in a dedicated `_mock` file rather than inline.
|
|
137
137
|
|
|
138
138
|
**When to use a `_mock` file vs inline:**
|
|
139
139
|
- Single-test use → define the mock inline inside the test file (per rule `09` example; no file needed)
|
|
@@ -149,7 +149,7 @@ When a mock implementation needs to be **reused across multiple tests or importe
|
|
|
149
149
|
| `order_service.ts` | `order_service_mock.ts` |
|
|
150
150
|
| `user_store.go` | `user_store_mock_test.go` |
|
|
151
151
|
|
|
152
|
-
**Placement:** follows the project's test file placement convention per [agentme-edr-004](
|
|
152
|
+
**Placement:** follows the project's test file placement convention per [agentme-edr-004](004-unit-test-requirements.md) rule `04`:
|
|
153
153
|
- Co-located test convention (TypeScript, Go) → mock file in the same directory as the source file
|
|
154
154
|
- Separate test folder convention (Python) → mock file mirrors the source path under the test folder (e.g. `lib/src/<pkg>/adapters/connectors/user-db/client.py` → `lib/tests/<pkg>/adapters/connectors/user-db/client_mock.py`)
|
|
155
155
|
|
|
@@ -160,6 +160,6 @@ When a mock implementation needs to be **reused across multiple tests or importe
|
|
|
160
160
|
## References
|
|
161
161
|
|
|
162
162
|
- [agentme-edr-016](../principles/016-cross-language-module-structure.md) — Defines the module-root structure (Makefile, dist/, .cache/) that wraps this internal layout
|
|
163
|
-
- [agentme-edr-002](
|
|
164
|
-
- [agentme-edr-004](
|
|
165
|
-
- [agentme-edr-
|
|
163
|
+
- [agentme-edr-002](002-coding-best-practices.md) — File size limits and code organization practices that complement this architecture
|
|
164
|
+
- [agentme-edr-004](004-unit-test-requirements.md) — Rule `04`: test file placement convention per language (governs `_mock` file placement in rule `10`)
|
|
165
|
+
- [agentme-edr-052](052-ai-test-types-taxonomy.md) — Rule `02`: `mock_fixtures` golden dataset envelope that drives `_mock` usage in eval scripts
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: agentme-edr-policy-
|
|
3
|
-
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-
|
|
2
|
+
name: agentme-edr-policy-040-ai-llm-development-standards
|
|
3
|
+
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-041, for workflow patterns see agentme-edr-043.
|
|
4
4
|
apply-to: Python projects that make direct LLM calls, manage prompt context, or handle conversation threads
|
|
5
5
|
valid-from: 2026-06-05
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
# agentme-edr-policy-
|
|
8
|
+
# agentme-edr-policy-040: AI LLM development standards
|
|
9
9
|
|
|
10
10
|
## Context and Problem Statement
|
|
11
11
|
|
|
@@ -29,7 +29,7 @@ Three distinct tiers of LLM-based computation are recognized in this policy. Eve
|
|
|
29
29
|
|
|
30
30
|
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.
|
|
31
31
|
|
|
32
|
-
See [agentme-edr-
|
|
32
|
+
See [agentme-edr-041](041-ai-agents-development-standards.md) for Agent implementation standards and [agentme-edr-043](043-ai-workflow-development-standards.md) for Workflow implementation standards.
|
|
33
33
|
|
|
34
34
|
### Details
|
|
35
35
|
|
|
@@ -44,7 +44,7 @@ Every component that interacts with an LLM MUST be classified as exactly one of
|
|
|
44
44
|
**Function calling boundary:**
|
|
45
45
|
|
|
46
46
|
- 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.
|
|
47
|
-
- An **iterative** function-calling loop where the LLM observes results and decides next actions autonomously is an Agent (see [agentme-edr-
|
|
47
|
+
- An **iterative** function-calling loop where the LLM observes results and decides next actions autonomously is an Agent (see [agentme-edr-041](041-ai-agents-development-standards.md)).
|
|
48
48
|
|
|
49
49
|
#### 02-llm-framework
|
|
50
50
|
|
|
@@ -71,7 +71,7 @@ llm = ChatOpenAI(
|
|
|
71
71
|
Enable LangChain auto-tracing at every application entry point by calling `mlflow.langchain.autolog()` during startup, before any LLM call is made.
|
|
72
72
|
|
|
73
73
|
- This captures inputs, outputs, token counts, and latency for every LangChain chain or runnable automatically.
|
|
74
|
-
- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../
|
|
74
|
+
- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../platform/008-common-targets.md) rule `09-ai-project-dev-targets`.
|
|
75
75
|
|
|
76
76
|
#### 04-unit-test-mocking
|
|
77
77
|
|
|
@@ -213,9 +213,11 @@ Return a JSON object with:
|
|
|
213
213
|
|
|
214
214
|
## References
|
|
215
215
|
|
|
216
|
-
- [agentme-edr-
|
|
217
|
-
- [agentme-edr-
|
|
218
|
-
- [agentme-edr-004](
|
|
216
|
+
- [agentme-edr-041](041-ai-agents-development-standards.md) — Agent implementation standards (deepagents, tool-invocation loops)
|
|
217
|
+
- [agentme-edr-043](043-ai-workflow-development-standards.md) — Workflow implementation standards (LangGraph, MLflow run-level tracking)
|
|
218
|
+
- [agentme-edr-004](004-unit-test-requirements.md) — Unit test requirements including external API mocking guidance
|
|
219
219
|
- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
|
|
220
|
-
- [agentme-edr-007](../
|
|
221
|
-
- [agentme-edr-
|
|
220
|
+
- [agentme-edr-007](../governance/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
|
|
221
|
+
- [agentme-edr-051](051-ai-eval-core-standards.md) — AI eval core standards: eval folder structure (rule `01`) and LLM-as-judge binary scoring contract (rule `02`)
|
|
222
|
+
- [agentme-edr-053](053-ai-eval-script.md) — AI eval script: entry-first loop, `--type` filtering, `mock_fixtures`, and MLflow conventions
|
|
223
|
+
- [agentme-edr-054](054-ai-eval-report-format.md) — AI eval report format: `report-<type>.md` template, Wilson CI, and convergence analysis
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: agentme-edr-policy-
|
|
3
|
-
description: Defines the structural patterns and design decisions for building AI agents with tool-invocation loops using the deepagents framework: framework selection, sandbox setup, state naming, agent naming, composition patterns, and system prompt structure. Use when designing or scaffolding a new agent. For tool definitions, error handling, observability, and testing see agentme-edr-
|
|
2
|
+
name: agentme-edr-policy-041-ai-agents-development-standards
|
|
3
|
+
description: Defines the structural patterns and design decisions for building AI agents with tool-invocation loops using the deepagents framework: framework selection, sandbox setup, state naming, agent naming, composition patterns, and system prompt structure. Use when designing or scaffolding a new agent. For tool definitions, error handling, observability, and testing see agentme-edr-042. For simple LLM calls see agentme-edr-040, for workflow orchestration see agentme-edr-043.
|
|
4
4
|
apply-to: AI agent projects — consult when designing agent structure, choosing sandbox approach, defining naming conventions, and composing multi-agent systems
|
|
5
5
|
valid-from: 2026-06-05
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
# agentme-edr-policy-
|
|
8
|
+
# agentme-edr-policy-041: AI agents development standards
|
|
9
9
|
|
|
10
10
|
## Context and Problem Statement
|
|
11
11
|
|
|
@@ -29,7 +29,7 @@ All agent implementations MUST use the **deepagents** framework.
|
|
|
29
29
|
|
|
30
30
|
- Use deepagents whenever the LLM needs to autonomously select and invoke tools to accomplish a task.
|
|
31
31
|
- The agent MUST follow the perceive → plan → act → observe cycle where the LLM observes tool outputs and decides the next action.
|
|
32
|
-
- All LLM calls within agents MUST follow [agentme-edr-
|
|
32
|
+
- All LLM calls within agents MUST follow [agentme-edr-040](040-ai-llm-development-standards.md) for LangChain configuration and observability.
|
|
33
33
|
|
|
34
34
|
**When to use agents vs workflows:**
|
|
35
35
|
|
|
@@ -87,7 +87,7 @@ def run_file_analysis_agent(input_files: List[Path]) -> AnalysisResult:
|
|
|
87
87
|
**State type naming:**
|
|
88
88
|
|
|
89
89
|
- Agent state types MUST end with `_agent_state` suffix (e.g., `file_analyzer_agent_state`)
|
|
90
|
-
- Follow [agentme-edr-
|
|
90
|
+
- Follow [agentme-edr-043](043-ai-workflow-development-standards.md) rule `11-state-type-conventions` when agents are used as workflow nodes
|
|
91
91
|
|
|
92
92
|
#### 04-agent-naming-conventions
|
|
93
93
|
|
|
@@ -104,14 +104,14 @@ Agent class names MUST follow the pattern `<Purpose>Agent` where `<Purpose>` des
|
|
|
104
104
|
- `MyAgent` (not descriptive)
|
|
105
105
|
- `Agent1` (numbered, not semantic)
|
|
106
106
|
|
|
107
|
-
When agents are used as nodes in workflows, the node name MUST use the `_agent` suffix per [agentme-edr-
|
|
107
|
+
When agents are used as nodes in workflows, the node name MUST use the `_agent` suffix per [agentme-edr-043](043-ai-workflow-development-standards.md) rule `09-node-naming-conventions`.
|
|
108
108
|
|
|
109
109
|
#### 05-agent-composition
|
|
110
110
|
|
|
111
111
|
When multiple agents are needed, one of these composition patterns MUST be chosen:
|
|
112
112
|
|
|
113
113
|
- **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).
|
|
114
|
-
- **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-
|
|
114
|
+
- **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-043](043-ai-workflow-development-standards.md).
|
|
115
115
|
- Nested agent loops (agent calling agent autonomously) MUST NOT be created. Use workflows for multi-agent orchestration.
|
|
116
116
|
|
|
117
117
|
**Decision criteria:**
|
|
@@ -267,7 +267,7 @@ def parse_agent_output(raw: str) -> FileAnalysisResult:
|
|
|
267
267
|
|
|
268
268
|
## References
|
|
269
269
|
|
|
270
|
-
- [agentme-edr-
|
|
271
|
-
- [agentme-edr-
|
|
272
|
-
- [agentme-edr-
|
|
270
|
+
- [agentme-edr-040](040-ai-llm-development-standards.md) — LLM development standards (LangChain configuration, mocking patterns)
|
|
271
|
+
- [agentme-edr-043](043-ai-workflow-development-standards.md) — Workflow development standards (using agents as workflow nodes)
|
|
272
|
+
- [agentme-edr-042](042-ai-agents-quality-standards.md) — Agent implementation quality standards (tool definitions, error handling, observability, unit testing)
|
|
273
273
|
- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: agentme-edr-policy-
|
|
3
|
-
description: Defines implementation quality standards for AI agents: tool definition patterns, error handling and recovery, observability, and unit testing. Apply alongside agentme-edr-
|
|
2
|
+
name: agentme-edr-policy-042-ai-agents-quality-standards
|
|
3
|
+
description: Defines implementation quality standards for AI agents: tool definition patterns, error handling and recovery, observability, and unit testing. Apply alongside agentme-edr-041 when implementing or reviewing agent code. For agent architecture and structural decisions (framework, sandbox, naming, composition, system prompts) see agentme-edr-041.
|
|
4
4
|
apply-to: AI agent implementation code — apply when writing tools, error handlers, logging, and unit tests for agents
|
|
5
5
|
valid-from: 2026-06-09
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
# agentme-edr-policy-
|
|
8
|
+
# agentme-edr-policy-042: AI agents quality standards
|
|
9
9
|
|
|
10
10
|
## Context and Problem Statement
|
|
11
11
|
|
|
@@ -15,7 +15,7 @@ How should agent tools be defined, what error handling must agents implement, ho
|
|
|
15
15
|
|
|
16
16
|
## Decision Outcome
|
|
17
17
|
|
|
18
|
-
**Agent implementations MUST follow the tool definition, error handling, observability, and unit testing standards defined here, alongside the structural decisions in [agentme-edr-
|
|
18
|
+
**Agent implementations MUST follow the tool definition, error handling, observability, and unit testing standards defined here, alongside the structural decisions in [agentme-edr-041](041-ai-agents-development-standards.md).**
|
|
19
19
|
|
|
20
20
|
### Details
|
|
21
21
|
|
|
@@ -100,9 +100,9 @@ Agent execution MUST be observable through logging and tracing:
|
|
|
100
100
|
|
|
101
101
|
- Log each iteration of the perceive → plan → act → observe cycle with iteration number and tool selection.
|
|
102
102
|
- Use structured logging (JSON) with fields: `iteration`, `tool_selected`, `tool_result_status`, `decision`.
|
|
103
|
-
- For LLM calls within agents, follow [agentme-edr-
|
|
103
|
+
- For LLM calls within agents, follow [agentme-edr-040](040-ai-llm-development-standards.md) rule `03-llm-observability`.
|
|
104
104
|
- When agents run as workflow nodes, MLflow tracking from the parent workflow automatically captures agent-level traces.
|
|
105
|
-
- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../
|
|
105
|
+
- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../platform/008-common-targets.md) rule `09-ai-project-dev-targets`.
|
|
106
106
|
|
|
107
107
|
**Example structured log entry:**
|
|
108
108
|
|
|
@@ -120,7 +120,7 @@ Agent execution MUST be observable through logging and tracing:
|
|
|
120
120
|
|
|
121
121
|
#### 04-agent-unit-testing
|
|
122
122
|
|
|
123
|
-
Agent LLM calls are external API calls and MUST be mocked in unit tests per [agentme-edr-
|
|
123
|
+
Agent LLM calls are external API calls and MUST be mocked in unit tests per [agentme-edr-040](040-ai-llm-development-standards.md) rule `04-unit-test-mocking`.
|
|
124
124
|
|
|
125
125
|
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:
|
|
126
126
|
|
|
@@ -150,7 +150,7 @@ def test_file_analyzer_agent_calls_search_then_stops():
|
|
|
150
150
|
assert "3 Python files" in result.summary
|
|
151
151
|
```
|
|
152
152
|
|
|
153
|
-
Agents MUST be designed so that the LLM instance is injectable (constructor parameter) to allow test doubles. See [agentme-edr-
|
|
153
|
+
Agents MUST be designed so that the LLM instance is injectable (constructor parameter) to allow test doubles. See [agentme-edr-040](040-ai-llm-development-standards.md) rule `04-unit-test-mocking` for the injectable LLM pattern.
|
|
154
154
|
|
|
155
155
|
**`mock_deep_agent`**
|
|
156
156
|
|
|
@@ -175,8 +175,10 @@ def test_workflow_calls_subagent(mocker):
|
|
|
175
175
|
|
|
176
176
|
## References
|
|
177
177
|
|
|
178
|
-
- [agentme-edr-
|
|
179
|
-
- [agentme-edr-
|
|
178
|
+
- [agentme-edr-041](041-ai-agents-development-standards.md) — Agent development standards (framework, sandbox, naming, composition, system prompts)
|
|
179
|
+
- [agentme-edr-040](040-ai-llm-development-standards.md) — LLM development standards (LangChain configuration, mocking patterns)
|
|
180
180
|
- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Hexagonal architecture (tool placement in adapters/connectors)
|
|
181
|
-
- [agentme-edr-007](../
|
|
182
|
-
- [agentme-edr-
|
|
181
|
+
- [agentme-edr-007](../governance/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
|
|
182
|
+
- [agentme-edr-051](051-ai-eval-core-standards.md) — AI eval core standards: eval folder structure (rule `01`) and LLM-as-judge binary scoring contract (rule `02`)
|
|
183
|
+
- [agentme-edr-053](053-ai-eval-script.md) — AI eval script: entry-first loop, `--type` filtering, `mock_fixtures`, and MLflow conventions
|
|
184
|
+
- [agentme-edr-054](054-ai-eval-report-format.md) — AI eval report format: `report-<type>.md` template, Wilson CI, and convergence analysis
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: agentme-edr-policy-
|
|
3
|
-
description: Defines the standard toolchain, framework, observability, and workflow patterns for building LangGraph workflows in Python. Use when scaffolding, reviewing, or extending AI workflow projects that orchestrate LLM calls, agents, and algorithmic nodes. For simple LLM calls see agentme-edr-
|
|
2
|
+
name: agentme-edr-policy-043-ai-workflow-development-standards
|
|
3
|
+
description: Defines the standard toolchain, framework, observability, and workflow patterns for building LangGraph workflows in Python. Use when scaffolding, reviewing, or extending AI workflow projects that orchestrate LLM calls, agents, and algorithmic nodes. For simple LLM calls see agentme-edr-040, for agentic patterns see agentme-edr-041. For naming conventions (nodes, states, routes, judge output schema) see agentme-edr-044.
|
|
4
4
|
apply-to: AI workflow projects using LangGraph StateGraph built with Python
|
|
5
5
|
valid-from: 2026-06-05
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
# agentme-edr-policy-
|
|
8
|
+
# agentme-edr-policy-043: AI workflow development standards
|
|
9
9
|
|
|
10
10
|
## Context and Problem Statement
|
|
11
11
|
|
|
@@ -23,21 +23,21 @@ Which tools, frameworks, and design patterns should AI workflow projects follow
|
|
|
23
23
|
|
|
24
24
|
Workflows MUST be built with **LangGraph**. Use LangGraph `StateGraph` to model each distinct workflow as an explicit directed graph with typed state.
|
|
25
25
|
|
|
26
|
-
For all direct LLM calls within workflow nodes, use LangChain per [agentme-edr-
|
|
26
|
+
For all direct LLM calls within workflow nodes, use LangChain per [agentme-edr-040](040-ai-llm-development-standards.md). For agent nodes with tool-invocation loops, use deepagents per [agentme-edr-041](041-ai-agents-development-standards.md).
|
|
27
27
|
|
|
28
28
|
#### 03-observability-and-experiment-tracking
|
|
29
29
|
|
|
30
30
|
Use **MLflow** for all workflow observability and evaluation:
|
|
31
31
|
|
|
32
32
|
- **Workflow-level tracking:** Wrap each workflow run with `mlflow.start_run()` to capture traces, parameters, and metrics locally.
|
|
33
|
-
- **LLM-level auto-tracing:** Enable LangChain auto-tracing per [agentme-edr-
|
|
33
|
+
- **LLM-level auto-tracing:** Enable LangChain auto-tracing per [agentme-edr-040](040-ai-llm-development-standards.md) rule `03-llm-observability` by calling `mlflow.langchain.autolog()` during application startup. This captures inputs, outputs, token counts, and latency for every LangChain call within workflow nodes.
|
|
34
34
|
- Log run parameters (model name, temperature, prompt version) and output metrics (accuracy, latency, token counts) using `mlflow.log_param` / `mlflow.log_metric`.
|
|
35
35
|
- Run a local MLflow tracking server with `mlflow ui` to inspect runs during development. Do not require a remote MLflow server for local development.
|
|
36
|
-
- The project Makefile MUST expose a `dev-mlflow` target to start the local MLflow tracking server, per [agentme-edr-008](../
|
|
36
|
+
- The project Makefile MUST expose a `dev-mlflow` target to start the local MLflow tracking server, per [agentme-edr-008](../platform/008-common-targets.md) rule `09-ai-project-dev-targets`.
|
|
37
37
|
|
|
38
38
|
#### 04-dataset-driven-accuracy-measurement
|
|
39
39
|
|
|
40
|
-
Projects MUST follow the eval dataset and implementation requirements defined in [agentme-edr-
|
|
40
|
+
Projects MUST follow the eval dataset and implementation requirements defined in [agentme-edr-051](051-ai-eval-core-standards.md) and [agentme-edr-053](053-ai-eval-script.md). Testing requirements (when evals are required, release gates) are defined in [agentme-edr-007](../governance/007-project-quality-standards.md) rule `09-ai-project-testing-requirements`.
|
|
41
41
|
|
|
42
42
|
#### 05-flow-documentation
|
|
43
43
|
|
|
@@ -101,17 +101,17 @@ lib/src/<package_name>/
|
|
|
101
101
|
|
|
102
102
|
#### 08-workflow-evals
|
|
103
103
|
|
|
104
|
-
Projects MUST follow the eval folder structure and script requirements defined in [agentme-edr-
|
|
104
|
+
Projects MUST follow the eval folder structure defined in [agentme-edr-051](051-ai-eval-core-standards.md) rule `01` and the eval script requirements defined in [agentme-edr-053](053-ai-eval-script.md). For LLM-as-judge scoring used in workflow verification nodes and evals, see [agentme-edr-051](051-ai-eval-core-standards.md) rule `02`.
|
|
105
105
|
|
|
106
106
|
#### 09-node-naming-conventions
|
|
107
107
|
|
|
108
|
-
Nodes MUST follow the naming conventions defined in [agentme-edr-
|
|
108
|
+
Nodes MUST follow the naming conventions defined in [agentme-edr-044](044-ai-workflow-naming-conventions.md) rule `01-node-naming-conventions`.
|
|
109
109
|
|
|
110
110
|
#### 10-workflow-unit-testing
|
|
111
111
|
|
|
112
|
-
All LLM calls within workflow nodes are external API calls and MUST be mocked in unit tests per [agentme-edr-
|
|
112
|
+
All LLM calls within workflow nodes are external API calls and MUST be mocked in unit tests per [agentme-edr-040](040-ai-llm-development-standards.md) rule `04-unit-test-mocking`. Workflow unit tests MUST run fully offline with no real LLM provider calls.
|
|
113
113
|
|
|
114
|
-
Choose the mock utility per [agentme-edr-
|
|
114
|
+
Choose the mock utility per [agentme-edr-040](040-ai-llm-development-standards.md) rule `04-unit-test-mocking`. For workflows containing `_agent` nodes that drive a tool-invocation loop, MUST use `GenericFakeChatModel`.
|
|
115
115
|
|
|
116
116
|
**Example — workflow with plain-text LLM nodes:**
|
|
117
117
|
|
|
@@ -152,19 +152,19 @@ def test_document_workflow_with_agent_node():
|
|
|
152
152
|
assert result.status == "approved"
|
|
153
153
|
```
|
|
154
154
|
|
|
155
|
-
Workflows MUST accept the LLM instance as a constructor parameter so that unit tests can inject a fake. See the injectable LLM pattern in [agentme-edr-
|
|
155
|
+
Workflows MUST accept the LLM instance as a constructor parameter so that unit tests can inject a fake. See the injectable LLM pattern in [agentme-edr-040](040-ai-llm-development-standards.md) rule `04-unit-test-mocking`.
|
|
156
156
|
|
|
157
157
|
#### 11-state-type-conventions
|
|
158
158
|
|
|
159
|
-
State types MUST follow the conventions defined in [agentme-edr-
|
|
159
|
+
State types MUST follow the conventions defined in [agentme-edr-044](044-ai-workflow-naming-conventions.md) rule `02-state-type-conventions`.
|
|
160
160
|
|
|
161
161
|
#### 12-workflow-naming-conventions
|
|
162
162
|
|
|
163
|
-
Workflows MUST be named following the conventions in [agentme-edr-
|
|
163
|
+
Workflows MUST be named following the conventions in [agentme-edr-044](044-ai-workflow-naming-conventions.md) rule `04-workflow-naming-conventions`.
|
|
164
164
|
|
|
165
165
|
#### 13-judge-node-output-format
|
|
166
166
|
|
|
167
|
-
Judge nodes MUST use the output format defined in [agentme-edr-
|
|
167
|
+
Judge nodes MUST use the output format defined in [agentme-edr-044](044-ai-workflow-naming-conventions.md) rule `03-judge-node-output-format`.
|
|
168
168
|
|
|
169
169
|
#### 15-workflow-state-persistence
|
|
170
170
|
|
|
@@ -197,15 +197,18 @@ result = graph.invoke(input_state, config={"thread_id": "session-123"})
|
|
|
197
197
|
|
|
198
198
|
#### 16-cross-element-naming-coherence
|
|
199
199
|
|
|
200
|
-
All workflow elements MUST maintain naming coherence as defined in [agentme-edr-
|
|
200
|
+
All workflow elements MUST maintain naming coherence as defined in [agentme-edr-044](044-ai-workflow-naming-conventions.md) rule `05-cross-element-naming-coherence`.
|
|
201
201
|
|
|
202
202
|
## References
|
|
203
203
|
|
|
204
|
-
- [agentme-edr-
|
|
205
|
-
- [agentme-edr-
|
|
206
|
-
- [agentme-edr-
|
|
204
|
+
- [agentme-edr-044](044-ai-workflow-naming-conventions.md) — AI workflow naming conventions: node suffixes/prefixes, state types, judge output schema, workflow names, and cross-element coherence
|
|
205
|
+
- [agentme-edr-040](040-ai-llm-development-standards.md) — LLM development standards: LangChain framework, provider configuration, LLM observability, and unit test mocking
|
|
206
|
+
- [agentme-edr-041](041-ai-agents-development-standards.md) — Agent development standards: deepagents framework, tool-invocation loops, and agent patterns
|
|
207
207
|
- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Adapter/application layer separation that defines the project layout
|
|
208
208
|
- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
|
|
209
|
-
- [agentme-edr-
|
|
210
|
-
- [agentme-edr-
|
|
211
|
-
- [agentme-edr-
|
|
209
|
+
- [agentme-edr-050](../data/050-ml-dataset-structure.md) — ML dataset structure for eval datasets
|
|
210
|
+
- [agentme-edr-051](051-ai-eval-core-standards.md) — AI eval core standards: eval folder structure (rule `01`) and LLM-as-judge binary scoring contract for all tiers (rule `02`)
|
|
211
|
+
- [agentme-edr-053](053-ai-eval-script.md) — AI eval script: entry-first loop, `--type` filtering, `mock_fixtures`, and MLflow conventions
|
|
212
|
+
- [agentme-edr-054](054-ai-eval-report-format.md) — AI eval report format: `report-<type>.md` template, Wilson CI, and convergence analysis
|
|
213
|
+
- [agentme-edr-055](055-ai-eval-repeatability.md) — AI eval repeatability: REPEAT_COUNT loop, scoring methods, and release cadence
|
|
214
|
+
- [agentme-edr-007](../governance/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: agentme-edr-policy-
|
|
3
|
-
description: Defines the naming vocabulary for LangGraph workflow elements: node suffixes/prefixes, state type names, state attribute grouping, workflow class/variable names, judge node output schema, route function names, and cross-element coherence rules. Use when naming any part of a LangGraph workflow — nodes, states, routes, or the workflow itself. For workflow structure and toolchain see agentme-edr-
|
|
2
|
+
name: agentme-edr-policy-044-ai-workflow-naming-conventions
|
|
3
|
+
description: Defines the naming vocabulary for LangGraph workflow elements: node suffixes/prefixes, state type names, state attribute grouping, workflow class/variable names, judge node output schema, route function names, and cross-element coherence rules. Use when naming any part of a LangGraph workflow — nodes, states, routes, or the workflow itself. For workflow structure and toolchain see agentme-edr-043.
|
|
4
4
|
apply-to: AI workflow projects using LangGraph StateGraph built with Python
|
|
5
5
|
valid-from: 2026-06-21
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
# agentme-edr-policy-
|
|
8
|
+
# agentme-edr-policy-044: AI workflow naming conventions
|
|
9
9
|
|
|
10
10
|
## Context and Problem Statement
|
|
11
11
|
|
|
@@ -25,10 +25,10 @@ LangGraph node names MUST follow a suffix convention that communicates the node'
|
|
|
25
25
|
|
|
26
26
|
| Convention | Node type | When to use |
|
|
27
27
|
|---|---|---|
|
|
28
|
-
| suffix `_llm` | LLM call | Any node whose primary action is a direct LLM inference call (see [agentme-edr-
|
|
28
|
+
| suffix `_llm` | LLM call | Any node whose primary action is a direct LLM inference call (see [agentme-edr-040](040-ai-llm-development-standards.md)) |
|
|
29
29
|
| suffix `_step` | Algorithmic step | Deterministic logic with no LLM involvement (transformation, validation, routing) |
|
|
30
30
|
| suffix `_tool` | Tool/API call | A node that wraps a single external tool or API (e.g. a REST endpoint, DB query) |
|
|
31
|
-
| suffix `_agent` | Subgraph agent | A node that invokes a nested subgraph containing its own tool-invocation cycle and LLM calls; use the **deepagents** library for these nodes (see [agentme-edr-
|
|
31
|
+
| suffix `_agent` | Subgraph agent | A node that invokes a nested subgraph containing its own tool-invocation cycle and LLM calls; use the **deepagents** library for these nodes (see [agentme-edr-041](041-ai-agents-development-standards.md)) |
|
|
32
32
|
| prefix `evaluate_` | Judge node | A node that evaluates the quality, correctness, completeness, or progress of prior outputs and returns a structured verdict; MUST follow rule `03-judge-node-output-format` |
|
|
33
33
|
|
|
34
34
|
The Python function implementing the node SHOULD share the same name as the node alias passed to `add_node`, so that graph definitions and stack traces remain unambiguous:
|
|
@@ -193,7 +193,7 @@ def route_after_evaluate_quality(state) -> str:
|
|
|
193
193
|
return "publish_step"
|
|
194
194
|
```
|
|
195
195
|
|
|
196
|
-
**Logging:** Log `verdict` and the count of each level as MLflow metrics on the current run per [agentme-edr-
|
|
196
|
+
**Logging:** Log `verdict` and the count of each level as MLflow metrics on the current run per [agentme-edr-043](043-ai-workflow-development-standards.md) rule `03-observability-and-experiment-tracking`.
|
|
197
197
|
|
|
198
198
|
#### 04-workflow-naming-conventions
|
|
199
199
|
|
|
@@ -276,6 +276,6 @@ def after_quality_check(state): ... # FORBIDDEN: not named "route_after_<node>"
|
|
|
276
276
|
|
|
277
277
|
## References
|
|
278
278
|
|
|
279
|
-
- [agentme-edr-
|
|
280
|
-
- [agentme-edr-
|
|
281
|
-
- [agentme-edr-
|
|
279
|
+
- [agentme-edr-043](043-ai-workflow-development-standards.md) — Workflow structure, LangGraph toolchain, observability, and testing patterns
|
|
280
|
+
- [agentme-edr-040](040-ai-llm-development-standards.md) — LLM development standards (drives `_llm` node suffix and mocking patterns)
|
|
281
|
+
- [agentme-edr-041](041-ai-agents-development-standards.md) — Agent development standards (drives `_agent` node suffix and state conventions)
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: agentme-edr-policy-
|
|
2
|
+
name: agentme-edr-policy-045-ai-agent-xdrs-knowledge-layer
|
|
3
3
|
description: Defines how to integrate XDRS as the runtime knowledge source of truth for AI agents — covering document placement, AGENTS.md setup, file tools, and local sandbox configuration. Apply only when the project explicitly uses XDRS to govern agent behavior.
|
|
4
4
|
apply-to: AI agent projects that use XDRS as the source of truth for policies and skills
|
|
5
5
|
valid-from: 2026-05-27
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
# agentme-edr-policy-
|
|
8
|
+
# agentme-edr-policy-045: AI agent XDRS knowledge layer
|
|
9
9
|
|
|
10
10
|
## Context and Problem Statement
|
|
11
11
|
|
|
@@ -17,7 +17,7 @@ How should an AI agent project integrate XDRS as its runtime source of truth for
|
|
|
17
17
|
|
|
18
18
|
**Embed XDRS documents in `lib/data/.xdrs/`, instruct the agent to consult them via `AGENTS.md`, equip the agent with sandboxed file tools, and use the deepagents framework when a local sandbox is required.**
|
|
19
19
|
|
|
20
|
-
This policy MUST only be applied when the project explicitly chooses XDRS as its knowledge governance layer. It is not required by [agentme-edr-
|
|
20
|
+
This policy MUST only be applied when the project explicitly chooses XDRS as its knowledge governance layer. It is not required by [agentme-edr-041](041-ai-agents-development-standards.md) or [agentme-edr-043](043-ai-workflow-development-standards.md) in general.
|
|
21
21
|
|
|
22
22
|
### Details
|
|
23
23
|
|
|
@@ -59,7 +59,7 @@ Read /AGENTS.md and follow all instructions in it before proceeding.
|
|
|
59
59
|
|
|
60
60
|
#### 02-agent-file-tools
|
|
61
61
|
|
|
62
|
-
Every agent that uses the XDRS knowledge layer MUST use the file tools provided by the deepagents framework. Do not implement hand-rolled alternatives — see [agentme-edr-
|
|
62
|
+
Every agent that uses the XDRS knowledge layer MUST use the file tools provided by the deepagents framework. Do not implement hand-rolled alternatives — see [agentme-edr-041 rule 02-local-sandbox](041-ai-agents-development-standards.md) for the full sandbox and tool requirements.
|
|
63
63
|
|
|
64
64
|
These tools operate over two sandboxed roots (configured in rule `03-local-sandbox`):
|
|
65
65
|
|
|
@@ -72,7 +72,7 @@ These tools operate over two sandboxed roots (configured in rule `03-local-sandb
|
|
|
72
72
|
|
|
73
73
|
#### 03-local-sandbox
|
|
74
74
|
|
|
75
|
-
Follow [agentme-edr-
|
|
75
|
+
Follow [agentme-edr-041 rule 02-local-sandbox](041-ai-agents-development-standards.md) for the general deepagents sandbox setup. When XDRS is in use, add the following mounts to the sandbox configuration:
|
|
76
76
|
|
|
77
77
|
| Source | Content | Deepagents sandbox path |
|
|
78
78
|
|---|---|---|
|
|
@@ -91,8 +91,8 @@ data_root = str(files("myagent").joinpath("data"))
|
|
|
91
91
|
agents_md = Path(temp_root) / "AGENTS.md"
|
|
92
92
|
agents_md.write_text(_AGENTS_MD) # content from xdrs-core AGENTS.md template; see rule 01-xdrs-knowledge-layer
|
|
93
93
|
|
|
94
|
-
# Add these mounts alongside the base mounts from agentme-edr-
|
|
95
|
-
# (mount_paths uses {src: dst} dict format per agentme-edr-
|
|
94
|
+
# Add these mounts alongside the base mounts from agentme-edr-041 rule 02-local-sandbox:
|
|
95
|
+
# (mount_paths uses {src: dst} dict format per agentme-edr-041)
|
|
96
96
|
sandbox = Sandbox(
|
|
97
97
|
mount_paths={
|
|
98
98
|
tmp_dir: "/workspace",
|