Unified Provider Protocol

https://providerprotocol.org
Admin
Unified Provider Protocol provides uniform interfaces for interacting with LLMs, embeddings, and...
Tokens:274,917
Snippets:2,125
Trust Score:1.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Provider Protocol AI Library

Source: https://providerprotocol.org/guide/quick-start

Install the Unified Provider Protocol AI library using your preferred package manager. This command adds the necessary package to your project's dependencies.

```bash
npm install @providerprotocol/ai
```

```bash
pnpm add @providerprotocol/ai
```

```bash
bun add @providerprotocol/ai
```

--------------------------------

### Install Provider Protocol AI SDK

Source: https://providerprotocol.org/introduction

Installs the Provider Protocol AI SDK using either Bun or npm. This is the first step to integrating the SDK into your project.

```bash
bun add @providerprotocol/ai
# or
npm install @providerprotocol/ai
```

--------------------------------

### Generate Images with Provider Protocol

Source: https://providerprotocol.org/guide/quick-start

Generate images from text prompts using the Provider Protocol. This example demonstrates how to create an image generation client, specify model parameters, and retrieve the image data.

```typescript
import { image, openai } from '@providerprotocol/ai';

const dalle = image({
  model: openai('dall-e-3'),
  params: { size: '1024x1024' },
});

const result = await dalle.generate('A sunset over mountains');
const imageData = result.images[0].image.toBytes();
```

--------------------------------

### Switch LLM Providers with Provider Protocol

Source: https://providerprotocol.org/guide/quick-start

Easily switch between different AI providers by changing the model import and configuration. This example shows how to instantiate LLM clients for OpenAI, Google, and Anthropic models.

```typescript
import { llm, openai, google, anthropic } from '@providerprotocol/ai';

// OpenAI
const gpt = llm({ model: openai('gpt-4o') });

// Google
const gemini = llm({ model: google('gemini-2.0-flash') });

// Anthropic
const claude = llm({ model: anthropic('claude-sonnet-4-20250514') });
```

--------------------------------

### Multiple Provider Import Example

Source: https://providerprotocol.org/introduction

Demonstrates importing and using multiple AI providers within the same application. This allows for flexibility in choosing the best provider for different tasks.

```typescript
import { llm } from '@providerprotocol/ai';
import { anthropic } from '@providerprotocol/ai/anthropic';
import { openai } from '@providerprotocol/ai/openai';

const claude = llm({ model: anthropic('claude-3-opus-20240229') });
const gpt4 = llm({ model: openai('gpt-4-turbo') });
```

--------------------------------

### Examples: Coding Agent

Source: https://providerprotocol.org/agents

Instructions on how to run the provided coding agent example, including command-line arguments for different modes.

```APIDOC
## Examples: Coding Agent

### Description
This section provides instructions on how to run the coding agent example, which demonstrates a Claude Code-style assistant with file operations, bash, search, and sub-agents.

### Running the Example

1. **Basic Usage**: Execute the agent with a specific task.
   ```bash
   ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts "List all TypeScript files"
   ```

2. **Interactive Mode**: Run the agent in an interactive command-line interface.
   ```bash
   ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts -i
   ```

3. **TUI Mode**: Launch the agent with a Text User Interface.
   ```bash
   ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts --tui
   ```

*Note: Replace `sk-...` with your actual Anthropic API key.*
```

--------------------------------

### Minimal Provider Import Example

Source: https://providerprotocol.org/introduction

Illustrates how to perform a minimal import, specifically for the Anthropic provider. This approach helps in reducing bundle size by only including necessary provider code.

```typescript
// Only imports Anthropic provider code, not OpenAI, Google, etc.
```

--------------------------------

### Install @providerprotocol/ai SDK

Source: https://providerprotocol.org/ai

Installs the @providerprotocol/ai SDK using the Bun package manager. This is the initial step to integrate the SDK into your project.

```bash
bun add @providerprotocol/ai
```

--------------------------------

### Multi-Turn Conversations with Provider Protocol

Source: https://providerprotocol.org/guide/quick-start

Maintain conversation history for multi-turn interactions with an LLM. This example demonstrates how to store messages, send them in subsequent calls, and allow the model to remember the context of the conversation.

```typescript
import { llm, anthropic, Message } from '@providerprotocol/ai';

const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
});

const history: Message[] = [];

// First turn
const turn1 = await claude.generate(history, 'My name is Alice.');
history.push(...turn1.messages);

// Second turn - model remembers context
const turn2 = await claude.generate(history, 'What is my name?');
history.push(...turn2.messages);

console.log(turn2.response.text);
// "Your name is Alice."
```

--------------------------------

### Basic LLM Generation with Anthropic

Source: https://providerprotocol.org/introduction

Demonstrates basic LLM text generation using the Anthropic provider. It initializes a model and then calls the generate method to get a response.

```typescript
const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  system: 'You are a helpful assistant.',
});

// Simple generation
const turn = await claude.generate('Hello, world!');
console.log(turn.response.text);
```

--------------------------------

### CheckpointStore Example Usage

Source: https://providerprotocol.org/agents/core/interfaces/checkpointstore

Demonstrates how to use the CheckpointStore interface to save, load, and delete agent checkpoints. This example uses a file-based implementation.

