@breadstone/archipel-mcp 0.0.54 → 0.0.56

package/data/guides/ai-text-generation.md

@@ -1,687 +1,150 @@
 ---
-title: AI Text Generation
-description: Generate text completions with multi-provider support for OpenAI, Anthropic, Google Gemini, and Grok using a unified configuration layer.
+title: AI Language Generation
+description: Generate text and structured output, stream results, use tools, and create agents without leaking provider SDKs.
 order: 15
 ---
 
-# AI Text Generation
+# AI Language Generation
 
-This guide covers text generation with `platform-intelligence`: choosing an AI provider, configuring the module, generating completions, streaming responses, and registering class-based or provider-native AI SDK tools.
+`IntelligenceLanguageGenerator` is the provider-neutral language facade. It
+owns plain text, schema-constrained objects, streaming, tool execution, result
+normalization, retries, cancellation, and timeouts.
 
-For versioned feature prompts with typed inputs, structured output schemas,
-execution policy, and a NestJS executor, start with
-[Intelligence Prompts Warm-up](./intelligence-prompts-warm-up).
-
-For server-owned, bidirectional audio and text connections, use the separate
-[AI Realtime Voice](./ai-realtime-voice) guide. Realtime sessions have a
-different transport, lifecycle, persistence, and metering model from request-
-or response-scoped text generation.
-
----
-
-## Installation
+Consumer applications depend only on Archipel:
 
 ```bash
 yarn add @breadstone/archipel-platform-intelligence
 ```
 
