AI & Agents Overview

The AI adapter brings Directive's constraint system to AI agent orchestration. Wrap any LLM framework with safety guardrails, approval workflows, token budgets, and state persistence.

Architecture

Directive doesn't replace your agent framework – it wraps it:

The AI adapter is organized into five sections:

Reading Paths

Quick Start Path

Build a working agent system step by step:

1. Running Agents – End-to-end examples
2. Agent Orchestrator – Single-agent with guardrails
3. Multi-Agent Orchestrator – Full multi-agent setup
4. Execution Patterns – Parallel, sequential, supervisor

Production Path

Harden for production after the basics:

1. Resilience & Routing – Retry, fallback, budgets
2. Guardrails – Input/output validation and PII detection
3. Self-Healing – Automatic error recovery
4. Evals – Quality measurement in CI
5. OpenTelemetry – Production observability

Advanced Path

Unlock the full power of the system:

1. Pattern Checkpoints – Save/resume, fork, progress tracking
2. Goal Pattern – Desired-state resolution with satisfaction scoring and relaxation
3. Communication – Decentralized agent messaging
4. Cross-Agent State – Shared derivations and scratchpad
5. Breakpoints & Checkpoints – Human-in-the-loop debugging
6. DevTools – Real-time visual debugging (Timeline, Cost, State + 5 more planned)

Two Orchestrators

Both are backed by a Directive System with reactive state, constraints, guardrails, streaming, approval, memory, retry, budget, hooks, and time-travel debugging. The multi-agent orchestrator has full feature parity – each registered agent becomes a namespaced Directive module.

// Single-agent
const single = createAgentOrchestrator({ runner, guardrails, maxTokenBudget: 10000 });
const result = await single.run(agent, 'Hello!');

// Multi-agent
const multi = createMultiAgentOrchestrator({
  runner,
  agents: { researcher: { agent: researcher }, writer: { agent: writer } },
  guardrails,
  maxTokenBudget: 50000,
});
const result = await multi.runAgent('researcher', 'What is WASM?');

Key Concepts

Quick Example

import { createAgentOrchestrator, createPIIGuardrail } from '@directive-run/ai';
import { createOpenAIRunner } from '@directive-run/ai/openai';

const runner = createOpenAIRunner({
  apiKey: process.env.OPENAI_API_KEY!,
});

const agent = {
  name: 'assistant',
  instructions: 'You are a helpful assistant.',
};

const orchestrator = createAgentOrchestrator({
  runner,

  // Block PII in user input
  guardrails: {
    input: [createPIIGuardrail()],
  },

  // Auto-enforce a 10K token budget
  maxTokenBudget: 10000,

  // React to agent state with declarative rules
  constraints: {
    escalateOnLowConfidence: {
      when: (facts) => facts.agent.output?.confidence < 0.7,
      require: (facts) => ({
        type: 'RUN_EXPERT_AGENT',
        query: facts.agent.input,
      }),
    },
  },
});

const result = await orchestrator.run(agent, 'Hello!');

Infrastructure

Observability

Safety & Compliance

Directive provides security guardrails and compliance tooling for AI agent systems. See Security & Compliance for full details.

Next Steps

• New to AI adapter? Start with Running Agents
• Need resilience? See Resilience & Routing
• Want streaming? See Streaming
• Need safety? See Guardrails and Security & Compliance
• Production debugging? See DevTools and Evals