Use Case 029: Task-Type Routing & Agent Provisioning

Overview

Implementation status (agent-identity release, June 2026): partial. Shipping: the TaskType registry (CRUD at /ai-gateway/task-types), the dispatcher's classification-filtered resolution, and agent provisioning (agents carry AllowedTaskTypes + DefaultTaskType, set via the setup wizard / agent forms). Not yet built: the ordered model chain with a preference + health cascade (a task type currently routes to a single DefaultModelDeploymentId), the two distinct provisioning UX paths described below (purpose-picker / direct-model-picker), and seeded starter task types.

Description

This use case describes the TaskType registry — the routing primitive of the Application Manager (AM) LLM Gateway — and the two agent-provisioning UX paths that feed it. A TaskType binds a logical job (developer.code-generation, chat.general, analysis.financial) to an ordered modelChain of ModelDeployments, plus per-task defaults (responseSchema, timeout, maxRetries, temperature, classificationFloor). The dispatcher (UC-030) resolves a task type to the first viable deployment after a preference cascade and classification filter. Admins configure model selection once, per task type, and many agents share it — so swapping the underlying model chain happens in one place.

This is part of the agent-identity release. The SDK master design is riptide-sdk/docs/plans/AGENT-IDENTITY-ARCHITECTURE.md; the AM-side plan is docs/internal/agent-identity-plan.md (§2 and §3.7). The gateway absorbs the RAF-SVC-LLM specification — its task-type routing and deployment cascade become AM's design. Crucially, AM is task-types-only at the data layer: both provisioning UX paths — the purpose-picker and the direct-model-picker — produce the same TaskType data, so the dispatcher, dashboards, and audit see one mechanism with no special-case code. An agent's AllowedTaskTypes + DefaultTaskType replace the older AllowedProviderModels concept.