```typescript
import { fileCheckpoints } from '@providerprotocol/agents/checkpoint';
import { AgentState } from '@providerprotocol/agents/state';

const store = fileCheckpoints({ dir: './checkpoints' });

// Save checkpoint after agent step
await store.save('session-123', state.toJSON());

// Resume from checkpoint on restart
const saved = await store.load('session-123');
if (saved) {
  const restored = AgentState.fromJSON(saved);
  // Continue execution from restored state
}

// Clean up when session is complete
await store.delete('session-123');
```

--------------------------------

### CheckpointStore load() Method Example

Source: https://providerprotocol.org/agents/core/interfaces/checkpointstore

Provides an example of using the load() method to retrieve the most recent checkpoint for a given session. It demonstrates how to restore the agent's state from the loaded data.

```typescript
const saved = await store.load('my-session');
if (saved) {
  const state = AgentState.fromJSON(saved);
  // Resume execution with restored state
} else {
  // Start fresh with initial state
  const state = AgentState.initial();
}
```

--------------------------------

### Create Basic Provider - TypeScript

Source: https://providerprotocol.org/ai/core/functions/createprovider

Demonstrates how to create a basic provider using the createProvider function. It shows the creation of an Anthropic provider with an LLM handler and how to use it to create a model reference. This is a fundamental example for getting started with the library.

```typescript
import { createProvider } from '@providerprotocol/ai';
import { createLLMHandler } from '@providerprotocol/ai';

// Create a basic provider
const anthropic = createProvider({
  name: 'anthropic',
  version: '1.0.0',
  handlers: { llm: createLLMHandler() },
});

// Use the provider to create a model reference
const model = anthropic('claude-sonnet-4-20250514');
```

--------------------------------

### Running Coding Agent Example (Bash)

Source: https://providerprotocol.org/agents

Provides command-line instructions for running a coding agent example. It shows how to set the `ANTHROPIC_API_KEY` environment variable and execute the agent script with a specific prompt or in interactive/TUI modes.

```bash
# Run with a specific prompt
ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts "List all TypeScript files"

# Interactive mode
ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts -i

# TUI mode
ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts --tui
```

--------------------------------

### Configure ReAct Agent with Custom Options using react()

Source: https://providerprotocol.org/agents/execution/functions/react

Shows how to customize the ReAct strategy by providing options to the react() function. This example sets a maximum number of steps (maxSteps) and a custom reasoning prompt (reasoningPrompt) to guide the agent's thought process.

```typescript
import { createAgent } from "@providerprotocol/agents";
import { react } from "@providerprotocol/agents/execution";

// Assume myLLM and searchTool are defined elsewhere

// With custom reasoning prompt and step limit
const customAgent = createAgent({
  llm: myLLM,
  tools: [searchTool],
  strategy: react({
    maxSteps: 10,
    reasoningPrompt: 'Analyze the situation and determine the best action.',
  }),
});
```

--------------------------------

### Stream LLM Responses with Provider Protocol

Source: https://providerprotocol.org/guide/quick-start

Stream tokens from an LLM response as they arrive, allowing for real-time processing. This example shows how to iterate over a stream and process text deltas, then retrieve the complete turn after streaming is finished.

```typescript
import { llm, anthropic } from '@providerprotocol/ai';

const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
});

const stream = claude.stream('Write a haiku about coding.');

for await (const event of stream) {
  if (event.type === 'text_delta') {
    process.stdout.write(event.delta.text ?? '');
  }
}

// Get the complete turn after streaming
const turn = await stream.turn;
```

--------------------------------

### Install @providerprotocol/agents and @providerprotocol/ai

Source: https://providerprotocol.org/agents

Installs the necessary packages for the agent framework and AI provider integration using Bun.

```bash
bun install @providerprotocol/agents @providerprotocol/ai
```

--------------------------------

### DynamicKey Initialization Examples (TypeScript)

Source: https://providerprotocol.org/ai/core/classes/dynamickey

Demonstrates how to initialize the DynamicKey class with different selector functions. These examples showcase fetching keys from environment variables, asynchronously from a secrets manager (like Vault), and based on time of day for rotation.

```typescript
import { DynamicKey } from '@providerprotocol/ai';

// Fetch key from environment based on current mode
const dynamicKey = new DynamicKey(() => {
  return process.env.NODE_ENV === 'production'
    ? process.env.PROD_API_KEY!
    : process.env.DEV_API_KEY!;
});

// Async key fetching from a secrets manager (assuming 'vault' is an initialized client)
// const vaultKey = new DynamicKey(async () => {
//   const secret = await vault.read('secret/openai');
//   return secret.data.apiKey;
// });

// Time-based key rotation
// const morningKey = 'MORNING_API_KEY';
// const afternoonKey = 'AFTERNOON_API_KEY';
// const timedKey = new DynamicKey(() => {
//   const hour = new Date().getHours();
//   return hour < 12 ? morningKey : afternoonKey;
// });

```

--------------------------------

### Prompt Engineering Examples

Source: https://providerprotocol.org/guide/image-generation

Provides examples of effective prompt engineering for image generation, focusing on specificity in style, composition, and technical details to achieve desired results.

