Agent

@kindgi/specs/agent.schema.json, schema version 1.3.0.

An agent definition. Declarative composition of instructions + capabilities + tools + memory retrieval + guardrails + conversation policy. The same definition is durable across restarts and versioned like flows — provenance references agents by (id, version).

• id (string, required): Agent identifier. Convention: '<pack>.<agent>' (e.g. 'acme.citation-verifier').
• version (string, required): Semver identifying this iteration of the agent. Different versions are different agents for audit purposes.
• name (string, required): Human-readable display name.
• description (string): Prose describing what the agent does. Shown in catalog + provenance metadata.
• instructions (string, required): System-prompt rendered at the top of every turn. LiquidJS template — {{ variable }} substitution, {% if %} / {% for %} control flow, {{ value | filter }} filters. Every referenced variable must be a declared PromptParameter or a framework auto-var (today, now, agent., conversation.). Rendered with strictVariables — unresolved refs are hard errors.
• parameters (array of PromptParameter): Typed parameters supplied at invoke time. UI reads this to build a configuration form; runtime validates required parameters are provided before the model call.
• capabilities (array of object, required): Capability declarations consumed by the router at turn time. One entry per resource kind the agent needs (e.g. LLM inference, embedding, gpu-compute). The router matches each entry by its kind (Capability.kind, default llm-inference) and its requirements; the array shape lets new kinds arrive without a schema break.
• tools (array of ToolRef, required): Tools the agent may invoke, as { id, version } references; an empty array makes the agent chat-only. At run start each reference resolves to the highest registered version that satisfies its range; an unresolvable reference fails the turn. Schema-version 1.1.0 replaced the bare-string tool ids of 1.0.0, which defineAgent already rejected.
• retrieval (array of RetrievalIntent, required): Fact-retrieval intents run before every turn to ground the model's context.
• guardrails (array of string, required): Guardrail ids the agent is subject to. Resolved at turn start against the guardrails bound for the run (an unknown id fails the turn); evaluated on each turn's final response, before it is stored.
• preferredProvider (string): Preferred model provider id. Soft hint: the router prefers this provider when it satisfies the agent's capabilities and tenant policy, and otherwise routes normally.
• preferredModel (string): Preferred model name within the selected provider. Soft hint, combined with preferredProvider.
• conversationPolicy (ConversationPolicy)
• budget (TurnBudget)
• tags (array of string): Free-form filter tags for the catalog. Not consumed by execution.
• output (AgentOutputSpec)
• toolErrors (ToolErrorsSpec)

Definitions

ToolErrorsSpec

What the turn does when a tool call fails (schema-version 1.3.0): the failure goes back to the model as the call's result, so it can correct the call, up to maxRetries times per turn, for the kinds in retryOn. Default: one retry, for invalid-arguments and unknown-tool. A tenant tool-errors policy can lower it.

• maxRetries (integer): Failed calls sent back to the model per turn. Default 1.
• retryOn (array of "invalid-arguments" | "unknown-tool" | "tool-error"): Which failures are sent back: arguments that don't fit the input schema, a tool the agent doesn't have, a tool that ran and failed. Default invalid-arguments, unknown-tool.

AgentOutputSpec

A typed result (schema-version 1.2.0): the final answer must be JSON matching schema. An invalid answer is sent back to the model with the problems listed, up to maxRepairs times; then the turn fails with output-schema-violation.

• schema (object, required): JSON Schema (draft 2020-12) the final answer must match.
• name (string): A name for the output, shown to the model and in errors. Default output.
• maxRepairs (integer): How many times the model is asked to repair an invalid answer. Default 1.

ToolRef

A typed tool reference: a tool id plus a semver range. Bare-string ids are not accepted — every reference names both.

• id (string, required): Tool id (e.g. 'acme.verify-citation'). Must not be blank.
• version (string, required): npm-style semver range: '1.2.3' pins exactly, '^1.2.3' allows compatible updates, '~1.2.3' patch updates only, '>=1.0.0 <2.0.0' an explicit range. Must not be blank; the range grammar is checked when the reference resolves at run start.

PromptParameter

• name (string, required): Variable name referenced in the instructions template. Must NOT collide with reserved auto-var namespaces: today, now, agent, conversation.
• description (string): UI-facing description of what the caller should supply.
• type ("string" | "number" | "boolean" | "date", required)
• required (boolean): Default true. Set false to allow the parameter to be omitted.
• default (object): Value used when the caller omits this parameter. Must match the declared type.

RetrievalIntent

• types (array of string, required)
• scope ("same-conversation" | "same-project" | "tenant", required)
• limit (integer): Cap on facts per turn. Default 10.
• mode ("keyword" | "semantic" | "both")

ConversationPolicy

• historyLimit (integer)
• autoCloseAfterInactiveSeconds (integer)
• hitlAfterTurns (integer)

TurnBudget

• maxSteps (integer): Maximum model→tool→model iterations per turn. Default 8.
• maxCostUsd (number): Maximum USD spend per turn.
• maxWallMs (integer): Wall-clock cap in ms. Default 120000.