-Install the AI SDK provider package for the model you want to use:
-
-| Provider       | Package             |
-| -------------- | ------------------- |
-| **OpenAI**     | `@ai-sdk/openai`    |
-| **Anthropic**  | `@ai-sdk/anthropic` |
-| **Google**     | `@ai-sdk/google`    |
-| **Grok (xAI)** | `@ai-sdk/xai`       |
-
-```bash
-# Example: OpenAI
-yarn add @ai-sdk/openai
-
-# Example: Grok / xAI
-yarn add @ai-sdk/xai
-```
-
----
-
-## Module Registration
-
-Import `IntelligenceModule` into your application module. It exposes `IntelligenceTextGenerator` and `IntelligenceToolRegistry` as shared providers.
+## Registration
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
-import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
+import { IntelligenceCapabilityNames, IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
+import { ANTHROPIC_CONFIG_ENTRIES, AnthropicIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/anthropic';
+import { OPENAI_CONFIG_ENTRIES, OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/openai';
 
 @Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-Register only the provider loaders you install. The root entry does not import provider SDK packages.
-
----
-
-## Configuration
-
-All intelligence settings are read from environment variables via `ConfigService`. No direct `process.env` access is needed.
-
-```dotenv
-INTELLIGENCE_PROVIDER=openai
-INTELLIGENCE_MODEL=gpt-4o-mini
-INTELLIGENCE_API_KEY=sk-...
-INTELLIGENCE_TEMPERATURE=0.7
-INTELLIGENCE_TOP_P=1
-INTELLIGENCE_MAX_OUTPUT_TOKENS=1024
-INTELLIGENCE_BASE_URL=              # optional — override for custom endpoints
-```
-
-### Supported Providers
-
-| `INTELLIGENCE_PROVIDER` | Default model              | Notes                              |
-| ----------------------- | -------------------------- | ---------------------------------- |
-| `openai`                | `gpt-4o-mini`              | OpenAI API                         |
-| `anthropic`             | `claude-sonnet-4-20250514` | Anthropic API                      |
-| `google`                | `gemini-2.0-flash`         | Google Gemini API                  |
-| `grok`                  | `grok-3-mini`              | xAI Grok API                       |
-
-Each provider resolves its API key and base URL from dedicated environment variables when the generic `INTELLIGENCE_API_KEY` is not set:
-
-```dotenv
-# Provider-specific keys (optional — fallback from INTELLIGENCE_API_KEY)
-OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
-GOOGLE_API_KEY=AI...
-GROK_API_KEY=xai-...
-```
-
----
-
-## Generating Text
-
-Inject `IntelligenceTextGenerator` to generate completions:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import type { Prompt } from 'ai';
-import { IntelligenceTextGenerator, type IIntelligenceTextCompletion } from '@breadstone/archipel-platform-intelligence';
-
-@Injectable()
-export class SummaryService {
-  private readonly _textGenerator: IntelligenceTextGenerator;
-
-  constructor(textGenerator: IntelligenceTextGenerator) {
-    this._textGenerator = textGenerator;
-  }
-
-  public async summarize(content: string): Promise<string> {
-    const prompt: Prompt = {
-      system: 'You are a concise summarizer. Respond with a short summary.',
-      messages: [{ role: 'user', content: content }],
-    };
-
-    const completion = await this._textGenerator.generateText(prompt);
-
-    return completion.text;
-  }
-}
-```
-
-### Prompt Structure
-
-A prompt uses the native AI SDK `Prompt` type. Use either a string prompt or a full message array:
-
-```typescript
-type Prompt =
-  | { readonly system?: string; readonly prompt: string }
-  | { readonly system?: string; readonly messages: Array<ModelMessage> };
-```
-
-### Per-Request Overrides
-
-Override generation parameters for individual requests without changing the global configuration:
-
-```typescript
-const completion = await this._textGenerator.generateText(prompt, {
-  temperature: 0.2, // more deterministic
-  maxOutputTokens: 256, // shorter responses
-});
-```
-
-### Completion Response
-
-The response includes the generated text, the provider/model used, provider-native sources, generated files, and optional token usage telemetry:
-
-```typescript
-interface IIntelligenceTextCompletion {
-  readonly text: string;
-  readonly provider: string;
-  readonly model: string;
-  readonly sources: ReadonlyArray<LanguageModelV3Source>;
-  readonly files: ReadonlyArray<GeneratedFile>;
-  readonly usage: IIntelligenceCompletionUsage | null;
-}
-
-interface IIntelligenceCompletionUsage {
-  readonly promptTokens: number | null;
-  readonly completionTokens: number | null;
-  readonly totalTokens: number | null;
-}
-```
-
----
-
-## Multi-Turn Conversations
-
-Build multi-turn conversations by passing the full message history:
-
-```typescript
-const prompt: Prompt = {
-  system: 'You are a helpful fitness coach.',
-  messages: [
-    { role: 'user', content: 'What should I eat before a workout?' },
-    { role: 'assistant', content: 'A balanced meal with carbs and protein about 2 hours before.' },
-    { role: 'user', content: 'Can you give me a specific example?' },
-  ],
-};
-
-const completion = await this._textGenerator.generateText(prompt);
-```
-
----
-
-## Tool Registration
-
-The intelligence module uses native AI SDK tools. Define a class that exposes a `name` and a native `Tool`, or register provider-native tool wrappers from provider subpaths.
-
-```typescript
-import { Injectable, Module } from '@nestjs/common';
-import { tool, type Tool } from 'ai';
-import { z } from 'zod';
-import { IntelligenceModule, IntelligenceProviderNames, IntelligenceToolBase } from '@breadstone/archipel-platform-intelligence';
-import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-
-interface IWorkoutInput {
-  readonly goal: string;
-}
-
-interface IWorkoutOutput {
-  readonly recommendation: string;
-}
-
-@Injectable()
-export class WorkoutRecommendationTool extends IntelligenceToolBase<IWorkoutInput, IWorkoutOutput> {
-  public override get name(): string {
-    return 'recommendWorkout';
-  }
-
-  public override get tool(): Tool<IWorkoutInput, IWorkoutOutput> {
-    return tool({
-      description: 'Recommends a workout plan for a user goal.',
-      inputSchema: z.object({
-        goal: z.string().describe('The user fitness goal'),
-      }),
-      execute: async (input) => ({
-        recommendation: `Workout plan for ${input.goal}`,
-      }),
-    });
-  }
-}
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-      tools: [WorkoutRecommendationTool],
-    }),
-  ],
+    imports: [
+        IntelligenceModule.register({
+            configEntries: [...OPENAI_CONFIG_ENTRIES, ...ANTHROPIC_CONFIG_ENTRIES],
+            providerAdapters: [OpenAIIntelligenceProviderAdapter, AnthropicIntelligenceProviderAdapter],
+            defaultModels: {
+                [IntelligenceCapabilityNames.Language]: {
+                    provider: IntelligenceProviderNames.OpenAI,
+                    model: 'gpt-5.4-mini',
+                },
+            },
+        }),
+    ],
 })
-export class WorkoutModule {}
+export class ApplicationModule {}
 ```
 
-Provider-defined AI SDK tools are available through tree-shakable provider subpaths. They return `IIntelligenceTool` instances and can be placed directly in the `tools` array:
+## Text and Objects
 
 ```typescript