```typescript
// Be specific about style
await dalle.generate(
  'A sunset over mountains, impressionist oil painting, ' +
  'vibrant colors, visible brushstrokes'
);

// Specify composition
await dalle.generate(
  'A robot, centered composition, studio lighting, ' +
  'white background, product photography'
);

// Include technical details
await dalle.generate(
  'Isometric view of a cozy coffee shop interior, ' +
  'soft lighting, warm colors, detailed furniture'
);
```

--------------------------------

### Agent ask() Method Example - TypeScript

Source: https://providerprotocol.org/agents/core/interfaces/agent

Provides an example of using the `ask()` method for multi-turn conversations with automatic history management. It details how to manage and update the agent's state across conversational turns.

```typescript
import { AgentState } from '@providerprotocol/agents';

// Assuming 'agent' is an initialized Agent instance
let state = AgentState.initial();

// First turn
const result1 = await agent.ask('My name is Alice.', state);
state = result1.state;

// Second turn - agent remembers context
const result2 = await agent.ask('What is my name?', state);
state = result2.state;
// result2.turn.response.text contains "Alice"
```

--------------------------------

### CheckpointStore list() Method Example

Source: https://providerprotocol.org/agents/core/interfaces/checkpointstore

Illustrates the usage of the list() method to retrieve all session IDs that have saved checkpoints. The example also shows how to iterate through these sessions to potentially delete older ones.

```typescript
const sessions = await store.list();
console.log(`Found ${sessions.length} saved sessions`);

// Clean up old sessions
for (const sessionId of sessions) {
  const meta = await store.loadMetadata(sessionId);
  if (isOlderThan(meta?.timestamp, '7d')) {
    await store.delete(sessionId);
  }
}
```

--------------------------------

### LoggingOptions Interface Examples (TypeScript)

Source: https://providerprotocol.org/agents/core/interfaces/loggingoptions

Demonstrates minimal and verbose configurations for the LoggingOptions interface. These examples show how to set the log level, include message content and timing, and specify a custom logger function.

```typescript
// Minimal logging
const options: LoggingOptions = {
  level: 'warn',
};

// Verbose debug logging to custom destination
const debugOptions: LoggingOptions = {
  level: 'debug',
  includeMessages: true,
  includeTiming: true,
  logger: (msg) => myLogger.log(msg),
};
```

--------------------------------

### Example Middleware Implementation in TypeScript

Source: https://providerprotocol.org/ai/core/interfaces/middleware

Demonstrates how to create a custom middleware by implementing optional hooks like onRequest, onStreamEvent, and onEnd. This example shows how to add a request ID and log the request duration.

```typescript
const customMiddleware: Middleware = {
  name: 'request-id',

  onRequest(ctx) {
    ctx.state.set('requestId', crypto.randomUUID());
  },

  onStreamEvent(event, ctx) {
    // Filter out reasoning events
    if (event.type === StreamEventType.ReasoningDelta) {
      return null;
    }
    return event;
  },

  onEnd(ctx) {
    const duration = ctx.endTime! - ctx.startTime;
    console.log(`Request ${ctx.state.get('requestId')} took ${duration}ms`);
  },
};

```

--------------------------------

### API Key Configuration Examples

Source: https://providerprotocol.org/guide/configuration

Illustrates different ways to configure the API key, including direct strings, environment variables, and asynchronous functions.

```APIDOC
## API Key Configuration

### Description
Demonstrates various methods for providing API keys to the provider configuration.

### Methods

1.  **String**: Provide the API key directly as a string.
    ```typescript
    const claude = llm({
      model: anthropic('claude-sonnet-4-20250514'),
      config: {
        apiKey: 'sk-ant-xxx',
      },
    });
    ```

2.  **Environment Variable**: Use an environment variable to store the API key.
    ```typescript
    const claude = llm({
      model: anthropic('claude-sonnet-4-20250514'),
      config: {
        apiKey: process.env.ANTHROPIC_API_KEY,
      },
    });
    ```

3.  **Async Function**: Provide an asynchronous function that fetches the API key dynamically.
    ```typescript
    const claude = llm({
      model: anthropic('claude-sonnet-4-20250514'),
      config: {
        apiKey: async () => {
          const secret = await fetchFromVault('anthropic-key');
          return secret.value;
        },
      },
    });
    ```

### Automatic Environment Variable Fallback
If `apiKey` is not explicitly provided, UPP checks standard environment variables for common providers (e.g., `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).
```

--------------------------------

### Create Agent with Plan Strategy

Source: https://providerprotocol.org/agents/core/interfaces/planoptions

Demonstrates how to create an agent using the plan execution strategy with custom options like maxPlanSteps and allowReplan. This strategy is useful for managing complex multi-step tasks by generating and executing a plan in topological order.

```typescript
import {
  createAgent,
  plan,
} from "@providerprotocol/agents";

const agent = createAgent({
  // ... other config
  strategy: plan({
    maxPlanSteps: 10,
    allowReplan: true,
  }),
});
```

--------------------------------

### Instantiate Groq Model and Generate Text

Source: https://providerprotocol.org/ai/groq/variables/groq

Demonstrates how to instantiate a Groq model using the 'groq' provider and generate text. It shows the basic setup for creating a model reference and making a generation call.

```typescript
const model = llm({
  model: groq('llama-3.3-70b-versatile'),
  params: { max_tokens: 1000 }
});

