Agent Profile YAML Schema

The canonical, currently-enforced shape. Every field name below is exact — camelCase variants of any of these are rejected at publish time.

key: string                    # must match the profile's profileKey
version: integer
name: string
description: string            # optional
role: string                   # prompt guidance
objective: string              # prompt guidance
instructions: [string]         # prompt guidance
constraints: [string]          # prompt guidance
guardrails: [string]           # prompt guidance, not an enforced permission boundary
responsibilities: [string]     # prompt guidance
required_outputs: object       # expected evidence/output declaration
output_contract: object        # structured output contract

runtime:
  provider_key: string         # required — a Runtime Provider's providerKey, e.g. "claude-code"
  command: string               # optional override of the provider's default command
  model: string                 # optional
  max_turns: integer
  timeout_seconds: integer
  permission_mode: string        # e.g. "acceptEdits" — never combine with non-empty action_gates when set to "bypassPermissions"
  memory_provider: string        # optional, e.g. "cognee"
  memory_connection_key: string  # required if memory_provider is set — must exist as a ProjectConnection alias on the dispatching project
  trust_workspace: boolean       # optional
  adapter_config:                 # provider-native settings, opaque to the platform
    settings:
      permissions:
        allow: [string]
        deny: [string]
  loop:
    enabled: boolean
    max_iterations: integer
    contract_validation: boolean
    repair_missing_artifacts: boolean
    repair_result_contract: boolean
    require_git_push: boolean
    retry_provider_failures: boolean
    required_artifacts: [string]
    stop_when: [string]          # only from: resultContractValid, requiredArtifactsUploaded, gitPushedIfRequired
                                   # if it includes resultContractValid, loop.contract_validation must not be false

workspace:
  needs_repository: boolean

permission_presets: ["key@version", ...]   # each must match [a-z0-9][a-z0-9._-]*@[1-9][0-9]*

action_gates:
  - match: string                # a permission-rule pattern, e.g. "Bash(git push *)"
    approver_role: string
    timeout_minutes: integer
    on_timeout: "deny" | "allow"

resources:
  skills:      [{ ref: "key@version", required: boolean }]
  hooks:       [{ ref: "key@version", required: boolean }]
  plugins:     [{ ref: "key@version", connection_alias: string, required: boolean }]
  mcp_servers: [{ ref: "key@version", required: boolean }]
  prompts:     [{ ref: "key@version", required: boolean }]
  knowledge:   [{ ref: "key@version", required: boolean }]

secrets:
  - name: string
    ref: string                 # project-scoped secret path; plaintext is resolved only by the worker

cost_limit_usd: number

artifact_policy:
  logical_roles:
    "<glob pattern>": "<logical role name>"

Rejected / non-canonical keys

Publishing fails outright (400) if any of these appear:

Rejected	Use instead
top-level settings:	runtime.adapter_config.settings
top-level actionGates	action_gates
top-level costLimitUsd	cost_limit_usd
top-level artifactPolicy	artifact_policy
top-level permissionPreset(s)	permission_presets
runtime.providerKey / runtime.provider / runtime.adapterKey	runtime.provider_key (adapter key belongs to the Runtime Provider catalog, not here)
runtime.maxTurns, timeoutSeconds, permissionMode, memoryProvider, memoryConnectionKey, adapterConfig	snake_case equivalents
runtime.loop.maxIterations, contractValidation, repairMissingArtifacts, repairResultContract, requireGitPush, retryProviderFailures, requiredArtifacts, stopWhen	snake_case equivalents
resources.mcpServers	resources.mcp_servers
workspace.repository_selector / repositorySelector, branch_pattern / branchPattern	not currently supported at all — omit
artifact_policy.include_globs / exclude_globs	not currently supported at all — omit

:::note Legacy knowledge declarations The Backend still recognizes the older {category, scope: "org"} knowledge declaration and resolves the latest active org resource by category. The current UI emits versioned {ref, required} bindings; use that form for deterministic profiles. Project-scoped category mapping is not implemented. :::

provider_key values "claude" and "claude-cli" are canonicalized to "claude-code" automatically.