129 lines
4.5 KiB
Markdown
129 lines
4.5 KiB
Markdown
# Agent Authoring Guide
|
|
|
|
This guide describes how to add or evolve agents after the runtime redesign.
|
|
|
|
## Acceptance Checklist (Task Gate)
|
|
|
|
Before shipping agent doc or definition changes, confirm all points are documented in the PR notes:
|
|
|
|
- Runtime definition location and ownership.
|
|
- How markdown prompt segments affect prompts through compile-time extraction.
|
|
- What a new agent must define in TypeScript.
|
|
- Expected structured output shape (`artifactType`, `sections`, `metadata`, `qualityChecks`, `previewText`, `body`).
|
|
- Tests added for definitions, prompt compilation, prompting, and contracts.
|
|
|
|
## Dual Model: Source of Truth Rules
|
|
|
|
The agent runtime uses two complementary sources of truth:
|
|
|
|
1. Structural/runtime contract in TypeScript.
|
|
- `lib/agent-definitions.ts`: registry (`AGENT_DEFINITIONS`), metadata, rules, blueprints, docs path.
|
|
- `lib/agent-run-contract.ts`: normalization and safety for plans, clarifications, and structured outputs.
|
|
- `lib/agent-templates.ts`: UI projection derived from definitions.
|
|
2. Curated prompt influence in markdown.
|
|
- `components/agents/<agent-id>.md` contains authored narrative plus marked prompt segments.
|
|
- `scripts/compile-agent-docs.ts` extracts only marked blocks.
|
|
- `lib/generated/agent-doc-segments.ts` is generated and consumed at runtime.
|
|
|
|
No free-form markdown parsing happens in `convex/agents.ts`.
|
|
|
|
## Add a New Agent
|
|
|
|
1. Add a definition in `lib/agent-definitions.ts`.
|
|
- Add a new `AgentDefinitionId` union member.
|
|
- Add a new item in `AGENT_DEFINITIONS` with metadata, rules, accepted source types, and `defaultOutputBlueprints`.
|
|
- Set `docs.markdownPath` to the companion markdown file.
|
|
2. Add companion markdown in `components/agents/<agent-id>.md`.
|
|
3. Compile prompt segments into `lib/generated/agent-doc-segments.ts`.
|
|
4. Add i18n entries for template and output labels in `messages/de.json` and `messages/en.json` when needed.
|
|
5. Add or update tests (see test matrix below).
|
|
|
|
## Marker Rules (Required)
|
|
|
|
Every agent markdown file must include exactly one start marker and one end marker for each required key:
|
|
|
|
- `role`
|
|
- `style-rules`
|
|
- `decision-framework`
|
|
- `channel-notes`
|
|
|
|
Marker format:
|
|
|
|
```md
|
|
<!-- AGENT_PROMPT_SEGMENT:role:start -->
|
|
Your segment text.
|
|
<!-- AGENT_PROMPT_SEGMENT:role:end -->
|
|
```
|
|
|
|
Constraints:
|
|
|
|
- Marker names must match exactly.
|
|
- Missing, duplicate, or empty segments fail compilation.
|
|
- Segment order in output is deterministic and follows `AGENT_PROMPT_SEGMENT_KEYS`.
|
|
- Unmarked prose is ignored by the runtime prompt payload.
|
|
|
|
## Compile Flow
|
|
|
|
Run the compiler after changing any `components/agents/*.md` marker content or any `docs.markdownPath` entry:
|
|
|
|
```bash
|
|
npx tsx scripts/compile-agent-docs.ts
|
|
```
|
|
|
|
Then verify generated output changed as expected:
|
|
|
|
- `lib/generated/agent-doc-segments.ts`
|
|
|
|
## Structured Output Expectations
|
|
|
|
Execution payloads are normalized via `normalizeAgentStructuredOutput(...)` in `lib/agent-run-contract.ts`.
|
|
|
|
The runtime expects:
|
|
|
|
- `title`
|
|
- `channel`
|
|
- `artifactType`
|
|
- `previewText`
|
|
- `sections[]` (`id`, `label`, `content`)
|
|
- `metadata` (`Record<string, string | string[]>`)
|
|
- `qualityChecks[]`
|
|
|
|
Compatibility behavior:
|
|
|
|
- `body` stays as a legacy fallback string for old render paths.
|
|
- Missing/invalid entries are normalized defensively.
|
|
|
|
## Test Matrix for Agent Changes
|
|
|
|
For a new agent or blueprint change, add or update tests in these areas:
|
|
|
|
- Definition registry and projection
|
|
- `tests/lib/agent-definitions.test.ts`
|
|
- `tests/lib/agent-templates.test.ts`
|
|
- Markdown marker extraction and generated segment coverage
|
|
- `tests/lib/agent-doc-segments.test.ts`
|
|
- Prompt assembly behavior
|
|
- `tests/lib/agent-prompting.test.ts`
|
|
- Runtime contracts (execution plan + structured output normalization)
|
|
- `tests/lib/agent-run-contract.test.ts`
|
|
- `tests/lib/agent-structured-output.test.ts`
|
|
- Convex orchestration behavior when contract semantics change
|
|
- `tests/convex/agent-orchestration-contract.test.ts`
|
|
|
|
## When `convex/agents.ts` Stays Unchanged
|
|
|
|
Do not modify `convex/agents.ts` when you only:
|
|
|
|
- add a new definition entry in `lib/agent-definitions.ts`
|
|
- add/update markdown prompt segments and recompile
|
|
- add or adjust output blueprints using existing contract fields
|
|
- tune analysis/execution rules in definitions
|
|
- update UI copy or i18n labels
|
|
|
|
Modify `convex/agents.ts` only when orchestration semantics change, for example:
|
|
|
|
- new runtime stage/state transitions
|
|
- credit/scheduler behavior changes
|
|
- schema shape changes for analyze or execute payloads
|
|
- persistence shape changes beyond current normalized contracts
|