agent.mdx

title	Agent
description	Agent protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

AI Model Configuration

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

TypeScript Usage

import { AIKnowledge, AIModelConfig, AITool, Agent, StructuredOutputConfig, StructuredOutputFormat, TransformPipelineStep } from '@objectstack/spec/ai';
import type { AIKnowledge, AIModelConfig, AITool, Agent, StructuredOutputConfig, StructuredOutputFormat, TransformPipelineStep } from '@objectstack/spec/ai';

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

---

AIKnowledge

Properties

Property	Type	Required	Description
topics	string[]	✅	Topics/Tags to recruit knowledge from
indexes	string[]	✅	Vector Store Indexes

---

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

---

AITool

Properties

Property	Type	Required	Description
type	Enum<'action' | 'flow' | 'query' | 'vector_search'>	✅
name	string	✅	Reference name (Action Name, Flow Name)
description	string	optional	Override description for the LLM

---

Agent

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	State machine defining the agent conversation follow and constraints
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	{ type: Enum<'action' | 'flow' | 'query' | 'vector_search'>; name: string; description?: string }[]	optional	Direct tool references (legacy fallback)
knowledge	{ topics: string[]; indexes: string[] }	optional	RAG access
active	boolean	✅
access	string[]	optional	Who can chat with this agent
permissions	string[]	optional	Required permission-set capabilities
tenantId	string	optional	Tenant/Organization ID
visibility	Enum<'global' | 'organization' | 'private'>	✅	[EXPERIMENTAL — NOT ENFORCED, #1901] Intended listing scope. No runtime consumer yet; use access/permissions for real gating.
planning	{ strategy: Enum<'react' | 'plan_and_execute' | 'reflexion' | 'tree_of_thought'>; maxIterations: integer; allowReplan: boolean }	optional	Autonomous reasoning and planning configuration
memory	{ longTerm?: object; reflectionInterval?: integer }	optional	Agent memory management
guardrails	{ maxTokensPerInvocation?: integer; maxExecutionTimeSec?: integer; blockedTopics?: string[] }	optional	Safety guardrails for the agent
structuredOutput	{ format: Enum<'json_object' | 'json_schema' | 'regex' | 'grammar' | 'xml'>; schema?: Record<string, any>; strict: boolean; retryOnValidationFailure: boolean; … }	optional	Structured output format and validation configuration
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

---