Agent Recipe

An Agent Recipe turns a scheduled, capability-using agent into a single declarative artifact you can deploy in one step. Instead of hand-wiring a script, a password "somewhere", a cron entry and a system prompt, you point troop at a pinned repo and it provisions everything.

Agent Recipe is a troop feature and a repo convention — not a protocol. There is nothing in the DDISA spec about it.

The shape of a recipe

A recipe repo has two parts:

• ape-agent.yaml — the manifest (all the declarative data).
• tools/ — the code part: the actual scripts the agent runs.
• README.md — for humans.

my-recipe/
├── ape-agent.yaml
├── tools/
│   └── summarize.mjs
└── README.md

ape-agent.yaml

name: bluesky-summary           # kebab-case; becomes the agent slug
kind: agent                     # v1: only `agent`
intent: |                       # the prepared system prompt
  You summarise the Bluesky feed about {{topic}} twice a day.
  Be concise. Use the tools in tools/ via your bash tool.
capabilities:                   # declared placeholder env names only
  - env: BLUESKY_HANDLE
  - env: BLUESKY_APP_PASSWORD
    prefer: local               # optional hint: proxy | local
params:                         # typed, validated at deploy time
  - name: topic
    type: string                # string | number | boolean
    required: true
schedules:                      # one agent run per tick
  - cron: "0 8 * * *"
    description: morning digest for {{topic}}
  - cron: "0 18 * * *"
user_addendum: true             # allow a free runtime behaviour layer
tools:                          # entrypoints under tools/
  - tools/summarize.mjs

Sourcing & trust

Deploy with a pinned ref — a version tag (v1.0.0) or a commit SHA. A floating ref (@main, a branch) is rejected before any fetch. Integrity comes from the pin.

apes agent deploy github.com/openape-ai/bluesky-summary@v0.1.0 \
  --param topic="AI agents"

The curated recipe index (e.g. github.com/openape-ai/bluesky-summary) is only a discovery convenience. It carries no special trust — capabilities are always consented explicitly, once, regardless of where the recipe comes from. A curated recipe and your own repo are technically identical.

Capabilities & secrets — the agent never sees them as a stranger

A recipe only declares placeholder env names. troop is the broker and owns the whole lifecycle:

1. At deploy you supply the values (prompted, or --secret ENV=val).
2. troop seals each value to the agent's X25519 public key the moment you submit it and stores only the sealed blob. troop's DB, logs and the control-plane WS only ever see ciphertext.
3. The blob is relayed blind through the nest to the agent host.
4. The agent — the only place plaintext exists — opens it with its private key and puts it in its own environment.

Revoke clears the agent's copy on the next connect. Rotate takes effect live, no re-deploy.

This follows the published principle "the infrastructure carries the knowledge, the agent operates blind" — Was der Agent nicht weiß. The proxy-injection path (where the agent never even decrypts) is the North-Star; see the proxy-secrets runbook.

Params vs. user_addendum

• params are typed and validated at deploy time, then interpolated into the intent/schedules/tools. They are fixed for the life of the deploy.
• user_addendum is free text the owner can edit any time in troop. It is appended to the intent on every run — no re-deploy. Use it for "focus on the negative posts" style tweaks.

Deploying

CLI and troop UI are equivalent. The CLI:

# pinned ref is mandatory
apes agent deploy github.com/<owner>/<name>@v1.2.0 \
  --param topic="AI agents" \
  --secret BLUESKY_HANDLE=me.bsky.social \
  --secret BLUESKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

# omit --secret to be prompted interactively
# add --json for non-interactive / scripted use

What happens: troop fetches and validates the manifest, validates your params, spawns the agent, sets its system prompt to the interpolated intent, creates the schedules, and binds the sealed secrets. Within seconds the agent is running on its schedule.

Next Steps

• Capabilities & Grants — the consent model
• escapes — the privilege boundary the relay uses
• Quick Start: Agent — your first agent