const turn = await model.generate('Hello!');
console.log(turn.response.text);
```

--------------------------------

### Define File Read Tool with Dependencies (TypeScript)

Source: https://providerprotocol.org/agents/core/interfaces/toolwithdependencies

Example of defining a 'read_file' tool using ToolWithDependencies. It specifies 'sequential: true' to ensure it completes before any other tools start. This tool requires a 'path' parameter and uses Node.js 'fs.readFile' for its run logic.

```typescript
const readTool: ToolWithDependencies = {
  name: 'read_file',
  description: 'Read a file',
  parameters: {
    type: 'object',
    properties: { path: { type: 'string' } },
    required: ['path'],
  },
  sequential: true, // Must complete before other tools
  run: async (params) => fs.readFile(params.path, 'utf-8'),
};
```

--------------------------------

### Pub-Sub Middleware: Enable Stream Resumption with Server and Framework Adapters

Source: https://providerprotocol.org/ai

Implements pubsubMiddleware for stream resumption, allowing reconnecting clients to catch up on missed events. Includes server setup using Bun.serve and examples for Express, Fastify, and H3/Nuxt framework adapters.

```typescript
// Create a shared adapter instance
const adapter = memoryAdapter({ maxStreams: 1000 });

// Server route handling both new requests and reconnections
Bun.serve({
  port: 3000,
  async fetch(req) {
    const { messages, streamId } = await req.json();
    const exists = await adapter.exists(streamId);

    if (!exists) {
      // Start background generation (fire and forget)
      // Stream is created lazily on first append()
      const model = llm({
        model: anthropic('claude-sonnet-4-20250514'),
        middleware: [pubsubMiddleware({ adapter, streamId })],
      });
      model.stream(messages).then(turn => { /* save to DB */ });
    }

    // Both new and reconnect: subscribe to events
    return new Response(webapi.createSubscriberStream(streamId, adapter), {
      headers: { 'Content-Type': 'text/event-stream' },
    });
  },
});
```

```typescript
// Express
app.post('/api/ai/reconnect', (req, res) => {
  const { streamId } = req.body;
  express.streamSubscriber(streamId, adapter, res);
});

// Fastify
app.post('/api/ai/reconnect', (request, reply) => {
  const { streamId } = request.body;
  return fastify.streamSubscriber(streamId, adapter, reply);
});

// H3/Nuxt
export default defineEventHandler(async (event) => {
  const { streamId } = await readBody(event);
  return h3.streamSubscriber(streamId, adapter, event);
});
```

--------------------------------

### Full LLM Client Configuration Example (TypeScript)

Source: https://providerprotocol.org/guide/configuration

Demonstrates a comprehensive configuration for an LLM client, including API key management with key rotation, custom base URL, request timeout, a custom retry strategy, and request parameters. It also shows how to set a system prompt for the model.

```typescript
const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  config: {
    apiKey: new RoundRobinKeys([
      process.env.ANTHROPIC_KEY_1!,
      process.env.ANTHROPIC_KEY_2!,
    ]),
    baseUrl: 'https://my-proxy.example.com',
    timeout: 30000,
    retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
  },
  params: {
    max_tokens: 4096,
    temperature: 0.7,
  } as AnthropicLLMParams,
  system: 'You are a helpful assistant.',
});
```

--------------------------------

### Streaming LLM Responses with Tool Usage in TypeScript

Source: https://providerprotocol.org/guide/streaming

Illustrates how to stream LLM responses when tool usage is involved, using TypeScript. The stream will emit events for tool calls, execution starts, and execution ends, in addition to text deltas. This example defines a `get_weather` tool and processes its related events.

```typescript
const weatherTool = {
  name: 'get_weather',
  description: 'Get weather for a location',
  parameters: {
    type: 'object',
    properties: {
      location: { type: 'string' },
    },
    required: ['location'],
  },
  run: async ({ location }) => ({ temp: 72, conditions: 'sunny' }),
};

const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: [weatherTool],
});

const stream = claude.stream('What is the weather in Tokyo?');

for await (const event of stream) {
  switch (event.type) {
    case 'text_delta':
      process.stdout.write(event.delta.text ?? '');
      break;

    case 'tool_call_delta':
      // Tool arguments being streamed
      console.log('\n[Calling tool:', event.delta.toolName, ']');
      break;

    case 'tool_execution_start':
      console.log(`[Executing ${event.delta.toolName}...]`);
      break;

    case 'tool_execution_end':
      console.log(`[Result: ${JSON.stringify(event.delta.result)}]`);
      break;
  }
}
```

--------------------------------

### Stop Condition Example

Source: https://providerprotocol.org/uap/full

Example implementation of a `stopCondition` function for agent execution.

```APIDOC
## Stop Condition Example

### Description
An example of how to define a `stopCondition` for agent execution to prevent infinite loops.

### Method
N/A (Code Example)

### Code
```javascript
strategy: {
  stopCondition: (state) => {
    if (state.metadata.taskComplete) return true
    if (state.metadata.totalTokens > 50000) return true
    return false
  },
}
```
```

--------------------------------

### First LLM Call with Provider Protocol

Source: https://providerprotocol.org/guide/quick-start

Make your first call to a Large Language Model (LLM) using the Provider Protocol. This involves importing the library, creating an LLM instance with a specific model and system prompt, and then generating a text response.

```typescript
import { llm, anthropic } from '@providerprotocol/ai';

