skills/kora-workflow-builder/references/agent-config.md

# Agent Config

Agent config lives on a `Capability` under `spec.agentConfig`. It controls how
an agent-assigned task is executed when a role assignment resolves to an agent.

```yaml
spec:
  agentConfig:
    mode: agentic
    requiresOutputReview: true
    systemPrompt: |
      Review the input and return the declared output JSON.
    model:
      ref: openai/gpt-5.4-mini
      thinkingLevel: off
    limits:
      maxTurns: 8
      maxDurationMs: 600000
      maxBudgetUsd: 2
    extensions:
      - github-primary
    execution:
      sandbox:
        network:
          defaultAction: deny
          inheritManaged: false
    output:
      schemaRef: ReviewResult
      maxRepairAttempts: 2
```

Rules:

- Use `mode: prompt` for single-turn prompt execution.
- Use `mode: agentic` when the task needs iterative tool use.
- Omit `agentConfig.model` to use the organization's workflow default, then the
  deployment fallback when the organization has not selected one.
- Use `agentConfig.model.ref` only for refs in the bundled Core model catalog. Do not
  invent arbitrary provider/model strings.
- `agentConfig.model.thinkingLevel` is optional. Use `off` to suppress thinking
  for that capability; otherwise use one of the supported runtime levels.
- Organization owners must add the selected model under Settings > Models
  before a release using that explicit model can deploy, unless the deployment
  already supplies matching fallback access. Model API keys are not stored in
  YAML.
- Built-in agent tools are provided by the runtime for `mode: agentic`.
- External APIs and domain-specific behavior should be modeled as extension
  functions, extension agent surfaces, and service operations, not hidden in
  the agent config.
- `agentConfig.extensions` is only for agent task nodes. It does not expose
  tools or skills to the workflow-authoring environment.
- Each `agentConfig.extensions` entry names an installed extension. Enabling it
  with shorthand exposes all granted static tools, provider-discovered tools,
  and skills from that install.
- Use object form to restrict an agent task to selected extension tools and
  skills:

  ```yaml
  extensions:
    - name: github-primary
      tools:
        - searchIssues
        - createIssue
      skills:
        - github-triage
  ```

- In object form, `tools` and `skills` may be `all`; omitted categories mean
  none, and the entry must include at least one of `tools` or `skills`.
- Extension skills reference registered skill roots in the installed package
  revision; the root must contain `SKILL.md` and may include adjacent assets.
- Agent output should match the workflow node's declared `output` type.
- `requiresOutputReview: true` is a capability policy for successful output
  produced by an agent. Every ordinary task using that capability must declare
  `agentOutputReview` to a directly reachable explicit human task, even if its
  current role assignment is human. Its object output type must set top-level
  `additionalProperties: false`.
- The runtime uses ordinary `next` for a human performer and for an agent whose
  capability does not require review. It uses only `agentOutputReview` for a
  successful agent whose capability requires review.
- Output review is post-execution supervision. It does not authorize extension
  tools, built-in tools, or external side effects. Put irreversible action in a
  service node after the human decision.
- Agent failure, invalid output, timeout, veto, and `agent_needs_human` do not
  take the output-review edge. Route expected failures with explicit error
  boundaries.
- `output.maxRepairAttempts` repairs structured output inside one agent task
  attempt. Whole-node retry belongs on the workflow `task` or `task.each` node,
  not in `agentConfig`.
- Prompt artifact attachments are workflow-node settings, not capability
  settings. Put `promptAttachments` on the specific `task` or `task.each` node
  that should send selected top-level file artifact input fields to the model.
- Use image attachments only for actual PNG/JPEG/GIF/WebP artifacts and text
  attachments only for extractor-produced text artifacts. For PDFs, Office
  docs, HTML, ZIPs, or other rich/binary files, model an extractor service node
  first and attach the extracted text or image artifact.

## Supported Model Refs

Keep this list aligned with the Core supported agent model registry and
`koractl` model choices:

<!-- supported-agent-model-refs:start -->
- `anthropic/claude-opus-4-6`
- `anthropic/claude-opus-4-8`
- `anthropic/claude-opus-4-7`
- `anthropic/claude-sonnet-4-6`
- `anthropic/claude-haiku-4-5`
- `openai/gpt-5.5`
- `openai/gpt-5.4`
- `openai/gpt-5.4-mini`
- `google/gemini-3.5-flash`
- `google/gemini-3.1-pro-preview`
- `xai/grok-4.3`
- `moonshotai/kimi-k2.6`
- `deepseek/deepseek-v4-pro`
- `deepseek/deepseek-v4-flash`
- `zai/glm-5.1`
- `zai/glm-4.7`
- `minimax/MiniMax-M3`
- `mistral/mistral-medium-3.5`
- `mistral/mistral-large-2512`
- `groq/meta-llama/llama-4-scout-17b-16e-instruct`
- `google/gemma-4-31b-it`
<!-- supported-agent-model-refs:end -->