Agent

AI Model Configuration

Source: packages/spec/src/ai/agent.zod.ts

TypeScript Usage

import { AIModelConfigSchema, AgentSchema, StructuredOutputConfigSchema, StructuredOutputFormatSchema, TransformPipelineStepSchema } from '@objectstack/spec/ai';
import type { Agent, StructuredOutputConfig, StructuredOutputFormat, TransformPipelineStep } from '@objectstack/spec/ai';

// Validate data
const result = AIModelConfigSchema.parse(data);

AIModelConfig

Properties

Property	Type	Required	Description
provider	`Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>`	✅
model	`string`	✅	Model name (e.g. gpt-4, claude-3-opus)
temperature	`number`	✅
maxTokens	`number`	optional
topP	`number`	optional

Properties

Property	Type	Required	Description
name	`string`	✅	Agent unique identifier
label	`string`	✅	Agent display name
avatar	`string`	optional
role	`string`	✅	The persona/role (e.g. "Senior Support Engineer")
instructions	`string`	✅	System Prompt / Prime Directives
model	`{ provider: Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>; model: string; temperature: number; maxTokens?: number; … }`	optional
lifecycle	`{ id: string; description?: string; contextSchema?: Record<string, any>; initial: string; … }`	optional	[EXPERIMENTAL — not enforced] State machine defining the agent conversation flow and constraints. Parsed but no runtime consumer yet (liveness #1878/#1893).
surface	`Enum<'ask' \| 'build'>`	✅	Product surface this agent binds ('ask' \| 'build') — ADR-0063 §1
skills	`string[]`	optional	Skill names to attach (Agent→Skill→Tool architecture)
tools	`never`	optional	[REMOVED] `agent.tools` was removed in @objectstack/spec 17 (#3894) — use `skills`. An agent reaches exactly the tools its surface-compatible skills declare (ADR-0064), so move each reference into a skill: a platform tool by its registered name, or `action_<name>` for one of your own AI-exposed Actions. This is NOT a rename — there is no key the value moves to: the migration DELETES the key and emits a notice naming each tool that was listed, and you re-declare each one in a skill by hand. Run `os migrate meta --from 16` to rewrite existing sources automatically.
knowledge	`never`	optional	[REMOVED] `agent.knowledge` was removed in @objectstack/spec 17.0.0 (#3896 audit close-out) — declaring knowledge sources/indexes on an agent never scoped retrieval: the `search_knowledge` tool takes `sourceIds` from the LLM's tool-call arguments, not from the agent record. Delete the block. Restrict retrieval at the knowledge-service / source level (per-source permissions), and describe intended grounding in `instructions` so the model asks for the right sources. Run `os migrate meta --from 16` to rewrite existing sources automatically.
active	`boolean`	✅
access	`string[]`	optional	Who can chat with this agent
permissions	`string[]`	optional	Required permission-set capabilities
planning	`{ maxIterations: integer }`	optional	Autonomous reasoning and planning configuration
memory	`{ longTerm?: object; reflectionInterval?: integer }`	optional	[EXPERIMENTAL — not enforced] Agent memory management. Parsed but no runtime consumer yet (liveness #1878/#1893).
guardrails	`{ maxTokensPerInvocation?: integer; maxExecutionTimeSec?: integer; blockedTopics?: string[] }`	optional	[EXPERIMENTAL — not enforced] Safety guardrails for the agent. Parsed but not enforced — real limits come from the quota service (liveness #1878/#1893).
structuredOutput	`{ format: Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>; schema?: Record<string, any>; strict: boolean; retryOnValidationFailure: boolean; … }`	optional	[EXPERIMENTAL — not enforced] Structured output format and validation configuration. Parsed but no runtime consumer yet (liveness #1878/#1893).
protection	`{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }`	optional	Package author protection block — lock policy for this agent.
_lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	optional	Item-level lock — controls overlay & delete (ADR-0010).
_lockReason	`string`	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	`Enum<'artifact' \| 'package' \| 'env-forced'>`	optional	Layer that set _lock (artifact \| package \| env-forced).
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package \| org \| env-forced).
_packageId	`string`	optional	Owning package machine id.
_packageVersion	`string`	optional	Owning package version.
_lockDocsUrl	`string`	optional	Optional documentation link surfaced next to _lockReason.

StructuredOutputConfig

Structured output configuration for agent responses

Properties

Property	Type	Required	Description
format	`Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>`	✅	Expected output format
schema	`Record<string, any>`	optional	JSON Schema definition for output
strict	`boolean`	✅	Enforce exact schema compliance
retryOnValidationFailure	`boolean`	✅	Retry generation when output fails validation
maxRetries	`integer`	✅	Maximum retries on validation failure
fallbackFormat	`Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>`	optional	Fallback format if primary format fails
transformPipeline	`Enum<'trim' \| 'parse_json' \| 'validate' \| 'coerce_types'>[]`	optional	Post-processing steps applied to output

StructuredOutputFormat

Output format for structured agent responses

Allowed Values

json_object
json_schema
regex
grammar
xml

TransformPipelineStep

Post-processing step for structured output

Allowed Values

trim
parse_json
validate
coerce_types

Agent

On this page