const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  system: 'You are a helpful assistant.',
});

const turn = await claude.generate('What is the capital of France?');
console.log(turn.response.text);
// "The capital of France is Paris."
```

--------------------------------

### Secure AI Provider Key Management and Request Handling (TypeScript)

Source: https://providerprotocol.org/ai/proxy/variables/webapi

This example demonstrates a server setup using Bun.serve for handling AI model requests. It includes user token validation, secure management of API keys using a RoundRobinKeys strategy, and exponential backoff for retries. The server can stream responses or return them as JSON, with options for system prompts and other parameters.

```typescript
async function validateToken(token: string): Promise<{ id: string } | null> {
  // Verify JWT, check database, etc.
  return token ? { id: 'user-123' } : null;
}

// Server manages AI provider keys - users never see them
const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  config: {
    apiKey: new RoundRobinKeys([process.env.ANTHROPIC_KEY_1!, process.env.ANTHROPIC_KEY_2!]),
    retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
  },
});

Bun.serve({
  port: 3000,
  async fetch(req) {
    // Authenticate with YOUR platform credentials
    const token = req.headers.get('Authorization')?.replace('Bearer ', '');
    const user = await validateToken(token ?? '');
    if (!user) return toError('Unauthorized', 401);

    // Rate limit, track usage, bill user, etc.
    // await trackUsage(user.id);

    const { messages, system, params } = parseBody(await req.json());

    if (params?.stream) {
      return toSSE(claude.stream(messages, { system }));
    }
    return toJSON(await claude.generate(messages, { system }));
  },
});
```

--------------------------------

### Configure xAI Models for LLM and Image Generation with API Modes

Source: https://providerprotocol.org/guide/core-providers

This example demonstrates configuring xAI's Grok models for both LLM and image generation. It also shows how to explicitly select different API modes, including the default and an OpenAI-compatible mode.

```typescript
// LLM
const grok = llm({ model: xai('grok-2') });

// Image generation
const aurora = image({ model: xai('grok-2-image') });
```

```typescript
// Default mode
const grok = llm({ model: xai('grok-2') });

// Explicit mode selection
const grokOpenAI = llm({ model: xai('grok-2', { api: 'openai' }) });
```

--------------------------------

### Configuring Middleware for LLM Instance

Source: https://providerprotocol.org/upp/full

Shows how to initialize an LLM instance with custom middleware. This example includes logging and parsed object middleware, demonstrating how to intercept and modify requests/responses.

```javascript
claude = llm({
  model: anthropic("claude-sonnet-4-20250514"),
  middleware: [
    loggingMiddleware(),
    parsedObjectMiddleware()
  ]
})
```

--------------------------------

### Provider Integration Examples (TypeScript)

Source: https://providerprotocol.org/agents

Demonstrates how to initialize an agent with different AI providers and set provider-specific parameters. It shows examples for Anthropic, OpenAI, Google, and Ollama (local), highlighting the `agent` function and the `params` option for customization.

```typescript
// Anthropic
agent({ model: anthropic('claude-sonnet-4-20250514'), params: { max_tokens: 4096 } });

// OpenAI
agent({ model: openai('gpt-4o'), params: { max_output_tokens: 4096 } });

// Google
agent({ model: google('gemini-2.0-flash'), params: { maxOutputTokens: 4096 } });

// Ollama (local)
agent({ model: ollama('llama3:8b'), params: { num_predict: 4096 } });
```

--------------------------------

### Enable Web Search with Groq LLM

Source: https://providerprotocol.org/guide/core-providers

This example demonstrates how to enable real-time web search capabilities when using the Groq provider for LLM tasks. It configures the `search_settings` within the `params` object to activate automatic search mode.

```typescript
const searchModel = llm({
  model: groq('llama-3.3-70b-versatile'),
  params: {
    search_settings: { mode: 'auto' },
  },
});

const turn = await searchModel.generate('What are the latest AI news today?');
```

--------------------------------

### OpenAIResponsesParams Example with Reasoning - TypeScript

Source: https://providerprotocol.org/ai/openai/interfaces/openairesponsesparams

Example of creating an OpenAIResponsesParams object with max_output_tokens, temperature, and reasoning parameters. This demonstrates basic configuration for the Responses API.

```typescript
const params: OpenAIResponsesParams = {
  max_output_tokens: 1000,
  temperature: 0.7,
  reasoning: { effort: 'medium' }
};
```

--------------------------------

### XAICompletionsParams Example - TypeScript

Source: https://providerprotocol.org/ai/xai/interfaces/xaicompletionsparams

An example demonstrating how to define and initialize an XAICompletionsParams object in TypeScript. This shows common parameters like max_tokens, temperature, and reasoning_effort.

```typescript
const params: XAICompletionsParams = {
  max_tokens: 1000,
  temperature: 0.7,
  reasoning_effort: 'high', // Grok 3 Mini only
};
```

--------------------------------

### Audio.fromPath()

Source: https://providerprotocol.org/ai/core/classes/audio

Creates an Audio object by reading a file from disk. The MIME type is automatically detected from the file extension.

```APIDOC
## Audio.fromPath()

### Description
Creates an Audio by reading a file from disk. The file is read into memory as bytes. MIME type is automatically detected from the file extension.

### Method
`static`