-import { Module } from '@nestjs/common';
-import { IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
-import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-import { createOpenAIWebSearchTool } from '@breadstone/archipel-platform-intelligence/providers/openai/tools';
+const completion = await language.generateText(
+    {
+        system: 'Answer using the supplied application context only.',
+        prompt: 'Summarize the open tasks.',
+    },
+    {
+        maxOutputTokens: 800,
+        maxRetries: 2,
+    },
+);
 
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-      tools: [createOpenAIWebSearchTool({ searchContextSize: 'medium' })],
+const structured = await language.generateObject(
+    { prompt: 'Classify the customer request.' },
+    z.object({
+        category: z.enum(['billing', 'technical', 'other']),
+        urgency: z.enum(['low', 'normal', 'high']),
     }),
-  ],
-})
-export class SearchModule {}
+);
 ```
 
-OpenAI, Google, Anthropic, and Grok provider subpaths expose wrappers for their built-in web search, file search, code execution, URL context, shell, MCP, X search, image/video understanding, and versioned tool families where supported by the underlying SDK.
-
-### Native AI SDK Passthrough
-
-Archipel is not intended to be a closed subset of the AI SDK. `IntelligenceTextGenerator.generateText()` and `streamText()` accept native AI SDK `Prompt` objects directly. Their options extend the native AI SDK call options, while Archipel still contributes provider configuration, registered tool merging, timeout defaults, logging, and normalized completion metadata.
+Applications can provide a model override as
+`{ provider: string, model: string }`. They never construct a provider-native
+model.
 
-Use the native AI SDK prompt shape for prompt strings, multimodal `ModelMessage` arrays, system-message arrays, or other prompt forms supported by the AI SDK.
+## Streaming
 
 ```typescript
-import { openai } from '@ai-sdk/openai';
-import { Injectable, Module } from '@nestjs/common';
-import { IntelligenceModule, IntelligenceTextGenerator, type IIntelligenceTextCompletion } from '@breadstone/archipel-platform-intelligence';
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      validateOnModuleInit: false,
-    }),
-  ],
-})
-export class RawAiSdkModule {}
-
-@Injectable()
-export class RawAiSdkRecipeService {
-  private readonly _textGenerator: IntelligenceTextGenerator;
+const stream = await language.streamText({ prompt: 'Explain the result.' });
 
-  public constructor(textGenerator: IntelligenceTextGenerator) {
-    this._textGenerator = textGenerator;
-  }
-
-  public async generateWithNativeAiSdkOptions(): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        system: 'Answer concisely and include assumptions.',
-        prompt: 'Compare the operational risks of outdoor work tomorrow.',
-      },
-      {
-        model: openai.responses('gpt-5'),
-        headers: { 'x-use-case': 'outdoor-risk' },
-        providerOptions: {
-          openai: {
-            reasoningEffort: 'medium',
-          },
-        },
-        seed: 42,
-      },
-    );
-  }
+for await (const delta of stream.textStream) {
+    sendToAuthenticatedClient(delta);
 }
