AI, tools, and composition

Semantic model roles

Workflows select semantic roles such as summarization, not vendor model IDs. Model resolution follows this order:

1. exact configured role match,
2. general fallback when no exact match exists,
3. validation failure when no matching role and no general model exists.

ai-router always requests router, which still falls back to general when router is not configured. Configure named providers in config/providers.yaml and built-in or custom role assignments in config/models.yaml under WORKSPACE_ROOT. The Models page displays the effective startup configuration without editing it.

Treat this as a design principle, not only a convenience feature. Keep workflow manifests focused on intent and behavior, and keep vendor/model selection in deployment configuration.

Recommended role design:

1. Define roles by task semantics (classification, summarization, reasoning, router) rather than by model brand or version.
2. Reuse role names across workflows so behavior can be tuned centrally.
3. Keep at least one broad fallback role (general) and add specialized roles only when they meaningfully improve quality, cost, latency, or reliability.

Toolsets

Toolsets are registered by name and contain discoverable tool definitions plus an invocation function. Manifest capabilities control visibility and invocation:

permissions:
  tools:
    - id: find-invoice
      tool: accounting/find-invoice
      consent: inherit
    - id: post-entry
      tool: accounting/post-entry
      consent: always-ask

Tool names are <toolset>/<tool>. Only declared, non-denied tools enter the workflow context. Host policy defaults unclassified tools to ask; always-ask can tighten it. Matching host-issued grants can satisfy ask-level policy, otherwise approval becomes an interaction request. See Tool permissions for launch and delegation rules.

The server loads streamable HTTP MCP definitions from config/toolsets.yaml under WORKSPACE_ROOT. The Toolsets page displays the effective startup configuration without editing it. Core also supports programmatic HTTP and stdio MCP catalogs. For HTTP MCP, authorization is typically injected from an environment variable named by the toolset record so bearer tokens are never stored in workflow manifests. Treat every MCP server as privileged code with the authority of its configured credentials.

Composable workflows

A manifest tool block makes a workflow addressable by its tool name. Call it with a workflow node or declare workflow/<name> as an agent capability. Child workflows receive only mapped input and return their final output. Launch grants do not pass to a child unless the parent capability explicitly delegates child capability IDs and the child tool trigger requests them. Failures and suspension propagate through the parent checkpoint stack. Discovery rejects missing dependencies, invalid delegations, duplicate tool names, and workflow dependency cycles.

Agent loop

An agent-request produces one turn. The tool route leads to tool-call, interaction can lead to interaction-input, and final exits. maxSteps provides a hard upper bound. Models used here must implement the agent-capable contract, not only the simple completion contract.