### Endpoint
N/A (Static method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*   **path** (`string`) - Required - Path to the audio file
*   **duration** (`number`) - Optional - Duration in seconds

### Request Example
```typescript
const audio = await Audio.fromPath('./recordings/interview.mp3');
```

### Response
#### Success Response (200)
*   **Promise<Audio>** (`Promise<Audio>`) - Promise resolving to an Audio object with the file contents

#### Response Example
(Not applicable for static methods returning promises directly)
```

--------------------------------

### Create and Query Agent - TypeScript

Source: https://providerprotocol.org/agents/core/interfaces/agent

Demonstrates creating an agent with a specific model and system prompt, then performing a stateless query. It shows how to instantiate the agent and retrieve a simple text response.

```typescript
import { agent } from '@providerprotocol/agents';
import { anthropic } from '@providerprotocol/ai';

const myAgent = agent({
  model: anthropic('claude-sonnet-4-20250514'),
  system: 'You are a helpful assistant.',
});

// Stateless single query
const turn = await myAgent.query('What is 2+2?');
console.log(turn.response.text);
```

--------------------------------

### ToolExecution Interface Example in TypeScript

Source: https://providerprotocol.org/ai/core/interfaces/toolexecution

An example demonstrating how to define and use the ToolExecution interface in TypeScript. This interface captures all necessary information about a tool call that has been executed.

```typescript
const execution: ToolExecution = {
  toolName: 'get_weather',
  toolCallId: 'call_abc123',
  arguments: { location: 'San Francisco' },
  result: { temperature: 72 },
  isError: false,
  duration: 150,
  approved: true
};
```

--------------------------------

### Quick Start: Basic LLM Generation

Source: https://providerprotocol.org/ai

Demonstrates a basic LLM text generation using the Anthropic provider. It initializes a model and generates a simple text response.

```typescript
const claude = llm({ model: anthropic('claude-sonnet-4-20250514') });
const turn = await claude.generate('Hello!');
console.log(turn.response.text);
```

--------------------------------

### Create and Use an Agent with UAP

Source: https://providerprotocol.org/agents/core

Demonstrates how to create an agent using the `agent` function, configure its model, execution strategy, tools, system prompt, and middleware. It then shows how to initialize agent state and generate a response to a prompt, logging the output.

```typescript
const coder = agent({
  model: anthropic('claude-sonnet-4-20250514'),
  execution: react(),
  tools: [Bash, Read, Write],
  system: 'You are an expert software engineer.',
  middleware: [logging({ level: 'info' })],
});

const state = AgentState.initial();
const { turn, state: newState } = await coder.generate('Fix the bug', state);
console.log(turn.response.text);
```

--------------------------------

### OpenAICompletionsParams Example - TypeScript

Source: https://providerprotocol.org/ai/openai/interfaces/openaicompletionsparams

Example demonstrating how to define and instantiate the OpenAICompletionsParams interface in TypeScript. This interface configures parameters for OpenAI's legacy chat completions API.

```typescript
const params: OpenAICompletionsParams = {
  temperature: 0.7,
  max_tokens: 1000,
  reasoning_effort: 'medium'
};
```

--------------------------------

### TokenBucket Initialization and Usage Example

Source: https://providerprotocol.org/ai/core/classes/tokenbucket

Demonstrates how to initialize a TokenBucket with different configurations for burst capacity and refill rate, and how to integrate it with the createOpenAI function for rate-limited requests.

```typescript
// Allow 10 requests burst, refill 1 token per second
const bucket = new TokenBucket({
  maxTokens: 10,    // Burst capacity
  refillRate: 1,    // Tokens per second
  maxAttempts: 3    // Retry attempts on rate limit
});

// Aggressive rate limiting: 5 req/s sustained
const strictBucket = new TokenBucket({
  maxTokens: 5,
  refillRate: 5
});

// Use with provider
const provider = createOpenAI({
  retryStrategy: bucket
});
```

--------------------------------

### ToolMetadata Interface Example (TypeScript)

Source: https://providerprotocol.org/ai/core/interfaces/toolmetadata

An example demonstrating how to define and use the ToolMetadata interface. This interface allows for provider-specific metadata, such as cache control settings, to be attached to tools.

```typescript
const metadata: ToolMetadata = {
  anthropic: { cache_control: { type: 'ephemeral' } },
  openrouter: { cache_control: { type: 'ephemeral', ttl: '1h' } }
};
```

--------------------------------

### AnthropicComputerTool Example - TypeScript

Source: https://providerprotocol.org/ai/anthropic/interfaces/anthropiccomputertool

An example demonstrating the structure of an AnthropicComputerTool object in TypeScript. This tool is designed for computer use and requires specific type identifiers and display dimensions.

```typescript
const tool: AnthropicComputerTool = {
  type: 'computer_20250124',
  name: 'computer',
  display_width_px: 1920,
  display_height_px: 1080,
};
```

--------------------------------

### AnthropicWebSearchTool Example in TypeScript

Source: https://providerprotocol.org/ai/anthropic/interfaces/anthropicwebsearchtool

This example demonstrates how to define an AnthropicWebSearchTool object in TypeScript. It specifies the tool type, name, maximum allowed searches, and whitelisted domains for web searches.

```typescript
const tool: AnthropicWebSearchTool = {
  type: 'web_search_20250305',
  name: 'web_search',
  max_uses: 5,
  allowed_domains: ['wikipedia.org', 'github.com'],
};
```

--------------------------------

### Build AI API Gateway Server with Bun/Deno/Cloudflare Workers in TypeScript

Source: https://providerprotocol.org/ai

Illustrates setting up a server-side AI API gateway using Bun. It shows how to manage AI provider keys securely on the server, implement user authentication via platform tokens, and handle requests for AI generation, including streaming responses. Dependencies include environment variables for API keys and custom validation/utility functions.

```typescript
// Server manages AI provider keys - users never see them
const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  config: {
    apiKey: new RoundRobinKeys([process.env.ANTHROPIC_KEY_1!, process.env.ANTHROPIC_KEY_2!]),
    retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
  },
});