-```
-
-If every request passes a native AI SDK model, `validateOnModuleInit: false` avoids requiring platform provider configuration at startup. If no `model` option is supplied, the configured provider loader and `INTELLIGENCE_PROVIDER` / `INTELLIGENCE_MODEL` values still define the model.
-
-### Additional OpenAI Tool Recipes
-
-The same pattern works for other provider-defined OpenAI tools. Register the provider tool wrapper on the module when it is available to the whole use case, or pass request-specific tools through `generateText()` when the tool needs request data such as a `fileId`.
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { stepCountIs, tool } from 'ai';
-import { z } from 'zod';
-import { IntelligenceTextGenerator } from '@breadstone/archipel-platform-intelligence';
-import { OpenAIIntelligenceToolNames } from '@breadstone/archipel-platform-intelligence/providers/openai';
-import {
-  createOpenAICodeInterpreterTool,
-  createOpenAICustomTool,
-  createOpenAIImageGenerationTool,
-  createOpenAIToolSearchTool,
-} from '@breadstone/archipel-platform-intelligence/providers/openai/tools';
-
-@Injectable()
-export class OpenAIToolRecipeService {
-  private readonly _textGenerator: IntelligenceTextGenerator;
-
-  public constructor(textGenerator: IntelligenceTextGenerator) {
-    this._textGenerator = textGenerator;
-  }
-
-  public async analyseSpreadsheet(fileId: string): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        system: 'You analyze uploaded spreadsheets and explain unusual values clearly.',
-        messages: [
-          {
-            role: 'user',
-            content: 'Analyze the file, detect unusual values, and summarize the most important findings as a table.',
-          },
-        ],
-      },
-      {
-        activeTools: [OpenAIIntelligenceToolNames.CodeInterpreter],
-        tools: {
-          [OpenAIIntelligenceToolNames.CodeInterpreter]: createOpenAICodeInterpreterTool({
-            container: { fileIds: [fileId] },
-          }).tool,
-        },
-      },
-    );
-  }
-
-  public async generateIllustration(description: string): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        prompt: description,
-      },
-      {
-        activeTools: [OpenAIIntelligenceToolNames.ImageGeneration],
-        tools: {
-          [OpenAIIntelligenceToolNames.ImageGeneration]: createOpenAIImageGenerationTool({
-            quality: 'medium',
-            size: '1024x1024',
-          }).tool,
-        },
-      },
-    );
-  }
 
-  public async answerWithDeferredTools(prompt: string): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        prompt: prompt,
-      },
-      {
-        stopWhen: stepCountIs(10),
-        tools: {
-          [OpenAIIntelligenceToolNames.ToolSearch]: createOpenAIToolSearchTool().tool,
-          get_birthdays: tool({
-            description: 'Returns employee birthdays in a date range.',
-            inputSchema: z.object({
-              from: z.string(),
-              to: z.string(),
-            }),
-            execute: async (input) => ({ from: input.from, to: input.to, employees: [] }),
-            providerOptions: {
-              openai: { deferLoading: true },
-            },
-          }),
-          search_orders: tool({
-            description: 'Searches orders using domain-specific filters.',
-            inputSchema: z.object({
-              query: z.string(),
-            }),
-            execute: async (input) => ({ query: input.query, orders: [] }),
-            providerOptions: {
-              openai: { deferLoading: true },
-            },
-          }),
-        },
-      },
-    );
-  }
-
-  public async createReadOnlyReportQuery(prompt: string): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        system: 'Create only read-only reporting queries. The query must start with SELECT.',
-        messages: [{ role: 'user', content: prompt }],
-      },
-      {
-        toolChoice: 'required',
-        stopWhen: stepCountIs(3),
-        activeTools: ['report_query'],
-        tools: {
-          report_query: createOpenAICustomTool({
-            name: 'report_query',
-            description: 'Create a strictly read-only reporting query.',
-            format: {
-              type: 'grammar',
-              syntax: 'regex',
-              definition: 'SELECT .+',
-            },
-          }).tool,
-        },
-      },
-    );
-  }
-}
+const finalText = await stream.text;
+const usage = await stream.usage;
 ```
 
-`generateIllustration()` can return generated images through `completion.files`, while web search results are exposed through `completion.sources`. The platform keeps the AI SDK tool objects intact, so provider-specific options such as `container.fileIds`, `deferLoading`, grammar formats, and image settings still pass through to OpenAI. With the currently installed OpenAI SDK, `customTool()` supports grammar-constrained provider output but not a local `execute` callback; run parser, allowlist, and tenant filtering before executing any generated query, or model that execution as a normal `tool()` when local execution is required.
-
-### Outdoor Order Weather Risk Example
+`streamObject()` exposes partial structured output and a validated final object.
+All stream iterables and result promises normalize provider failures as
+`IntelligenceProviderError`.
 
