Customize agent components

Try a changed prompt or agent loop without changing ptc.json. If you keep the change, give your permanent components new IDs.

A prelude is the compiled set of components used by one workflow or mission. It is immutable during a run. You do not replace the whole prelude. You replace one selected component when the next run starts.

Try a different agent prompt

Selecting agent.core also selects agent.prompt. The prompt is therefore an override target even when it is not listed directly in the manifest.

Candidate creation requires a source checkout. Copy the shipped prompt, then edit the copy:

mkdir -p private
cp priv/preludes/kernel/agent.prompt.clj private/agent.prompt.clj

Turn the edited source into a checked candidate:

mix ptc.materialize ptc.json \
  --workflow \
  --component agent.prompt \
  --out private/agent-prompt-candidate \
  --source private/agent.prompt.clj

The command checks the source and creates the candidate and descriptor files. The output directory must not already exist.

Validate the candidate without acquiring a provider:

mix ptc validate ptc.json \
  --component-override-descriptor private/agent-prompt-candidate/descriptor.json

Run the normal version first. Then run the candidate:

mix ptc run ptc.json
mix ptc run ptc.json \
  --component-override-descriptor private/agent-prompt-candidate/descriptor.json

The override applies only to that command. It does not edit the manifest or install the candidate. Use replay when you need a fair comparison with the same model responses.

Keep a change

Use new component IDs for permanent application code. A local component cannot reuse a shipped library ID. If you replace a prompt or policy permanently, select a loop whose dependencies point to your new components.

The components-and-preludes reference defines dependencies, mission targets, descriptor fields, hashes, effect widening, failure messages, and security boundaries. The agent library reference documents the shipped agent components and their options.