Implementation note — guided setup. The shipped entry point for standing up this chain is the AI Gateway → Setup wizard (/ai-gateway/setup). It walks provider account → model → deployment → task type → agent in order and shows a live readiness banner that reports real callability (a task type is callable only when it's enabled, wired to an enabled deployment whose model exists and whose provider account is enabled with a resolvable key — the same guards the dispatcher applies). It lists the specific blocker when a step isn't ready, and an on-demand Run live check issues a real provider probe. See AI Gateway & Model Governance.

Actors

Preconditions

1. Application Manager is running; the agent-identity EF migration (creating the TaskType table in IdentityDbContext and seeding starter task types) has been applied.
2. At least one ProviderAccount and one ModelDeployment exist (UC-028).
3. The acting principal is authenticated (X-Api-Key or admin cookie) and holds llm.gateway.config (for task types) and/or agents.write (for provisioning).
4. The agent being provisioned exists or is being created in the same flow (UC-025).
5. Starter task types are seeded; on first ProviderAccount registration the admin is prompted to bind them to available deployments.

Postconditions

Success Postconditions

1. A TaskType is persisted with its component-namespaced id ({component}.{task-name}), ordered modelChain, and defaults.
2. An agent has AllowedTaskTypes set and a DefaultTaskType chosen, via either provisioning path.
3. ResolveTaskType returns an ordered list of viable ModelDeployments after the preference cascade and classification filter.
4. Starter task types are bound to real deployments, so dispatch has a working chain from day one.
5. Registration/provisioning events are written to AuditLog.

Failure Postconditions

1. A TaskType whose modelChain references no viable deployment (all unreachable or below classificationFloor) is rejected or flagged unroutable.
2. A classificationFloor exceeding every chain deployment's maxClassification is rejected.
3. An agent provisioned with no resolvable task type cannot dispatch — UC-030 fails closed.
4. Duplicate task-type ids are rejected.

Primary Flow Sequence

sequenceDiagram
    actor Admin as Provisioning Admin
    participant Web as TaskTypesController / AgentsController
    participant Med as MediatR
    participant Resolve as ResolveTaskType
    participant Repo as LlmGateway Repos
    participant Audit as AuditLog

    Admin->>Web: Register task type (id, modelChain, defaults)
    Web->>Med: RegisterTaskType command
    Med->>Repo: Validate deployments exist + classificationFloor satisfiable
    Repo-->>Med: Validation OK
    Med->>Repo: Persist TaskType
    Med->>Audit: Write registration entry
    Med-->>Web: Task type registered
    Admin->>Web: Provision agent (purpose-picker: select task types)
    Web->>Med: Set AllowedTaskTypes + DefaultTaskType
    Med->>Resolve: ResolveTaskType(DefaultTaskType)
    Resolve->>Repo: Apply cascade + classification filter
    Repo-->>Resolve: Ordered viable deployments
    Resolve-->>Med: At least one viable deployment
    Med->>Audit: Write provisioning entry
    Med-->>Web: Agent provisioned
    Web-->>Admin: Agent ready to dispatch

UC-029a: Register / Edit a Task Type & Model Chain

Triggers

• Admin opens LLM Gateway > Task Types > New (or edits one) and submits, or POST /api/llm/task-types / PUT /api/llm/task-types/{taskType}.

Basic Flow

1. Admin enters a component-namespaced taskType id ({component}.{task-name}, e.g. analysis.financial) and a description.
2. Admin orders a modelChain — a list of ModelDeployments tried in preference order at dispatch.
3. Admin sets defaults: optional responseSchema (for structured output), timeout, maxRetries, optional temperature, optional classificationFloor.
4. RegisterTaskType validates the chain references existing deployments and that at least one chain deployment's maxClassification meets the classificationFloor.
5. The TaskType is persisted; the registration is audited.
6. UpdateTaskType edits the chain or defaults in place — every agent referencing the task type immediately picks up the new chain (the one-place-to-swap property).

Alternative Flows

• A1: classificationFloor unsatisfiable — no chain deployment's maxClassification reaches the floor; rejected with a validation error.
• A2: Empty / all-unreachable chain — task type flagged unroutable; agents may still reference it but dispatch fails closed until a viable deployment is added.
• A3: Duplicate id — taskType already registered; rejected.
• A4: Private direct-picker task type edited by hand — agent.{agentName}.direct task types are owned by the direct-picker flow; manual edits are allowed but warned (they may be overwritten on re-provisioning).

UC-029b: Resolve Task Type to Deployment (Cascade + Classification Filter)

Triggers

• The dispatcher (UC-030) calls ResolveTaskType(taskType, requestClassification); or an admin previews resolution from the task-type editor.

Basic Flow

1. ResolveTaskType loads the task type and its modelChain.
2. It applies the preference cascade: walk the chain in order, keeping deployments that are not Unreachable.
3. It applies the classification filter: drop any deployment whose maxClassification is below the request's data classification (or the task's classificationFloor).
4. The result is an ordered list of viable ModelDeployments — the first is the primary, the rest are fallbacks for retry/model-chain fallback (UC-030).
5. If the list is non-empty, resolution succeeds; the dispatcher proceeds.

Alternative Flows

• A1: No viable deployment — every chain entry is unreachable or below classification; resolution returns empty and dispatch fails closed (Unroutable).
• A2: Health-degraded primary — a Degraded primary is kept but ranked after Healthy peers where the cascade allows.
• A3: Classification floor stricter than request — the task's classificationFloor is applied even when the request classification is lower, raising the effective filter.

sequenceDiagram
    participant Disp as LlmDispatchService
    participant Resolve as ResolveTaskType
    participant TT as TaskType Repo
    participant Dep as ModelDeployment Repo

    Disp->>Resolve: ResolveTaskType(taskType, requestClassification)
    Resolve->>TT: Load task type + modelChain
    TT-->>Resolve: Ordered chain + classificationFloor
    Resolve->>Dep: Fetch deployments in chain
    Dep-->>Resolve: Deployments (health, maxClassification)
    Resolve->>Resolve: Cascade (drop Unreachable, prefer Healthy)
    Resolve->>Resolve: Classification filter (>= max(reqClass, floor))
    alt Viable deployments remain
        Resolve-->>Disp: Ordered viable deployments
    else None viable
        Resolve-->>Disp: Empty (Unroutable, fail closed)
    end

UC-029c: Purpose-Picker Agent Provisioning

Triggers

• Admin provisions an agent via "What will this agent do?" in the agent provisioning UI.

Basic Flow

1. The flow lists available task types (developer.code-generation, chat.general, analysis.financial, …) with descriptions.
2. Admin selects one or several task types.
3. AM sets the agent's AllowedTaskTypes to the selected set.
4. DefaultTaskType is set to the first selected task type.
5. No new task type is created — the agent references shared, admin-managed task types.
6. This is the strategic path: many agents share a task type, so swapping the underlying model chain happens once in the registry (UC-029a) and propagates to all of them.

