Agent Agent protocol schemas
AI Model Configuration
Source: packages/spec/src/ai/agent.zod.ts
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); Property Type Required Description provider Enum<'openai' | 'azure_openai' | 'anthropic' | 'local'>optional (default: "openai") model string✅ Model name (e.g. gpt-4, claude-3-opus) temperature numberoptional (default: 0.7) maxTokens numberoptional topP numberoptional
Property Type Required Description name string✅ Agent unique identifier label string✅ Agent display name avatar stringoptional 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. surface Enum<'ask' | 'build'>optional (default: "ask") Product surface this agent binds ('ask' | 'build') — ADR-0063 §1 skills string[]optional Skill names to attach (Agent→Skill→Tool architecture) tools neveroptional [REMOVED] agent.tools was removed in @objectstack/spec 17 — 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 list the mechanical edits for existing sources; apply them by hand. knowledge neveroptional [REMOVED] agent.knowledge was removed in @objectstack/spec 17.0.0 (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 list the mechanical edits for existing sources; apply them by hand. active booleanoptional (default: true) 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. 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. 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. 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 stringoptional 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 stringoptional Owning package machine id. _packageVersion stringoptional Owning package version. _lockDocsUrl stringoptional Optional documentation link surfaced next to _lockReason.
Property Type Required Description provider Enum<'openai' | 'azure_openai' | 'anthropic' | 'local'>optional (default: "openai") model string✅ Model name (e.g. gpt-4, claude-3-opus) temperature numberoptional (default: 0.7) maxTokens numberoptional topP numberoptional
Property Type Required Description id string✅ Unique Machine ID description stringoptional contextSchema Record<string, any>optional Zod Schema for the machine context/memory initial string✅ Initial State ID states Record<string, { type: Enum<'atomic' | 'compound' | 'parallel' | 'final' | 'history'>; entry?: (string | object)[]; exit?: (string | object)[]; on?: Record<string, string | object | object[]>; … }>✅ State Nodes on Record<string, string | { target?: string; cond?: string | object; actions?: (string | object)[]; description?: string } | { target?: string; cond?: string | object; actions?: (string | object)[]; description?: string }[]>optional
Property Type Required Description maxIterations integeroptional (default: 10) Maximum planning loop iterations
Property Type Required Description longTerm { enabled: boolean; store: Enum<'vector' | 'database' | 'redis'>; maxEntries?: integer }optional Long-term / persistent memory reflectionInterval integeroptional Reflect every N interactions to improve behavior
Property Type Required Description maxTokensPerInvocation integeroptional Token budget per single invocation maxExecutionTimeSec integeroptional Max execution time in seconds blockedTopics string[]optional Forbidden topics or action names
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 booleanoptional (default: false) Enforce exact schema compliance retryOnValidationFailure booleanoptional (default: true) Retry generation when output fails validation maxRetries integeroptional (default: 3) 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
Property Type Required Description lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>✅ Lock policy — none | no-overlay | no-delete | full. reason string✅ User-visible reason shown when the lock blocks an action. docsUrl stringoptional Optional URL the Studio banner links to for more context.
Structured output configuration for agent responses
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 booleanoptional (default: false) Enforce exact schema compliance retryOnValidationFailure booleanoptional (default: true) Retry generation when output fails validation maxRetries integeroptional (default: 3) 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
Output format for structured agent responses
json_objectjson_schemaregexgrammarxml
Post-processing step for structured output
trimparse_jsonvalidatecoerce_types
ObjectStack