-This is the Archipel equivalent of using one application tool together with OpenAI web search. The model is selected through configuration, for example `INTELLIGENCE_PROVIDER=openai` and `INTELLIGENCE_MODEL=gpt-5`; the use case only depends on `IntelligenceTextGenerator`.
+## Application Tools
 
 ```typescript
-import { Injectable, Module } from '@nestjs/common';
-import { stepCountIs, tool, type Tool } from 'ai';
-import { z } from 'zod';
-import {
-  IntelligenceModule,
-  IntelligenceProviderNames,
-  IntelligenceTextGenerator,
-  IntelligenceToolBase,
-  type IIntelligenceTextCompletion,
-} from '@breadstone/archipel-platform-intelligence';
-import { OpenAIIntelligenceToolNames, loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-import { createOpenAIWebSearchTool } from '@breadstone/archipel-platform-intelligence/providers/openai/tools';
-
-interface IOutdoorOrderLookupInput {
-  readonly date: string;
-}
-
-interface IOutdoorOrder {
-  readonly id: string;
-  readonly location: string;
-  readonly scheduledAt: string;
-  readonly outdoorWork: boolean;
-}
-
-interface IOutdoorOrderLookupOutput {
-  readonly date: string;
-  readonly orders: ReadonlyArray<IOutdoorOrder>;
-}
-
-@Injectable()
-export class OutdoorOrdersTool extends IntelligenceToolBase<IOutdoorOrderLookupInput, IOutdoorOrderLookupOutput> {
-  public override get name(): string {
-    return 'get_outdoor_orders';
-  }
-
-  public override get tool(): Tool<IOutdoorOrderLookupInput, IOutdoorOrderLookupOutput> {
-    return tool({
-      description: 'Returns outdoor field orders for the current tenant and date.',
-      inputSchema: z.object({
-        date: z.string().describe('Date in YYYY-MM-DD format'),
-      }),
-      execute: async (input: IOutdoorOrderLookupInput) => this.loadOutdoorOrders(input.date),
-    });
-  }
-
-  private async loadOutdoorOrders(date: string): Promise<IOutdoorOrderLookupOutput> {
-    return {
-      date: date,
-      orders: [
-        {
-          id: 'ord_4711',
-          location: 'Berlin',
-          scheduledAt: `${date}T08:00:00+02:00`,
-          outdoorWork: true,
-        },
-      ],
-    };
-  }
-}
-
-@Injectable()
-export class OutdoorOrderRiskAnalysisService {
-  private readonly _textGenerator: IntelligenceTextGenerator;
-
-  public constructor(textGenerator: IntelligenceTextGenerator) {
-    this._textGenerator = textGenerator;
-  }
-
-  public async analyseOutdoorOrders(date: string): Promise<{ readonly text: string; readonly sources: IIntelligenceTextCompletion['sources'] }> {
-    const result = await this._textGenerator.generateText(
-      {
-        system: 'You assess weather-related risks for tenant outdoor field orders.',
-        messages: [
-          {
-            role: 'user',
-            content: `Review outdoor field orders for ${date} and flag weather-related risks.`,
-          },
-        ],
-      },
-      {
-        toolChoice: 'auto',
-        activeTools: ['get_outdoor_orders', OpenAIIntelligenceToolNames.WebSearch],
-        stopWhen: stepCountIs(3),
-      },
-    );
+export class CustomerSearchTool extends IntelligenceToolBase<ICustomerSearchInput, ReadonlyArray<ICustomerSummary>> {
+    public override get name(): string {
+        return 'customer_search';
+    }
 
-    return {
-      text: result.text,
-      sources: result.sources,
-    };
-  }
+    public override get tool() {
+        return defineIntelligenceTool({
+            description: 'Searches customers visible to the authenticated tenant.',
+            inputSchema: createIntelligenceJsonSchema<ICustomerSearchInput>({
+                type: 'object',
+                properties: { query: { type: 'string' } },
+                required: ['query'],
+                additionalProperties: false,
+            }),
+            execute: async ({ query }) => this._customers.search(query),
+        });
+    }
 }
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-      tools: [
-        OutdoorOrdersTool,
-        createOpenAIWebSearchTool({
-          externalWebAccess: true,
-          searchContextSize: 'medium',
-          filters: {
-            allowedDomains: ['dwd.de'],
-          },
-        }),
-      ],
-    }),
-  ],
-  providers: [OutdoorOrderRiskAnalysisService],
-})
-export class OutdoorOrderRiskAnalysisModule {}
-```
-
-Use AI SDK request options to constrain tool use per call:
-
-```typescript
-const completion = await this._textGenerator.generateText(prompt, {
-  toolChoice: 'auto',
-  activeTools: ['recommendWorkout'],
-});
-```
-
-> **Capacity limit:** The registry enforces a maximum of **128** registered tools.
-
----
-
-## Streaming Text
-
-`streamText()` uses the same provider configuration and registered tools as `generateText()` and returns the native AI SDK stream result.
-
-```typescript
-const stream = await this._textGenerator.streamText(prompt, {
-  activeTools: ['recommendWorkout'],
-  stopWhen: stepCountIs(3),
-});
-
-return stream.toUIMessageStreamResponse();
 ```
 
----
-
-## Inspecting Configuration
-
-Retrieve the resolved provider configuration at runtime:
-
-```typescript
-const config = this._textGenerator.getConfiguration();
-console.log(config.provider); // 'openai'
-console.log(config.model); // 'gpt-4o-mini'
-```
-
----
-
-## Error Handling
-
-`IntelligenceTextGenerator` wraps all provider errors in `IntelligenceProviderError`, which includes `provider`, `model`, and `retryable` metadata. The generator automatically retries retryable failures (e.g. transient network errors) with exponential backoff before giving up.
-
-Two additional error classes handle configuration and validation failures:
+Register tools through `IntelligenceModule.register({ tools: [...] })`. Use
+`activeToolNames` to constrain a call and `maxSteps` to bound the tool loop.
+Tool authorization remains application-owned and must fail closed before data
+or side effects are exposed.
 
