building-ai-agents

name	building-ai-agents
description	Configure AI provider runners (Anthropic, OpenAI, Ollama), stream tokens and structured output, and wire cross-agent communication. Use when setting up LLM provider connections, implementing token streaming, choosing between providers, or building agents that communicate results to each other.

Building AI Agents

Prerequisites

This skill applies when the project uses @directive-run/ai. If not found in package.json, suggest installing it: npm install @directive-run/ai.

When Claude Should Use This Skill

Auto-Invoke Triggers

• User asks which LLM provider to use or how to set one up
• User wants to stream tokens or handle streaming responses
• User mentions createAnthropicRunner, createOpenAIRunner, createOllamaRunner
• User asks how agents share data or pass results between each other
• User needs to switch providers or implement a provider abstraction

Exclusions

• Do NOT invoke for orchestrator structure (constraints/resolvers) – use building-ai-orchestrators
• Do NOT invoke for rate limits, budgets, or guardrails – use hardening-ai-systems
• Do NOT invoke for testing runners – use testing-ai-systems

---

Quick Reference

Decision Tree: Which Runner?

Choosing a provider?
├── Production, best quality → createAnthropicRunner (claude-opus-4-6)
├── Production, cost-efficient → createAnthropicRunner (claude-haiku-4-5)
├── OpenAI ecosystem / GPT models → createOpenAIRunner
├── Local / private / no API key → createOllamaRunner
└── Custom provider → implement AgentRunner interface

Decision Tree: Streaming vs Non-Streaming?

Need the response immediately as it arrives?
├── Yes, show tokens as they generate → runStream() + "token" events
├── Yes, but structured JSON → runStream() + "structured" events
└── No, wait for full response → run()

---

Provider Runners

Anthropic

import { createAnthropicRunner } from "@directive-run/ai/anthropic";

const runner = createAnthropicRunner({
  model: "claude-opus-4-6",           // or "claude-haiku-4-5", "claude-sonnet-4-6"
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxTokens: 4096,                    // optional, default: 1024
  temperature: 0.7,                   // optional, default: 1.0
  systemPrompt: "You are helpful.",   // optional default system prompt
});

OpenAI

import { createOpenAIRunner } from "@directive-run/ai/openai";

const runner = createOpenAIRunner({
  model: "gpt-4o",                    // or "gpt-4o-mini", "gpt-3.5-turbo"
  apiKey: process.env.OPENAI_API_KEY,
  maxTokens: 4096,
  temperature: 0.7,
  organization: "org-...",            // optional
});

Ollama (Local)

import { createOllamaRunner } from "@directive-run/ai/ollama";

const runner = createOllamaRunner({
  model: "llama3.2",                  // any Ollama-installed model
  baseUrl: "http://localhost:11434",  // default Ollama endpoint
  temperature: 0.8,
});

---

Running LLM Calls Inside Resolvers

resolvers: {
  generate: {
    requirement: "GENERATE",
    resolve: async (req, context) => {
      // Basic call – returns full response when complete
      const result = await context.runner.run({
        prompt: "Explain quantum entanglement simply.",
        system: "You are a science communicator.",
        maxTokens: 500,
      });

      context.facts.output = result.text;
      context.facts.tokenUsage = result.usage.totalTokens;
    },
  },
},

Runner Result Shape

interface RunnerResult {
  text: string;           // Generated text
  usage: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
  };
  model: string;          // Model used
  stopReason: "end_turn" | "max_tokens" | "stop_sequence";
  raw: unknown;           // Raw provider response
}

---

Streaming

Token Streaming

// orchestrator.runStream() returns AsyncIterable<OrchestratorEvent>
const stream = orchestrator.runStream({ input: "Write a story about..." });

for await (const event of stream) {
  if (event.type === "token") {
    // Arrives as the LLM generates – display immediately
    process.stdout.write(event.text);
  }

  if (event.type === "done") {
    console.log("\nFinal facts:", event.facts);
  }

  if (event.type === "error") {
    console.error("Stream error:", event.error.message);
    break;
  }
}

All Stream Event Types

type OrchestratorEvent =
  | { type: "token"; text: string; agentId?: string }
  | { type: "requirement_met"; requirementType: string; agentId?: string }
  | { type: "requirement_queued"; requirementType: string }
  | { type: "agent_started"; agentId: string }
  | { type: "agent_done"; agentId: string }
  | { type: "done"; facts: Record<string, unknown> }
  | { type: "error"; error: Error };

Structured Output Streaming

import { z } from "zod";

// When you need typed JSON output, not raw text
const result = await context.runner.runStructured({
  prompt: "Extract product info from this description: ...",
  schema: z.object({
    name: z.string(),
    price: z.number(),
    inStock: z.boolean(),
  }),
});

// result.data is typed to the schema
context.facts.productName = result.data.name;
context.facts.price = result.data.price;

Emitting Custom Stream Events from Resolvers

