Skip to content

Profiles

Profiles are named, reusable agent-state fragments. They make backend, instructions, tools, approval, and delegation reviewable as one unit.

Define a Profile

> profile: reviewer:
    ###
    Reviews one change against repository evidence.
    ###
    > adapter: pydantic
    > model: groq:qwen/qwen3-32b
    > effort: medium
    > system: Cite the evidence used for every finding.
    > settings:
        temperature: 0.1

A profile body may contain > adapter:, > agent:, > model:, > effort:, > approval:, > system:, > settings:, > mcp:, > use:, > subagent:, > max_agents:, and > workflow:.

Profile Documentation

When a ### block is the first profile member, it becomes the profile docstring. The LSP shows it in hover and subagent tool descriptions. A later block remains an ordinary comment.

Document what task the profile owns, what evidence it should return, and any important limitation. Child-agent descriptions depend on this text.

Apply a Profile

Single-line > use: applies a profile when no procedure with that name exists:

> use: reviewer

>> Review of the current change: [review: str].
= <review>

If a procedure and profile share a name, the procedure wins and is registered as a tool. Avoid such collisions.

Merge Rules

Applying a profile merges it into active state:

  • scalar members such as backend, model, effort, system, approval, max_agents, and workflow mode replace earlier values when specified;
  • settings merge by key;
  • tools and subagents merge by name, with later bindings taking precedence;
  • MCP servers append in order;
  • omitted members inherit from the active state.

Direct directives after profile application can override profile members:

> use: reviewer
> effort: high

The result uses the reviewer's backend, model, instructions, and settings with high effort.

Export and Import Profiles

Profiles are module values and can be explicitly exported:

> profile: reviewer:
    > adapter: pydantic
    > model: groq:qwen/qwen3-32b

> export:
  reviewer

Imported profiles retain private tool and child-profile bindings needed by their contract without flattening those dependencies into the importer's procedure namespace. This lets a package expose a profile facade while keeping helpers private.

Forward References and Validation

A profile can name a child profile declared later. Kedi resolves the complete profile graph and rejects unknown children and cycles.

Within one profile, framework and harness selection remain mutually exclusive. Invalid backend kinds, duplicate or unknown members, invalid settings, nonpositive max_agents, missing tools, and unsupported required capabilities produce diagnostics or compile-time errors.

Child Profiles

> profile: coordinator:
    > adapter: pydantic
    > subagent: researcher
    > max_agents: 3
    > workflow: dynamic

> profile: researcher:
    > adapter: pydantic
    > system: Investigate one self-contained question.

Only directly listed children can be delegated to. max_agents bounds the descendant work started by one parent invocation. Workflow mode defaults to delegate; dynamic exposes one sandboxed Python orchestration tool. See Subagents for lifecycle and safety rules.

Choosing Profile Boundaries

Create a profile when a task needs a stable combination of behavior and capabilities. Do not create one merely to alias a model string. Profiles should be narrow enough that their tools, approvals, and child relationships can be reviewed as a coherent security boundary.