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

# Runtime

> Delegate an Agent turn to a registered runtime.

`runtime` hands the whole turn to a registered runtime instead of running the local chat loop.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[🤖 Agent] --> R[⚙️ resolve runtime]
    R --> C{capabilities ok?}
    C -->|no| E[❌ throws]
    C -->|yes| T[▶️ run turn on runtime]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef err fill:#8B0000,stroke:#7C90A0,color:#fff

    class A agent
    class R,T step
    class C step
    class E err
```

## Quick Start

**1. Use the builtin runtime**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({ instructions: 'Delegated', runtime: true });
await agent.chat('Do the work');
```

`runtime: true` selects `DEFAULT_RUNTIME_ID` (`'praisonai'`).

**2. Name a runtime and require capabilities**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'Streamed',
  runtime: { runtime: 'praisonai', requiredCapabilities: ['streaming'] },
});
```

***

## `AgentRuntimeConfig`

| Field | Type | Notes |
| - | - | - |
| `runtime` | `string` | Runtime id. Defaults to `DEFAULT_RUNTIME_ID` (`'praisonai'`). |
| `requiredCapabilities` | `string[]` | Checked before the agent is built; a missing capability throws. |
| `configOverrides` | `Record<string, unknown>` | Runtime-specific options forwarded on every turn. |
| `metadata` | `Record<string, unknown>` | Free-form metadata. |

`runtime` accepts `true`, a string id, an `AgentRuntimeConfig` object (snake\_case keys accepted), or an object that already satisfies `AgentRuntimeProtocol`.

## When it throws

> [!WARNING]
>
> ```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> # a required capability the runtime does not report
> Error: Runtime 'praisonai' does not provide the required capability: streaming.
>   It reports: (none).
>
> # runtime combined with backend or runOn (both say where the loop runs)
> TypeError: Agent(runtime, backend/runOn) sets where the loop runs twice. ...
>
> # an invalid runtime type
> TypeError: Invalid runtime type: number. Expected boolean, string, object, or an AgentRuntimeProtocol instance.
> ```

`runtime` and `backend` / `runOn` answer the same question — where the loop runs — so naming both is rejected as a contradiction.

## Reading the resolved runtime

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({ instructions: 'x', runtime: true });
console.log(agent.getRuntime()); // the resolved runtime, or undefined
```

## Related

> [card] [Placement](https://praison.ai/docs/js/placement.md)
>
> backend / runOn / toolsRunOn

> [card] [Agent](https://praison.ai/docs/js/agent.md)
>
> Constructor options


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