Agent Presets

"Agent preset" means two different things in Ductor, and conflating them causes confusion. This page keeps them apart.

1. Preset templates (connector actions)

A preset template is a compile-time agent baked into the binary and registered as a connector action under the agent provider (displayed as "AI Agents") so it appears one-click in the workflow editor palette alongside every other action. The provider is registered AuthNone and read-only — preset agents consume no per-tenant credentials; the inference proxy handles upstream LLM authentication.

Each template is a thin authoring wrapper: a model, a baked-in system prompt, and sensible generation defaults. The built-ins:

The action key is the provider key plus the slug — e.g. agent.support_triage.

Overriding a template per step

A step author supplies the input and can override the baked defaults:

The action output is a structured object:

{
  "preset": "support_triage",
  "model": "gpt-4o-mini",
  "provider": "openai",
  "content": "…the model's answer…",
  "latency_ms": 812,
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 }
}

Because a preset template is just a connector action, it runs anywhere a connector action runs — most commonly as a step in a workflow run. See workflow AI steps for how it slots into a DAG.

2. Tenant agent presets (versioned config)

A tenant agent preset is a reusable, tenant-owned agent configuration stored per tenant and versioned. It captures the full agent runtime configuration — model, provider, instructions, the tool set, per-tool approval requirements, output type, and generation parameters (max tokens, temperature, top-p, and the loop bounds max_tool_calls / max_requests) — so that a session or a workflow step can reference a preset by id instead of inlining all of that. A chat session records the preset it runs against via agent_preset_id; an ai_agent workflow step resolves a preset (optionally pinned to a version) at execution.

Every save mints a new version, so a PresetRef can pin an exact version — or use version 0 to mean "resolve the latest."

When the deployment defines a governed typed-decision policy, chat and workflow hosts apply it only while constructing a new immutable definition. It fills absent model-routing and completion policy; an already persisted definition wins, and active sessions never change when operator config changes.

The presets are managed through the AgentPresetService:

A tenant preset requires a name and a model. Its tool set may be empty for a model-only worker that produces text or structured output without calling tools. Every declared tool still requires a name and action, and names must be unique within the preset.

Tool and request bounds

Preset bounds are resolved after the workflow host merges the selected preset with step arguments and normalizes the effective definition:

Skills and declared specialists add callable broker tools, so an empty inline tool array alone does not establish a model-only definition. A workflow's explicit max_tool_calls: 0 survives preset resolution and JSON round trips. Negative bounds and an explicit max_requests: 0 are refused.

Model-only execution still persists a governed session, an empty tool manifest, policy evidence, and journaled model turns. An unsolicited tool proposal cannot execute. The worker registers against the same immutable preset version and definition hash as a worker with tools; final acceptance and receipt issuance use the same clearing contract.

Related