Agents, models & tools
Agent composition, alias-based model routing, and the governed tool layer.
Agents
An Agent is a versioned composition: a workflow (or node) plus its model alias, prompts,
tool permissions, and guardrail bindings. Like workflows, agent versions are immutable — you
publish a new version and flip the pointer. That makes "which agent answered this?" a precise,
auditable question: (agent_id, version) pins everything the agent could see and do.
Model routing
Agents never hard-code a provider model. They bind a model alias
(tier-1-reasoning, fast-cheap, …) that the router resolves per call:
- The alias resolves to a concrete
(provider, model_id, model_version). - Layered configuration applies: platform defaults → tenant → agent → experiment → request. A tenant can pin models; an experiment can flip a variant; nothing redeploys.
- The call is budget-checked, credential-injected (provider keys are fetched just-in-time — never held by agent code), and dispatched.
- On provider failure the resolved fallback chain is walked.
- Every call mints provenance —
(model_id, model_version, output_id)— plus token counts and cost, joined to the run's trace.
Tools
Tools are governed in two planes:
- The registry (definition plane) is the system of record: every agent-callable tool — MCP server, OpenAPI operation, native function — is registered with its schema and owner. Definitions are versioned and immutable; schema drift quarantines a tool automatically.
- The gateway (invocation plane) is the single enforcement point every call crosses. Agents never speak HTTP/MCP directly. Per invocation, the gateway enforces — at one logical point — the concerns an agent must not be trusted with:
| Check | What it does |
|---|---|
| Agent allowlist | The agent may only call tools its manifest declares. |
| Access control | Per-resource permission check (execute) before anything else. |
| Policy | Tenant policy + approval gates evaluate the invocation context. |
| Schema validation | Arguments validate against the registered JSON Schema. |
| Rate limits | Per-tenant × per-tool budgets. |
| Credential injection | Secrets are injected just-in-time, invisibly to the agent. |
| Output guardrails | Tool responses are classified before the agent sees them. |
| Audit | Every invocation — including denials — is recorded. |
Guardrails
Content safety wraps every LLM-mediated boundary in three layers: input classification, instruction/data separation, and output classification (including tool responses). The guardrail engine fails closed — a classifier outage is a trip, not a pass. Rule sets are platform-governed with per-tenant additions.
Secrets
The vault stores credentials once, envelope-encrypted per tenant. Agents reference secrets by name; values are injected at invocation time with scoped policies and never appear in prompts, traces, or logs. API keys are shown once at creation.