Profiles, kinds, and modes
When designing an agent run, read this because profiles, kinds, modes, and document owners solve different problems and prevent a long prompt from becoming an unstable substitute for an application identity.
Shape a run by choosing the dial that owns the decision. The four dials are independent: a useful profile does not imply an orchestrator, and a specialist kind does not decide where its knowledge lives.
| Dial | It answers | Use it when |
|---|---|---|
| Profile | Which application identity, project purview, environment, and profile documents apply? | An application or body of work has stable directories and conventions |
| Kind | What standing role, model tier, tools, and expertise should the agent have? | The work matches a recurring role such as developer or reviewer |
| Mode | Does this node work hands-on or coordinate independent children? | Parallel work makes coordination the main job |
| Document owner | Who should receive a document? | Guidance must reach one node, repo, profile, user, or all crouter users |
A profile is not a label on a run. It is a stable agent identity with its own documents and a purview of project directories. It lets an application create nodes from the same target context even if the caller runs elsewhere. Create a profile when an app has a durable set of directories, environment values, and conventions worth sharing. Do not make a profile for every repository or individual request. Use client.profiles and the SDK’s profile create field to select the application’s identity.
A kind is a recurring role, not a decorative name. It carries a role-specific posture and may choose a suitable model tier and tools. A custom kind beats a long prompt when the role recurs and needs standing discipline that should survive every run: for example, an application’s compliance reviewer that always needs the same tools, expertise, and model choice. A one-off instruction belongs in the node’s prompt, where it does not create a permanent persona to maintain.
Base mode is the normal choice: the node owns and performs the work, using a child only for a separable part. Promote to orchestrator only when independent parts can proceed in parallel and the benefits outweigh coordination and integration. A terminal orchestrator still finishes normally; residency is separate and belongs to a person-facing ongoing conversation.
These choices keep the application prompt focused. Identity belongs in a profile, standing role in a kind, task-specific intent in the prompt, coordination in mode, and reusable knowledge in the narrowest document owner. For the full selection rules, run crtr canvas read internal/agent-shaping; nodes.create documents the profile, kind, and mode fields an application passes.
Documents
When shaping an agent without rewriting its prompt, read this because documents separate facts to consult from behavior to embody and let each owner control who receives them.
Scopes and trust
When giving an application or node less authority, read this because a scope list is an allow-list enforced by the daemon and a bearer token can set the maximum authority for every run it creates.