75 lines
2.9 KiB
Markdown
75 lines
2.9 KiB
Markdown
# Neutral Agent Card — Spec v1.0 (DRAFT)
|
|
|
|
The portable definition of a specialist. Runtime-agnostic: any agent runtime
|
|
(opencode here, a standalone server, an Odoo-side runner) can interpret a card.
|
|
This is the "Docker model": the format is neutral, the runtime ships or is
|
|
preinstalled per target.
|
|
|
|
## File
|
|
|
|
One JSON file per agent in `agents/`.
|
|
|
|
## Schema
|
|
|
|
```json
|
|
{
|
|
"schema_version": "1.0",
|
|
"agent_id": "o1-sellers-recruiter",
|
|
"name": "Seller Recruiter",
|
|
"role": "specialist",
|
|
"description": "Finds and recruits consignment sellers for O1 on OLX and local forums",
|
|
"model_hint": "free-tier",
|
|
"persona": "Practical Bulgarian business developer; direct, trustworthy; works in BG+EN",
|
|
"prompt_files": ["prompts/sellers-recruiter.md"],
|
|
"tools": ["odoo.search_records", "odoo.create_record", "file.read", "script.run"],
|
|
"memory": {
|
|
"engine": "brain",
|
|
"script": "brain/brain.py",
|
|
"namespace": "o1-sellers"
|
|
},
|
|
"gates": ["hours"],
|
|
"verification": {
|
|
"definition_of_done": "Confirmed N sellers recruited with signed consignment agreements this cycle",
|
|
"check": "odoo.search_records('o1.seller', [['status','=','signed']]).count >= N"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Field rules
|
|
|
|
1. **`model_hint`** is a *class* (`free-tier` / `balanced` / `max`), never a
|
|
concrete vendor model ID. Each runtime maps hints to its own models
|
|
(here: `free-tier` → `opencode/mimo-v2.5-free`).
|
|
2. **`tools`** are declared by *name* against a shared tool registry — no
|
|
inline code in cards. The runtime resolves names to implementations.
|
|
3. **`prompt_files`** keep prompts external (markdown) — cards stay data.
|
|
4. **`memory`** points to a brain script + namespace; the card never carries
|
|
memory content.
|
|
5. **`verification`** is mandatory — a machine-checkable definition of done.
|
|
A card without one is rejected by the validator. ("I processed X" is never
|
|
done; "I confirmed X exists/counts" is done.)
|
|
6. **`gates`** are named constraints (working hours, irreversible-action gate)
|
|
resolved by the runtime.
|
|
7. No runtime-specific syntax, no absolute paths, no secrets.
|
|
|
|
## Mapping: neutral card ↔ opencode agent
|
|
|
|
The converter is a small script; both directions must round-trip losslessly
|
|
(convert → back → identical hash).
|
|
|
|
| Neutral card field | opencode agent (`agent/*.md` frontmatter / body) |
|
|
|---|---|
|
|
| `description` | frontmatter `description` |
|
|
| `model_hint` | frontmatter `model` (resolved via model map) |
|
|
| `tools` | frontmatter tool booleans (`write: true`, `bash: true`, ...) |
|
|
| `prompt_files` | body / loaded instructions |
|
|
| `memory` | brain.py reference in body |
|
|
| `verification` | "Completion Verification" section in body |
|
|
| `gates` | body constraints section |
|
|
|
|
## Validator
|
|
|
|
`validate-depo.sh` rejects a package when: any card is missing a field,
|
|
`verification` is absent, `prompt_files` referenced but missing, tools named
|
|
but unregistered in the tool registry, or secrets detected.
|