-| Error class                        | Code                          | When thrown                                                           |
-| ---------------------------------- | ----------------------------- | --------------------------------------------------------------------- |
-| `IntelligenceProviderError`        | `INTELLIGENCE_PROVIDER`       | Provider SDK failures during text generation                          |
-| `IntelligenceValidationError`      | `INTELLIGENCE_VALIDATION`     | Invalid generation parameters (temperature, topP, maxOutputTokens)    |
-| `IntelligenceConfigurationError`   | `INTELLIGENCE_CONFIGURATION`  | Unsupported provider, missing API key, or missing provider loader     |
+Provider-owned tools are imported from Archipel provider `/tools` subpaths.
+They are represented by opaque Archipel definitions; their native SDK types do
+not cross into the application.
 
-### Timeout & Retry Defaults
+## Agents
 
-| Setting     | Default  | Description                                                 |
-| ----------- | -------- | ----------------------------------------------------------- |
-| `timeoutMs` | `30000`  | Abort the provider request after this many milliseconds     |
-| Max retries | `2`      | Retryable errors are retried up to 2 times                  |
-| Backoff     | 1s → 4s  | Exponential backoff with a 4-second cap between retries     |
-
-Override the timeout per call:
+`IntelligenceAgentFactory.create()` builds a reusable bounded agent on the same
+language facade:
 
 ```typescript
-const result = await this._textGenerator.generateText(prompt, {
-  timeoutMs: 15_000, // 15-second timeout for this call
+const agent = agents.create({
+    name: 'researcher',
+    instructions: 'Use approved sources and report uncertainty.',
+    activeToolNames: ['web_search', 'document_search'],
+    maxSteps: 6,
 });
-```
-
-### Catching Errors
-
-```typescript
-import { IntelligenceProviderError } from '@breadstone/archipel-platform-intelligence';
 
-try {
-  const result = await this._textGenerator.generateText(prompt);
-  return result.text;
-} catch (error) {
-  if (error instanceof IntelligenceProviderError) {
-    this._logger.error(`Provider ${error.provider}/${error.model} failed`, {
-      retryable: error.retryable,
-      message: error.message,
-    });
-  }
-  return 'Sorry, I could not generate a response right now.';
-}
+const answer = await agent.generate({ prompt: question });
 ```
 
-If no loader is registered for the configured provider, startup fails with a clear configuration error. If a provider subpath is imported without its AI SDK peer package installed, the application fails at that import boundary instead of pulling the provider through the root package.
-
----
+Agents do not create a second provider abstraction. They compose language,
+tools, model policy, and step limits already owned by Archipel.
 
-## Architecture Overview
+## Results and Failures
 
-```mermaid
-flowchart TB
-  subgraph IntelligenceModule[IntelligenceModule]
-    TextGenerator[IntelligenceTextGenerator\nConfigService -> provider]
-    ToolRegistry[IntelligenceToolRegistry]
-  end
+Language completions expose provider, model, text, typed output, finish reason,
+reasoning text, normalized sources and files, tool calls/results, warnings, and
+usage. Usage contains provider-neutral input, output, total, cache-read,
+cache-write, reasoning, and available modality counters. A `null` counter means
+the provider did not report it and must not be interpreted as measured zero.
+The default total-operation timeout is 30 seconds.
 
-  GenerateText["generateText(prompt, options?)"]
-  StreamText["streamText(prompt, options?)"]
-  ResolveTools["toToolSet()\nregister(tool)"]
-  ProviderLoaders[Registered Provider Loaders\nproviders/openai, providers/anthropic, providers/google, providers/grok]
-  FeatureTools[Feature Tools\nnative AI SDK tools]
-
-  TextGenerator --> GenerateText
-  TextGenerator --> StreamText
-  ToolRegistry --> ResolveTools
-  TextGenerator --> ProviderLoaders
-  ToolRegistry --> FeatureTools
-  GenerateText --> ToolRegistry
-  StreamText --> ToolRegistry
-```
+Provider failures use `IntelligenceProviderError`; invalid prompts and options
+use `IntelligenceValidationError`; missing adapters or capability defaults use
+`IntelligenceConfigurationError`.