DefineAgentSpec

Author-facing input shape for defineAgent. id and version are strings (they get branded inside defineAgent); array fields are readonly so callers can pass literal arrays.

Field-by-field authoring guide

The most common author mistake is treating tools as a list of tool ids (strings). It is NOT — it is a list of {id, version} refs where version is an npm-style semver RANGE ('^1.0.0', '~1.2.3', '1.0.0', '>=1.0.0 <2.0.0'). Resolution happens at run start via semver.maxSatisfying.

Example

const agent = defineAgent({
  id: 'my-pack.summarizer',
  version: '1.0.0',
  name: 'Summarizer',
  instructions: 'Summarize the user message in one sentence.',
  capabilities: [{ needs: [{ feature: 'tool-use' }] }],
  tools: [
    { id: 'my-pack.fetch-doc', version: '^0.1.0' },
  ],
  retrieval: [],
  guardrails: [],
  budget: { maxSteps: 6, maxCostUsd: 0.1, maxWallMs: 30_000 },
});

Properties

Property	Modifier	Type	Description
budget?	readonly	TurnBudget	Turn budget caps. maxSteps limits model+tool call loop iterations per turn; maxCostUsd caps model spend per turn; maxWallMs bounds turn wall-clock time. Exceeding any cap ends the turn with a budget-exceeded failure. Sensible dev defaults: {maxSteps: 6, maxCostUsd: 0.1, maxWallMs: 30_000}.
capabilities	readonly	readonly Capability[]	Required capabilities the agent needs from a ModelProvider. Typically one entry: [{ needs: [{ feature: 'tool-use' }] }] for a tool-calling agent, [{ needs: [{ feature: 'structured-output' }] }] for an agent that returns schema-constrained JSON. The router uses the first entry to pick a compatible provider from the tenant's ProviderRegistry.
conversationPolicy?	readonly	ConversationPolicy	Per-conversation behavior — how much history to load, when to gate on HITL, when to auto-close. Every field optional; defaults are "load the full history, no HITL, no auto-close". See ConversationPolicy for the full shape including tool-level HITL rules.
description?	readonly	string	Optional longer description shown in catalogs / admin surfaces.
guardrails	readonly	readonly string[]	Guardrail IDs that guard this agent's turns. Each id must resolve among the guardrails bound for the run, or the turn fails with unresolved-guardrail. Guardrails are evaluated once per turn, on the final response before it is stored — see defineCheck for the checker side. Empty array [] = no guarding.
id	readonly	string	Business identifier. Convention: <pack-id>.<agent-name> (e.g. 'acme.contract-reviewer'). Non-empty. Gets branded as AgentId inside defineAgent.
instructions	readonly	string	The system prompt. Sent to the model with every turn as the baseline instructions. Load-bearing — this is where you shape the agent's behavior (persona, output format, tool-use policy).
name	readonly	string	Human-readable name for UI and logs.
output?	readonly	object	A typed result: the final answer must be JSON matching schema (JSON Schema, or a Zod schema converted at definition time). An invalid answer is sent back to the model with the problems listed, up to maxRepairs times (default 1). See AgentOutputSpec.
output.maxRepairs?	readonly	number	-
output.name?	readonly	string	-
output.schema	readonly	AnySchema	-
parameters?	readonly	readonly PromptParameter[]	Optional named prompt parameters. Callers pass values for these in invokeAgent({parameters: {...}}); the framework substitutes them into instructions. Each parameter declares its type + default. Absent = agent takes no runtime parameters.
preferredModel?	readonly	string	Preferred model name within the selected provider. Soft hint — see Agent.preferredModel.
preferredProvider?	readonly	string	Preferred model provider by id. Soft hint — the router prefers this provider when it satisfies capabilities.needs + tenant policy, falling back to normal capability-based selection when the preferred provider is unregistered or filtered out. Enables A/B'ing agents across providers without churning registrations: register several, pin the agent to the one you want to test. The value is a ProviderMetadata.id string (e.g. 'anthropic-claude-sonnet-4-6'). Unset = capability-match only.
retrieval	readonly	readonly RetrievalIntent[]	Retrieval intents the agent runs BEFORE calling the model. Each intent names fact types, a scope, and a retrieval mode; the results are injected into the model input as retrieved context. Empty array [] = no retrieval, model sees only the conversation history + user message.
tags?	readonly	readonly string[]	Free-form tags for catalog filtering. Not interpreted by the runtime.
toolErrors?	readonly	ToolErrorsSpec	What the turn does when a tool call fails: 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 (nothing ran). A tenant's tool-errors policy can lower it. See ToolErrorsSpec.
tools	readonly	readonly ToolRef[]	Tools the agent may call. NOT a list of tool ids — a list of {id, version} refs where version is an npm-style semver range. At run start, each ref resolves against the registered versions via semver.maxSatisfying; unresolvable refs fail the turn with tool-version-unresolvable. The model sees each tool's id, description, and input schema — write tool descriptions carefully (that's what the LLM reads to decide when to call).
version	readonly	string	Exact semver of THIS agent revision (e.g. '1.0.0', '0.2.1-alpha.3'). Distinct from tool version RANGES on tools[]. Every publish under the same id must bump this.