Skip to main content

Create an Agent Profile

Go to Agent Profiles → New Profile.

1. Identity​

  • Profile Key — a short, unique identifier (e.g. backend-developer). It's unique across the whole platform and can't be changed once other things reference it.
  • Name / Description.

2. Reasoning & Guardrails​

  • Role / Objective — tell the agent who it is and what outcome it owns.
  • Instructions, Guardrails, Constraints, Responsibilities — one item per line. These fields guide the model; they do not replace enforced permissions or approval gates.
  • Required Outputs / Output Contract — JSON describing the evidence and structured output expected from the run.

3. Runtime​

  • Provider — which CLI runs the agent (Claude Code, or another registered runtime provider).
  • Model, Max Turns, Timeout — tune per role; a quick reviewer profile needs far fewer turns than a full implementation profile.
  • Permission Mode — shown for providers that support Claude-style permission modes.
  • Memory Provider / Memory Connection Key — only if this role should have long-term memory. The connection key must match a binding you created in Connect a Git Repository.
  • Needs Repository — whether this profile requires a checked-out repo at all (a pure planning/reporting profile might not).

4. Permissions​

Two independent layers, both configurable here:

  • Allow / Deny — Claude's own native permission rules, one pattern per line (Read({workspace}/**), Bash(git push *), ...). Deny always wins over allow.
  • Permission Presets — reusable, versioned policies from the registry (e.g. repository-write@1) that get merged in alongside your inline rules.

5. Loop, validation, and recovery​

Configure maximum iterations, contract validation, artifact repair, result-contract repair, provider retry, required artifacts, and stop conditions. The supported stop conditions are:

  • resultContractValid
  • requiredArtifactsUploaded
  • gitPushedIfRequired

If resultContractValid is selected, contract validation must be enabled. Recovery options control how the loop tries to repair a failed condition; they do not define additional stop conditions.

6. Action Gates (optional)​

A JSON list of tool-call patterns that must pause for human approval, e.g.:

[
  { "match": "Bash(git push *)", "approver_role": "TECH_LEAD", "timeout_minutes": 240, "on_timeout": "deny" }
]
caution

Never combine a non-empty Action Gates list with Permission Mode "Bypass Permissions" — the console will block saving, because gates delivered through the permission-prompt path never fire when permissions are bypassed entirely.

7. Resources​

Attach registry resources this role needs: Skills, Hooks, Plugins, MCP Servers, Prompts, and Knowledge. Select a published version and mark each dependency required or optional. A required dependency blocks dispatch when missing or incompatible; an optional dependency is skipped.

8. Secrets, artifacts, and cost​

  • Secret Refs map an environment-facing name to a project-scoped secret path. The RunSpec carries references, never plaintext secret values.
  • Artifact Logical Roles use glob=role lines, for example out/result-contract.json=result-contract, to classify uploaded artifacts.
  • Cost Limit sets the run's USD ceiling when provider usage data is available.

9. Save & Publish​

The right-hand panel shows a live preview of the generated configuration as you fill the form — use it to sanity-check before saving. Click Save, then Publish to make this version live.

Common errors​

MessageWhat it means
"... is not canonical; ... must use snake_case"Only shows up if you're editing raw content directly rather than the form — switch back to the form fields, which always produce valid names.
"Required registry resource version was not found: X@N"A required Skill/Hook/Plugin/MCP binding references a version that doesn't exist in this org. Check the resource's published versions in Registry and re-select it.
"No agent profile configured for task 'X'" (at run time)The workflow task this profile is supposed to run on has no assignment — see Create and Deploy a Workflow.

Next​

A profile alone doesn't run anything — it has to be assigned to a task inside a workflow. Continue to Create and Deploy a Workflow.