Skip to content

agent.mdx

Latest commit

 

History

History
137 lines (96 loc) · 6.5 KB

agent.mdx

File metadata and controls

137 lines (96 loc) · 6.5 KB
Raw
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, Agent, StructuredOutputConfig, StructuredOutputFormat, TransformPipelineStep } from '@objectstack/spec/ai';
import type { AIKnowledge, AIModelConfig, Agent, StructuredOutputConfig, StructuredOutputFormat, TransformPipelineStep } from '@objectstack/spec/ai';

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

AIKnowledge

Properties

Property Type Required Description
sources string[] optional Knowledge sources/tags to recruit RAG context from. Canonical key consumed by the agent renderer (objectui AgentPreview KnowledgeSummary).
topics any optional [REMOVED] knowledge.topics was removed in @objectstack/spec 17 (#3855) — use knowledge.sources. Rename the key; the value (a list of source tags) is unchanged. Run os migrate meta --from 16 to rewrite it automatically.
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

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 [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 any 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. Run os migrate meta --from 16 to rewrite it automatically.
knowledge { sources?: string[]; topics?: any; indexes: string[] } optional RAG access
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