> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cascadeflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CascadeAgent

> TypeScript CascadeAgent API for model cascading, routing, batch execution, tools, and streaming.

`CascadeAgent` runs the least expensive suitable model first and escalates when validation or routing requires it.

## Constructor

```typescript theme={null}
import { CascadeAgent, type AgentConfig } from '@cascadeflow/core';

const config: AgentConfig = {
  models: [
    { name: 'gpt-4o-mini', provider: 'openai', cost: 0.00015 },
    { name: 'gpt-4o', provider: 'openai', cost: 0.0025 },
  ],
  quality: {
    threshold: 0.7,
    requireMinimumTokens: 3,
  },
};

const agent = new CascadeAgent(config);
```

Models are sorted by cost. A single model produces direct execution, while two or more models enable cascading.

## run()

```typescript theme={null}
const result = await agent.run('Explain speculative execution', {
  maxTokens: 500,
  temperature: 0.2,
  systemPrompt: 'Answer for a software engineer.',
});
```

The input can be a string or an array of universal `Message` objects.

```typescript theme={null}
const result = await agent.run([
  { role: 'system', content: 'Answer concisely.' },
  { role: 'user', content: 'What is model cascading?' },
]);
```

## RunOptions

| Option | Type | Purpose |
| - | - | - |
| `maxTokens` | number | Maximum generated tokens |
| `temperature` | number | Sampling temperature from 0 to 2 |
| `systemPrompt` | string | Stable system instruction |
| `knowledge` | string or `KnowledgeSnapshot` | Request-scoped provider-neutral knowledge |
| `tools` | `Tool[]` | Available tool definitions |
| `toolExecutor` | `ToolExecutor` | Tool implementation registry |
| `maxSteps` | number | Maximum model calls in a tool loop |
| `extra` | object | Provider-specific options |
| `forceDirect` | boolean | Skip cascading |
| `userTier` | string | Apply tier-based filtering |
| `workflow` | string | Select a workflow profile |
| `kpiFlags` | object | Add rule-engine KPI context |
| `tenantId` | string | Apply tenant rules |
| `channel` | string | Apply channel routing and failover |

## Tools

```typescript theme={null}
const result = await agent.run('What is the weather in Zurich?', {
  tools: [weatherTool.toOpenAIFormat()],
  toolExecutor: new ToolExecutor([weatherTool]),
  maxSteps: 5,
});
```

See [Tools](/api-reference/typescript/tools) for complete setup.

## Batch Execution

```typescript theme={null}
const batch = await agent.runBatch(
  ['Summarize A', 'Summarize B'],
  { maxParallel: 2, stopOnError: false },
  { maxTokens: 200 },
);

console.log(batch.successCount, batch.failureCount);
```

## Streaming

```typescript theme={null}
import { StreamEventType } from '@cascadeflow/core';

for await (const event of agent.stream('Write a short explanation')) {
  if (event.type === StreamEventType.CHUNK) {
    process.stdout.write(event.content);
  }
}
```

See [Streaming](/api-reference/typescript/streaming).

## Inspection

```typescript theme={null}
console.log(agent.getModels());
console.log(agent.getModelCount());
console.log(agent.getRouterStats());

agent.resetRouterStats();
```

## Methods

| Method | Returns |
| - | - |
| `run(input, options?)` | `Promise<CascadeResult>` |
| `runBatch(queries, batchConfig?, runOptions?)` | `Promise<BatchResult>` |
| `runStream(input, options?)` | `AsyncIterable<StreamEvent>` |
| `runStreaming(query, options?)` | `Promise<CascadeResult>` |
| `streamEvents(input, options?)` | `AsyncIterable<StreamEvent>` |
| `stream(input, options?)` | `AsyncIterable<StreamEvent>` |
| `getModels()` | `ModelConfig[]` |
| `getModelCount()` | number |
| `getRouterStats()` | router statistics object |
| `resetRouterStats()` | void |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.