AGENTS.md

1# AGENTS.md
2 
3Conventions for the `@n8n/agents` package.
4 
5## Code Style
6 
7- **No `_` prefix on private properties** — use `private` access modifier
8  without underscore. Write `private name: string`, not `private _name: string`.
9- **Builder pattern with lazy build** — all public primitives use a fluent
10  builder API. **User code never calls `.build()`**. Builders are passed
11  directly to the consuming method (e.g. `agent.tool(myTool)`) which calls
12  `.build()` internally. Agent has `generate()`/`stream()` directly on the
13  class, which lazy-build via `ensureBuilt()` on first call. `build()` is
14  `protected` on Agent to keep it out of the public API.
15- **Zod for schemas** — all input/output schemas use Zod.
16 
17## Package Structure
18 
19```
20src/
21  index.ts              # Public API barrel export
22  types/                # Public TypeScript types
23    index.ts            # Re-exports consumable types
24    telemetry.ts
25    sdk/                # Types aligned with builders (agent, eval, guardrail, mcp, memory, message, provider, tool)
26    runtime/            # Serializable runtime shapes (events, message lists)
27    utils/              # JSON typing helpers re-exported with public types
28  sdk/                  # Fluent builders and SDK entry points
29    agent.ts            # Agent builder
30    catalog.ts          # Provider catalog fetch
31    eval.ts             # Evaluation primitives
32    evaluate.ts         # Evaluation runner over agents + dataset
33    guardrail.ts        # Guardrail builder
34    mcp-client.ts       # MCP client integration
35    memory.ts           # Memory builder
36    message.ts          # LLM/DB message helpers
37    provider-tools.ts   # Provider-defined tool factories
38    telemetry.ts        # Telemetry builder (OTel, redaction)
39    tool.ts             # Tool builder
40    verify.ts           # Verification utilities
41  runtime/              # Internal — never exported
42    agent-runtime.ts    # Core agent execution engine (AI SDK)
43    tool-adapter.ts     # Tool execution, branded suspend detection
44    stream.ts           # Streaming helpers
45    model-factory.ts    # Model instantiation
46    memory-store.ts     # In-memory conversation and observation-log storage
47    observation-log-observer.ts
48    observation-log-reflector.ts
49    observation-log-renderer.ts
50    scoped-memory-task-runner.ts
51    message-list.ts     # Message list + serialization for agent loop
52    messages.ts         # Message normalization
53    mcp-connection.ts   # MCP connection lifecycle
54    mcp-tool-resolver.ts
55    run-state.ts        # Run / checkpoint state
56    event-bus.ts        # Internal agent events
57    runtime-helpers.ts
58    title-generation.ts
59    strip-orphaned-tool-messages.ts
60    logger.ts
61  storage/              # Shared memory backend base class (exported)
62    base-memory.ts
63  workspace/            # Workspace, sandbox, filesystem, built-in tools (exported)
64  integrations/         # Optional integrations (exported where applicable)
65    langsmith.ts        # LangSmith telemetry adapter (peer `langsmith`)
66  utils/                # Internal helpers (e.g. Zod utilities); not barrel-exported
67examples/
68  basic-agent.ts        # Sample snippet; included in format/lint paths
69docs/
70  agent-runtime-architecture.md  # In-package runtime notes
71```
72 
73The **`index.ts`** surface also exports `Workspace` / sandbox / filesystem types,
74`InMemoryMemory`, `LangSmithTelemetry`, and `evals` alongside the core SDK builders.
75 
76Optional **peer dependencies** (telemetry): `langsmith`, `@opentelemetry/sdk-trace-node`,
77`@opentelemetry/sdk-trace-base`, `@opentelemetry/exporter-trace-otlp-http` — all
78optional; install only when wiring that telemetry.
79 
80## Credential Pattern
81 
82Agents declare credential requirements via `.credential('name')`. The execution
83engine resolves the name to an API key and injects it into the model config.
84User code never touches raw API keys.
85 
86```typescript
87const agent = new Agent('assistant')
88  .model('anthropic/claude-sonnet-4-5')
89  .credential('anthropic')
90  .instructions('You are helpful.');
91```
92 
93## Engine Injection (EngineAgent)
94 
95The execution engine extends `Agent` and overrides `protected build()` to
96inject infrastructure (checkpoint storage, credentials) before calling
97`super.build()`. This is the pattern for all engine-level concerns:
98 
99```typescript
100class EngineAgent extends Agent {
101  build() {
102    this.checkpoint(store);
103    const cred = this.declaredCredential;
104    if (cred) this.resolvedApiKey = resolve(cred);
105    return super.build();
106  }
107}
108```
109 
110 
111## Testing
112 
113- Unit tests live in `src/__tests__/`, integration tests in `src/__tests__/integration/`
114- Unit tests use Vitest (`pnpm test`)
115- Integration tests use Vitest (`pnpm test:integration`) with real LLM calls
116  - A `.env` file at the package root is loaded automatically by the vitest config.
117    Always assume it exists when running integration tests. Never commit it.
118  - Required keys:
119    - `ANTHROPIC_API_KEY` — all integration tests
120  - Tests skip automatically when the required API key is not set
121- Run from the package directory: `cd packages/@n8n/agents && pnpm test`
122 
123### Integration tests
124 
125Integration tests make real LLM calls. CI replays recorded HTTP cassettes
126instead, so every test must have a matching recording.
127 
128**Workflow after changing or adding integration tests:**
129 
1301. `pnpm test:integration <file>` — verify the test passes with a live API key
1312. `pnpm test:integration:record <file>` — record HTTP cassettes
1323. `pnpm test:integration:replay` — confirm the test passes from recordings
133 
134**Rules:**
135- No random IDs or current timestamps in HTTP requests — the replay matcher
136  must be able to match recorded requests deterministically
137- Run only the affected test files, not the full suite, unless changes affect all tests
138 
139## Documentation
140 
141- Spec-driven work in the wider repo may use `.agents/specs/` (see repo skill
142  `.agents/skills/spec-driven-development`).
143 
144## Building
145 
146```bash
147cd packages/@n8n/agents
148pnpm build       # rimraf dist && tsc -p tsconfig.build.json → dist/
149pnpm typecheck   # tsc --noEmit
150pnpm test        # vitest (unit)
151```
152 
153## PR naming convention
154 
155The Agents feature is not generally available yet, so any PRs related to the Agents package should have (no-changelog) in the title to avoid generating a changelog entry.
156