Bun.serve({
  port: 3000,
  async fetch(req) {
    // Authenticate with YOUR platform credentials
    const token = req.headers.get('Authorization')?.replace('Bearer ', '');
    const user = await validatePlatformToken(token ?? '');
    if (!user) return toError('Unauthorized', 401);

    // Rate limit, track usage, bill user, etc.
    await trackUsage(user.id);

    const { messages, system, params } = parseBody(await req.json());

    if (params?.stream) {
      return toSSE(claude.stream(messages, { system }));
    }
    return toJSON(await claude.generate(messages, { system }));
  },
});
```

--------------------------------

### XAIXSearchTool Interface Example (TypeScript)

Source: https://providerprotocol.org/ai/xai/interfaces/xaixsearchtool

An example demonstrating how to define and initialize the XAIXSearchTool interface in TypeScript. This snippet shows the basic structure and common properties like 'type', 'allowed_x_handles', and 'from_date'.

```typescript
const tool: XAIXSearchTool = {
  type: 'x_search',
  allowed_x_handles: ['elonmusk', 'xai'],
  from_date: '2025-01-01',
};
```

--------------------------------

### Complete Example: Generate Product Image (TypeScript)

Source: https://providerprotocol.org/guide/image-generation

Provides a complete function to generate professional product photography using DALL-E 3. It takes a description, configures DALL-E parameters, generates the image, saves it as a PNG file, and returns the filename and revised prompt.

```typescript
async function generateProductImage(description: string) {
  const dalle = image({
    model: openai('dall-e-3'),
    params: {
      size: '1024x1024',
      quality: 'hd',
      style: 'natural',
    },
  });

  const result = await dalle.generate(
    `Professional product photography of ${description}, ` +
    'studio lighting, white background, high detail'
  );

  const bytes = result.images[0].image.toBytes();
  const filename = `product-${Date.now()}.png`;
  await Bun.write(filename, bytes);

  return {
    filename,
    revisedPrompt: result.images[0].revisedPrompt,
  };
}

const { filename, revisedPrompt } = await generateProductImage('wireless earbuds');
console.log('Saved to:', filename);
console.log('DALL-E prompt:', revisedPrompt);
```

--------------------------------

### Configure Anthropic Provider with Beta Options (TypeScript)

Source: https://providerprotocol.org/ai/anthropic/variables/betas

Demonstrates how to configure an Anthropic provider using the 'betas' option. This allows for enabling experimental features. It shows two methods: using predefined beta constants and directly providing beta version strings.

```typescript
// Using the betas config option (recommended)
const provider = anthropic('claude-sonnet-4-20250514', {
  betas: [betas.structuredOutputs, betas.interleavedThinking],
});

// Or use string values directly for new/unlisted betas
const provider = anthropic('claude-sonnet-4-20250514', {
  betas: ['new-beta-2025-12-01'],
});
```

--------------------------------

### OpenAIResponsesParams Example with Tools - TypeScript

Source: https://providerprotocol.org/ai/openai/interfaces/openairesponsesparams

Example of creating an OpenAIResponsesParams object with max_output_tokens and enabling specific tools like web search and image generation. This showcases the use of built-in tools.

```typescript
const params: OpenAIResponsesParams = {
  max_output_tokens: 2000,
  tools: [tools.webSearch(), tools.imageGeneration()]
};
```

--------------------------------

### VideoBlock Interface Example - TypeScript

Source: https://providerprotocol.org/ai/core/interfaces/videoblock

This example demonstrates how to create an instance of the VideoBlock interface in TypeScript. It shows the required and optional properties, such as type, data, mimeType, duration, width, and height.

```typescript
const videoBlock: VideoBlock = {
  type: 'video',
  data: videoBytes,
  mimeType: 'video/mp4',
  duration: 30,
  width: 1920,
  height: 1080
};
```

--------------------------------

### LLMInstance Example: Simple Generation and Streaming

Source: https://providerprotocol.org/ai/core/interfaces/llminstance

Demonstrates how to instantiate an LLM and use its generate and stream methods. The generate method returns a complete turn, while stream provides an async iterable for real-time output.

```typescript
const instance = llm({ model: openai('gpt-4') });

// Simple generation
const turn = await instance.generate('Hello!');
console.log(turn.response.text);

