Backend Selection¶

Kedi separates framework adapters from agent harnesses because they expose different execution and capability contracts.

Frameworks with > adapter:¶

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

>> Summary of <document>: [summary: str].

Built-in framework shortnames are pydantic, dspy, and langchain. Frameworks are appropriate when Kedi owns structured prompting and registers typed tools through the framework's model interface.

Harnesses with > agent:¶

> agent: codex
> model: gpt-5
> settings:
    cwd: .
    sandbox: workspace-write

>> Inspect the repository and return [answer: str] explaining the failing test.
= <answer>

Built-in harness shortnames are claude, codex, and acp. Harnesses are appropriate when the underlying agent owns its tool loop, repository context, or protocol session.

Literal and Dynamic Selection¶

Literal names are validated by the parser/LSP and runtime:

> adapter: langchain

Use a backtick expression only when selection is genuinely dynamic:

```
selected_backend = "pydantic"
```

> adapter: `selected_backend`

Dynamic selection postpones validation and reduces static diagnostics. Prefer a literal or profile in production source.

ACP Commands¶

Select ACP using an explicit command:

> agent:
    acp: `["uv", "run", "my-acp-agent"]`

The command can be plain text or a Python expression evaluating to a string or sequence of strings. The structured form binds the command to the acp harness.

ACP commands are always explicit. Use multiline > agent: syntax or construct ACPAdapter(command=...) in Python. Plain > agent: acp, CLI command options, and environment command fallbacks are unsupported.

CLI and Environment Defaults¶

If source does not select a backend, Python configuration or CLI defaults can provide one. The Python API loads .env and recognizes:

KEDI_ADAPTER and KEDI_AGENT are mutually exclusive.

Selection Precedence¶

For a model call, selection priority is:

1. a direct directive in the current lexical scope;
2. a profile applied in that scope;
3. Python/CLI default agent profile;
4. environment-based default selection.

Nested scopes may choose another backend and restore the outer selection when they exit.

Invalid Combinations¶

A single lexical scope cannot mix > adapter: and > agent:. Kedi also rejects a framework name in > agent:, a harness name in > adapter:, conflicting environment defaults, a dynamic value with the wrong type, and an adapter instance whose declared kind does not match the selected API.

Switch in a nested procedure or define separate profiles instead of creating an ambiguous mixed scope.