Alternative Flows

• A1: Selected task type unroutable — admin warned at provisioning time that the task type currently resolves to no viable deployment; provisioning may proceed but dispatch will fail closed until fixed.
• A2: Zero selections — provisioning blocked; an agent must have at least one allowed task type.

UC-029d: Direct-Model-Picker Agent Provisioning

Triggers

• Admin provisions an agent via "Which models can this agent use?" in the agent provisioning UI.

Basic Flow

1. The flow lists available ModelDeployments (model, provider, classification, health) instead of task types.
2. Admin picks one or several deployments, in preference order.
3. AM creates a private task type named agent.{agentName}.direct with the picked deployments as its modelChain.
4. AM sets that private task type as both the agent's AllowedTaskTypes and its DefaultTaskType.
5. The admin never types the words "task type" — the mechanism is hidden behind a model picker.
6. This is the simple path for one-off agents; the produced data is identical to the purpose-picker output, so the dispatcher and audit see one mechanism.

Alternative Flows

• A1: Re-provision with a different model set — the existing agent.{agentName}.direct chain is replaced; an audit entry records the change.
• A2: Picked deployment later disabled — the private chain still references it; resolution (UC-029b) filters it out and falls through to the next picked deployment.
• A3: Name collision — if agent.{agentName}.direct already exists for a different agent, AM disambiguates with the agent id.

UC-029e: Seed & Bind Starter Task Types

Triggers

• Initial agent-identity migration runs (seeds starter task types); first ProviderAccount registration prompts the admin to bind them.

Basic Flow

1. The initial migration seeds starter task types: developer.code-generation, developer.code-explanation, developer.code-review, chat.general, chat.customer-support, analysis.financial, analysis.legal, summarization.document, embedding.search.
2. Default chains reference common cloud-provider deployments by intent (not yet bound to a specific account).
3. When an admin registers their first ProviderAccount and its deployments (UC-028), AM prompts: "Bind starter task types to your available deployments?"
4. The admin maps each starter task type's chain to one or more real ModelDeployments.
5. UpdateTaskType persists the bound chains; the starter task types become routable.
6. Agents provisioned via the purpose-picker can immediately select these starter types.

Alternative Flows

• A1: Admin skips binding — starter task types remain unroutable until bound; dispatch against them fails closed.
• A2: Partial binding — only some starter types are bound; the rest stay unroutable without blocking the bound ones.
• A3: Embedding task type — embedding.search binds only to embedding-capable deployments; non-embedding deployments are not offered for it.

API Endpoints

// POST /api/agents/{id}/provision/purpose
// Request
{
  "selectedTaskTypes": [
    "developer.code-generation",
    "developer.code-review"
  ]
}

// Response 200
{
  "agentId": "01J8ZA10AGENT00000000001",
  "allowedTaskTypes": [
    "developer.code-generation",
    "developer.code-review"
  ],
  "defaultTaskType": "developer.code-generation",
  "provisioningPath": "PurposePicker",
  "defaultTaskTypeRoutable": true
}

Business Rules

Data Requirements

TaskType

Agent provisioning fields (on AgentIdentity — see UC-025)

Security Considerations

• Authentication: API routes require X-Api-Key; Web admin routes require the admin cookie.
• Authorization / capabilities: task-type registry writes gated by llm.gateway.config; agent provisioning gated by agents.write; reads by llm.gateway.read. Capabilities compose into roles via the existing RBAC model.
• Data protection: task types and chains carry no secrets; provider credentials stay on ProviderAccount (UC-028) and are never referenced in task-type data.
• Audit: task-type registration/edits and both provisioning paths write AuditLog entries with actor chain. Direct-picker chain replacement is audited so the swap is forensically visible.
• PII handling: task-type and provisioning data carry no end-user PII; classificationFloor is the lever that keeps high-classification work off low-classification deployments — enforced at resolution and again at dispatch (UC-030).

Testing Scenarios

Related Use Cases

• UC-025: Agent Identity Registration & Lifecycle — the agent that carries AllowedTaskTypes/DefaultTaskType.
• UC-028: LLM Provider Account & Deployment Management — the deployments task-type chains resolve to.
• UC-030: LLM Request Dispatch — consumes ResolveTaskType output as the first dispatch step.

Revision History