// Streaming
const stream = instance.stream('Tell me a story');
for await (const event of stream) {
  if (event.type === StreamEventType.TextDelta) {
    process.stdout.write(event.delta.text ?? '');
  }
}
const finalTurn = await stream.turn;
```

--------------------------------

### AudioBlock Interface Example (TypeScript)

Source: https://providerprotocol.org/ai/core/interfaces/audioblock

An example demonstrating how to create an instance of the AudioBlock interface. This interface requires the 'type' and 'mimeType' properties, and accepts 'data' (as Uint8Array) and an optional 'duration' (in seconds).

```typescript
const audioBlock: AudioBlock = {
  type: 'audio',
  data: audioBytes,
  mimeType: 'audio/mp3',
  duration: 120.5
};
```

--------------------------------

### contentBlockStart()

Source: https://providerprotocol.org/ai/core/functions/contentblockstart

This function creates a content block start stream event. It takes an index as a parameter and returns a StreamEvent.

```APIDOC
## contentBlockStart()

### Description
Creates a content block start stream event.

### Method
N/A (Function)

### Endpoint
N/A (Function)

### Parameters
#### Path Parameters
- **index** (number) - Required - The content block index starting

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- Returns a `StreamEvent`

#### Response Example
N/A
```

--------------------------------

### LLM System Prompts: Simple String and Advanced

Source: https://providerprotocol.org/ai

Demonstrates configuring system prompts for LLMs, showing both a simple string format compatible with all providers and a more advanced, provider-specific format for features like prompt caching.

```typescript
// Simple string (all providers)
const simple = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  system: 'You are a helpful assistant.',
});

// Anthropic cache_control format

const cached = llm({
  model: anthropic('claude-sonnet-4-20250514', {
    betas: [betas.promptCaching],
  }),
  system: [
    { type: 'text', text: 'Large context document...', cache_control: { type: 'ephemeral' } },
    { type: 'text', text: 'Instructions...' },
  ],
});
```

--------------------------------

### XAIResponsesParams Example - TypeScript

Source: https://providerprotocol.org/ai/xai/interfaces/xairesponsesparams

An example demonstrating how to define and use the XAIResponsesParams interface in TypeScript. This includes setting parameters for token limits, temperature, and enabling stateful storage and conversation continuation.

```typescript
const params: XAIResponsesParams = {
  max_output_tokens: 1000,
  temperature: 0.7,
  store: true, // Enable stateful storage
  previous_response_id: 'resp_123...', // Continue previous conversation
};
```

--------------------------------

### ImageSourceType Constants and Usage Example (TypeScript)

Source: https://providerprotocol.org/ai/core/variables/imagesourcetype

Defines constants for image source types: Base64, Bytes, and Url. Includes an example demonstrating how to use these constants to check the type of an image source.

```typescript
const ImageSourceType = {
  Base64: 'base64' as const,
  Bytes: 'bytes' as const,
  Url: 'url' as const
};

// Example usage:
// Assuming 'source' is an object with a 'type' property
// if (source.type === ImageSourceType.Base64) {
//   // Handle base64 encoded image
// } else if (source.type === ImageSourceType.Url) {
//   // Handle URL reference
// }
```

--------------------------------

### Agent Execution Strategies and Tool Ordering Example (TypeScript)

Source: https://providerprotocol.org/agents/execution

Demonstrates how to import and use execution strategies (loop, react, plan) and the orderToolCalls function from the @providerprotocol/agents/execution module. This example shows basic agent creation with a strategy and manual ordering of tool calls.

```typescript
import {
  loop,
  react,
  plan,
  orderToolCalls,
  injectToolContext,
} from '@providerprotocol/agents/execution';

// Use a strategy
const agent = createAgent({
  llm: myLLM,
  strategy: react({ maxSteps: 10 }),
});

// Order tool calls manually
const groups = orderToolCalls(toolCalls, tools);
```

--------------------------------

### ToolUseStrategy Example - TypeScript

Source: https://providerprotocol.org/ai/core/interfaces/toolusestrategy

An example demonstrating how to implement the ToolUseStrategy interface in TypeScript. This strategy defines maximum iterations and custom logic for before, during, and after tool calls, including parameter transformation and result sanitization.

```typescript
const strategy: ToolUseStrategy = {
  maxIterations: 5,
  onToolCall: (tool, params) => {
    console.log(`Calling ${tool.name} with`, params);
  },
  // Transform input parameters
  onBeforeCall: (tool, params) => {
    if (tool.name === 'search') {
      return { proceed: true, params: { ...params, limit: 10 } };
    }
    return true;
  },
  // Transform output results
  onAfterCall: (tool, params, result) => {
    if (tool.name === 'fetch_data') {
      return { result: sanitize(result) };
    }
  },
  onMaxIterations: (iterations) => {
    console.warn(`Reached max iterations: ${iterations}`);
  }
};
```

--------------------------------

### ThreadTree Constructor Examples (TypeScript)

Source: https://providerprotocol.org/agents/thread-tree/classes/threadtree

Illustrates how to instantiate the ThreadTree class, both by creating a fresh tree with an automatically generated root node and by initializing it with an existing root node, typically used during deserialization.

```typescript
import { ThreadTree, ThreadNode } from "@providerprotocol/agents";

// Create a fresh tree
const tree = new ThreadTree();

// Create from an existing root (used by fromJSON)
// Assuming 'id', 'null', 'state' are defined elsewhere
// const existingRoot = new ThreadNode(id, null, state, 'root');
// const tree = new ThreadTree(existingRoot);
```
Tokens:
Raw