resolve: async (req, context) => {
  // Emit custom events consumers can observe
  context.emit({ type: "token", text: "Starting analysis..." });

  const result = await context.runner.run({ prompt: req.input });

  context.emit({ type: "token", text: result.text });
  context.facts.output = result.text;
},

---

Cross-Agent Communication

Via Coordinator Facts (Recommended)

In createMultiAgentOrchestrator, agents share coordinator facts. The coordinator acts as the message bus.

// researcher agent writes to coordinator facts
resolve: async (req, context) => {
  const result = await context.runner.run({ prompt: "Research AI trends..." });
  // Writing to shared coordinator facts signals the next agent
  context.facts.researchComplete = true;
  context.facts.researchNotes = result.text;
},

// writer agent reads coordinator facts set by researcher
constraints: {
  startWriting: {
    // Only activates after researcher signals completion
    when: (facts) => facts.researchComplete && !!facts.researchNotes,
    require: { type: "WRITE_ARTICLE" },
  },
},

Via Requirement Payload

// Pass structured data in the requirement itself
constraints: {
  routeToSpecialist: {
    when: (facts) => facts.analysisType === "legal",
    require: (facts) => ({
      type: "SPECIALIST_REVIEW",
      category: facts.analysisType,
      priority: facts.urgency,
      content: facts.draftOutput,
    }),
  },
},

resolvers: {
  specialistReview: {
    requirement: "SPECIALIST_REVIEW",
    resolve: async (req, context) => {
      // req contains { category, priority, content } from above
      const result = await context.runner.run({
        prompt: `Review this ${req.category} content: ${req.content}`,
      });
      context.facts.reviewedOutput = result.text;
    },
  },
},

---

Custom Provider – Implement AgentRunner Interface

import type { AgentRunner, RunOptions, RunnerResult } from "@directive-run/ai";

class MyCustomRunner implements AgentRunner {
  async run(options: RunOptions): Promise<RunnerResult> {
    // Call your provider
    const response = await myProviderClient.generate({
      prompt: options.prompt,
      system: options.system,
    });

    return {
      text: response.text,
      usage: {
        inputTokens: response.usage.input,
        outputTokens: response.usage.output,
        totalTokens: response.usage.total,
      },
      model: "my-custom-model",
      stopReason: "end_turn",
      raw: response,
    };
  }

  // Optional: implement for streaming support
  async *runStream(options: RunOptions): AsyncIterable<string> {
    for await (const chunk of myProviderClient.stream(options)) {
      yield chunk.text;
    }
  }
}

---

Multi-Turn Conversations

// Maintain conversation history in facts
factsSchema: {
  messages: t.array(t.object<{ role: "user" | "assistant"; content: string }>()),
  latestInput: t.string(),
  latestOutput: t.string().optional(),
},

init: (facts) => {
  facts.messages = [];
},

resolve: async (req, context) => {
  // Add user message to history
  context.facts.messages.push({
    role: "user",
    content: context.facts.latestInput,
  });

  const result = await context.runner.run({
    messages: context.facts.messages,  // Pass full history
    system: "You are a helpful assistant.",
  });

  // Add assistant reply to history
  context.facts.messages.push({
    role: "assistant",
    content: result.text,
  });

  context.facts.latestOutput = result.text;
},

---

Critical Anti-Patterns

Not handling stream errors

// WRONG – if stream throws, it crashes uncaught
for await (const event of orchestrator.runStream(input)) {
  if (event.type === "token") {
    process.stdout.write(event.text);
  }
}

// CORRECT – always handle error events
for await (const event of orchestrator.runStream(input)) {
  if (event.type === "token") {
    process.stdout.write(event.text);
  }

  if (event.type === "error") {
    console.error("Stream failed:", event.error.message);
    break;
  }
}

Blocking on stream consumption inside a resolver

// WRONG – consuming a stream inside a resolver blocks the engine
resolve: async (req, context) => {
  const stream = orchestrator.runStream(req.input);
  for await (const event of stream) { /* deadlock risk */ }
},

// CORRECT – use context.runner.run() inside resolvers
resolve: async (req, context) => {
  const result = await context.runner.run({ prompt: req.input });
  context.facts.output = result.text;
},

Resolver parameter naming

Always use (req, context) – never (req, ctx) or (request, context).

Hardcoding API keys

// WRONG
const runner = createAnthropicRunner({ apiKey: "sk-ant-..." });

// CORRECT
const runner = createAnthropicRunner({ apiKey: process.env.ANTHROPIC_API_KEY });

Ignoring token usage

// WRONG – fire and forget, no budget awareness
const result = await context.runner.run({ prompt });
context.facts.output = result.text;

// CORRECT – track usage for budget management
const result = await context.runner.run({ prompt });
context.facts.output = result.text;
context.facts.tokensUsed = (context.facts.tokensUsed ?? 0) + result.usage.totalTokens;

---

Reference Files

• ai-agents-streaming.md – Streaming events, AsyncIterable patterns, token buffering
• ai-adapters.md – Provider adapter interface, all runner options, custom runner guide
• ai-communication.md – Cross-agent communication, coordinator facts, requirement payloads