# AI & Agents (/docs/ai)



Ductor is not "an app with an AI feature bolted on." It is a workflow runtime that
an agent can operate the same way a person operates the REST API — and it can also
run agents of its own. This section documents that whole surface, and how the pieces
share one auth chain and one tool catalog.

In the clearing model, an AI agent is a kind of <Term name="Worker" /> — an
identity that can take work, run it under a budget, and be governed and metered
like any other worker (human or agent). Everything on this page is that
governance and execution surface as it ships today, alongside the worker registry
that gives an agent a bid-eligible identity. For **Agent RFQ** — agents *bidding*
on work, priced and settled — typed bid terms, buyer-side clearing, authenticated
submission, a published task spec, disclosure-scoped discovery, and an autonomous
bidder all ship as opt-in surfaces. Executing the won work is on the roadmap, and
clearing weighs a *declared* quality claim rather than a verified score.

There are two directions to keep straight:

* **Ductor as two MCP control planes.** External agent harnesses (Claude Code,
  Codex, OpenCode, Cursor) use the isolated
  [consumer and admin MCP servers](/docs/ai/mcp-server) to operate one tenant or
  govern tenant, member, role, invite, and API-key lifecycles. Both use Ductor's
  authentication and authorization chain, with different identities and tool
  registries.
* **Ductor running agents.** An in-product [chat agent](/docs/ai/chat-agent), a
  provider-agnostic [inference proxy](/docs/ai/inference-proxy), tenant
  [agent presets](/docs/ai/agent-presets), and
  [worker-side AI workflow steps](/docs/ai/workflow-ai-steps) — all layered over
  an [agent-tool-exposure](/docs/ai/agent-tool-security) authorization engine that
  decides which tools a session may even see.
* **Messaging providers hosting Ductor conversations.** The
  [external conversation bridge](/docs/ai/external-conversation-bridges) verifies a
  provider webhook, maps the provider user through an explicit tenant-owned binding,
  and runs that thread on the same durable agent runtime.

Ductor can also go the other way and *import* external MCP providers as connectors;
that lives with the connector machinery under
[External MCP providers](/docs/connectors/external-mcp-providers).

<Callout type="warn" title="Every AI feature is off by default and fails closed">
  `mcp.enabled`, `aichat.enabled`, and `ai_inference.enabled` all default to
  **false**. Nothing here is reachable until you opt in. And the dependencies are
  enforced at **startup**, not lazily: `aichat.enabled=true` requires
  `ai_inference.enabled=true` with at least one provider, a Postgres pool, and a
  ready MCP backend — miss any of them and the process fails to start rather than
  serving a half-wired agent. Provider API keys are never read from config files;
  they come from environment variables named by each provider's `api_key_env`.
</Callout>

## The shared spine [#the-shared-spine]

The reason these features belong in one section is that they are not independent
integrations — they reuse each other:

```mermaid
flowchart TD
  H["Tenant agent"] --> MCP["Consumer MCP<br/>tenant-scoped tools"]
  A["Platform-admin agent"] --> AMCP["Admin MCP<br/>product lifecycle"]
  D["Operator client"] --> CA["Durable chat host<br/>(application/aichat)"]
  W["Workflow run<br/>(ai_agent step)"] --> EX["Durable workflow host<br/>(application/workflow/dag)"]
  S["Slack thread"] --> EB["Authenticated conversation bridge"]
  CA --> RT["Shared agent runtime<br/>state machine + bounds"]
  EX --> RT
  EB --> RT
  RT --> J["Append-only agent journal<br/>sequence + replay cursor"]
  MCP --> REG["Canonical tool registry +<br/>exposure manifests"]
  AMCP --> AREG["Admin registry +<br/>platform authorization"]
  RT --> REG
  RT --> PX["Inference proxy<br/>(application/ai)<br/>provider-agnostic, OpenAI-compatible"]
  PX --> P["openai · anthropic · gemini · bedrock · ollama"]
```

The external MCP server and Ductor-hosted agents draw from the **same** canonical tool
catalog and enforce the **same** explicit agent-session exposure policy. Chat and workflow hosts
submit immutable turns to one journal-backed runtime rather than implementing separate
LLM loops. Every provider call routes through the inference vertical, while committed
events—not an open network connection—define progress.

## What's in this section [#whats-in-this-section]

<Cards>
  <Card title="MCP Admin & Consumer Servers" href="/docs/ai/mcp-server">
    Isolated stateless MCP 2026-07-28 planes for tenant operation and governed
    platform lifecycle administration.
  </Card>

  <Card title="Agent Tool Security" href="/docs/ai/agent-tool-security">
    The least-privilege exposure engine — explicit agent-session manifests, schema-hash
    binding, policies, redaction, and the decision receipts that authorize or deny
    every call.
  </Card>

  <Card title="Chat Agent" href="/docs/ai/chat-agent">
    Admit a turn, consume committed SSE events, reconnect by sequence, and resume
    approval-gated tools without repeating provider work.
  </Card>

  <Card title="Durable Agent Runtime" href="/docs/ai/durable-agent-runtime">
    The shared journal, state machine, immutable admission contract, recovery
    boundaries, execution bounds, and host adapters.
  </Card>

  <Card title="Durable Session Channels" href="/docs/ai/session-channels">
    Multi-turn identity, membership, ordered controls, resumable streams,
    verified snapshots, retention, and safe runtime upgrades.
  </Card>

  <Card title="Governed Agent Skills" href="/docs/ai/governed-skills">
    Signed, content-addressed instruction bundles with progressive disclosure
    and broker-authorized read-only access.
  </Card>

  <Card title="Provider-Aware Prompt Caching" href="/docs/ai/prompt-caching">
    Stable tenant-bound cache identities, native provider hints, normalized
    usage, and cache-aware budget accounting.
  </Card>

  <Card title="Trusted-Edge Admission" href="/docs/ai/trusted-edge-admission">
    Signed, expiring, replay-safe anti-abuse context for public chat admission.
  </Card>

  <Card title="Deterministic Agent Watches" href="/docs/ai/agent-watches">
    Explicitly approved monitoring with registered evaluators, live
    reauthorization, and durable notification evidence.
  </Card>

  <Card title="External Conversation Bridges" href="/docs/ai/external-conversation-bridges">
    Signed Slack ingress, explicit actor bindings, durable FIFO processing,
    same-thread replies, and encrypted single-use browser approvals.
  </Card>

  <Card title="Inference Proxy" href="/docs/ai/inference-proxy">
    The OpenAI-compatible, provider-agnostic router: RouteInference, health from
    live error rates, circuit breakers, and durable cost, latency, error, agent,
    workflow, and experiment attribution.
  </Card>

  <Card title="Experiments" href="/docs/management/experiments">
    Compare agent definitions and workflow steps with immutable exposure
    receipts and idempotent delayed scores.
  </Card>

  <Card title="Agent Presets" href="/docs/ai/agent-presets">
    Two things called "preset": compile-time preset templates surfaced as
    connector actions, and tenant-owned versioned agent presets referenced by
    sessions.
  </Card>

  <Card title="Workflow AI Steps" href="/docs/ai/workflow-ai-steps">
    Worker-side ai\_action and durable ai\_agent steps inside a DAG run.
  </Card>

  <Card title="External MCP Providers" href="/docs/connectors/external-mcp-providers">
    The other direction — importing a third-party MCP server as a Ductor connector.
  </Card>
</Cards>