---
title: Agent
description: Agent protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

AI Model Configuration

<Callout type="info">
**Source:** `packages/spec/src/ai/agent.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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** | `Object` | optional |  |
| **lifecycle** | `Object` | optional | State machine defining the agent conversation follow and constraints |
| **skills** | `string[]` | optional | Skill names to attach (Agent→Skill→Tool architecture) |
| **tools** | `Object[]` | optional | Direct tool references (legacy fallback) |
| **knowledge** | `Object` | optional | RAG access |
| **active** | `boolean` | ✅ |  |
| **access** | `string[]` | optional | Who can chat with this agent |
| **permissions** | `string[]` | optional | Required permissions or roles |
| **tenantId** | `string` | optional | Tenant/Organization ID |
| **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | ✅ |  |
| **planning** | `Object` | optional | Autonomous reasoning and planning configuration |
| **memory** | `Object` | optional | Agent memory management |
| **guardrails** | `Object` | optional | Safety guardrails for the agent |
| **structuredOutput** | `Object` | optional | Structured output format and validation configuration |
| **protection** | `Object` | 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`


---

