# PrimeAgent API Reference: Complete Guide to Session Management, Streaming, and LLM Integration

> Explore the PrimeAgent API for seamless LLM integration. Manage persistent agent workflows and utilize streaming capabilities with this comprehensive TypeScript API guide.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: api-reference
- Published: 2026-08-20

---

**PrimeAgent exposes a dual-layered TypeScript API consisting of a host-side session manager (`createAgentSession`) for running persistent agent workflows and a provider-agnostic streaming layer (`stream`, `complete`) for direct LLM integration.**

The PrimeAgent API is the programmatic interface for PrimeIntellect-ai/prime-agent, a TypeScript-based coding agent framework that orchestrates LLM interactions with persistent IPython kernels and tool execution. Whether you are embedding agent capabilities into a Node.js application or building custom extensions, understanding the two-layer architecture—host session management and model-facing streaming—is essential for effective integration.

## Core Architecture: Host Layer vs. Model Layer

PrimeAgent organizes its API into distinct layers with clear separation of concerns:

- **Host Layer (`@earendil-works/pi-agent-core`)**: Manages persistent sessions, tool registration, and conversation state
- **Model Layer (`@earendil-works/pi-ai`)**: Handles provider-specific LLM communication with unified streaming semantics

This separation allows you to use the streaming primitives directly for simple completions or leverage the full session machinery for multi-turn interactive workflows.

## Host-Side API: Creating and Managing Agent Sessions

The primary entry point for PrimeAgent integration is `createAgentSession()` in [`packages/coding-agent/src/core/sdk.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/sdk.ts).

### Session Creation and Initialization

```typescript
export async function createAgentSession(
  options?: CreateAgentSessionOptions,
): Promise<CreateAgentSessionResult>;

```

When invoked, `createAgentSession` instantiates several core components:

- **SessionManager** – Persists conversation history to JSONL files and handles session lifecycle
- **SettingsManager** – Loads authentication credentials and user preferences
- **ModelRegistry** – Enumerates available models based on configured API keys
- **Agent** – The core state machine that processes messages and schedules tool calls

The `findInitialModel()` function in [`packages/coding-agent/src/core/model-resolver.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/model-resolver.ts) automatically selects a default model or restores a previously used model from session storage.

### Configuration Options

The `CreateAgentSessionOptions` interface supports extensive customization:

| Option | Purpose |
|--------|---------|
| `model` | Explicit `Model` selection, bypassing auto-resolution |
| `tools` | Allow-list of built-in tools to enable (`ipython`, `bash`, `edit`) |
| `noTools` | Disable all tool execution |
| `customTools` | Array of `ToolDefinition` objects for domain-specific capabilities |
| `thinkingLevel` | Reasoning depth: `"low"`, `"medium"`, `"high"` |
| `onPayload` | Callback to intercept/modify provider requests |
| `onResponse` | Callback to inspect raw provider responses |

### Working with AgentSession

The returned `AgentSession` exposes methods for interactive control:

```typescript
const { session } = await createAgentSession();

// Inject a user message into conversation state
await session.sendMessage({
  role: "user",
  content: "Analyze the runtime complexity of this function",
  timestamp: Date.now()
});

// Execute one agent turn (may involve multiple tool calls)
await session.runTurn();

// Attach to an existing session for debugging or monitoring
await session.attach(sessionId);

```

## Model-Facing API: Streaming and Completion Functions

For direct LLM interaction without session overhead, use the streaming primitives in [`packages/ai/src/stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/stream.ts).

### Core Streaming Function

```typescript
export function stream<TApi extends Api>(
  model: Model<TApi>,
  context: Context,
  options?: ProviderStreamOptions,
): AssistantMessageEventStream;

```

The `stream` function returns an `AssistantMessageEventStream` that emits incremental events defined in `AssistantMessageEvent` ([`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts)):

- `start` – Stream initialization
- `text_delta` – Incremental text generation
- `thinking_delta` – Reasoning chain updates (for supported models)
- `toolcall_delta` – Partial tool call formation
- `done` – Completion signal with final `AssistantMessage`
- `error` – Structured error information

### Convenience Wrappers

PrimeAgent provides three simplified variants:

- **`complete<TApi>()`** – Consumes the full stream and returns a single `AssistantMessage`
- **`streamSimple<TApi>()`** – Accepts `SimpleStreamOptions` with explicit `reasoning` level and custom `thinkingBudgets`
- **`completeSimple<TApi>()`** – Combines simple options with full consumption

All variants resolve the correct provider implementation via `getApiProvider()` in [`packages/ai/src/api-registry.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/api-registry.ts), with built-in providers registered through [`packages/ai/src/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/register-builtins.ts).

### Provider Registration Architecture

New LLM providers are added by:

1. Implementing the `Provider` interface in `packages/ai/src/providers/<provider>.ts`
2. Registering the provider in [`packages/ai/src/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/register-builtins.ts)

Supported providers include OpenAI, Anthropic, and Amazon Bedrock, with automatic credential resolution from environment variables or settings files.

## Message and Event Types

The unified type system in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) ensures consistency across layers.

### Core Message Types

| Type | Description |
|------|-------------|
| `UserMessage` | Input from the user with timestamp |
| `AssistantMessage` | Complete LLM response with content blocks |
| `ToolResultMessage` | Structured output from tool execution |

### Content Block Variants

- `TextContent` – Plain text segments
- `ThinkingContent` – Model reasoning traces
- `ImageContent` – Base64-encoded images with mime types
- `ToolCall` – Pending or completed tool invocations

### Streaming Event Protocol

The `AssistantMessageEvent` type defines the contract between provider implementations and consumers, enabling type-safe handling of partial responses across all supported LLM APIs.

## Practical Integration Examples

### One-Shot Completion with Custom Reasoning

```typescript
import { getModel, streamSimple } from "@earendil-works/pi-ai";
import { createAgentSession } from "@earendil-works/pi-agent-core";

async function run() {
  // Initialize agent session for credential and model management
  const { session } = await createAgentSession();

  // Resolve specific model with cost and capability metadata
  const model = getModel("anthropic", "claude-opus-4-5");

  // Construct minimal conversation context
  const context = {
    messages: [{
      role: "user",
      content: "Explain recursion in 2 sentences.",
      timestamp: Date.now()
    }],
  };

  // Stream with high reasoning depth
  const stream = await streamSimple(model, context, { reasoning: "high" });
  
  stream.on("text_delta", ({ delta }) => process.stdout.write(delta));
  await stream.result(); // Await completion
}

run().catch(console.error);

```

*Source: `streamSimple` implementation in* [[`packages/ai/src/stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/stream.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/stream.ts)

### Interactive Session with Tool Constraints

```typescript
import { createAgentSession } from "@earendil-works/pi-agent-core";

async function startInteractive() {
  const { session } = await createAgentSession({
    tools: ["ipython"],                    // IPython only, no bash/edit
    thinkingLevel: "medium",
    model: getModel("openai", "gpt-4o"),   // Explicit model selection
  });

  await session.sendMessage({
    role: "user",
    content: "List all .ts files in src/",
    timestamp: Date.now()
  });

  await session.runTurn(); // Executes until LLM yields final response
}

startInteractive();

```

*Source: `createAgentSession` in* [[`packages/coding-agent/src/core/sdk.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/sdk.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/sdk.ts)

### Custom Tool Registration

```typescript
import { createAgentSession, ToolDefinition } from "@earendil-works/pi-agent-core";

const echoTool: ToolDefinition = {
  name: "echo",
  description: "Echoes back the supplied text.",
  schema: {
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"]
  },
  invoke: async ({ text }) => ({
    role: "toolResult",
    toolCallId: "1",
    toolName: "echo",
    content: [{ type: "text", text }],
    isError: false,
    timestamp: Date.now()
  }),
};

async function demo() {
  const { session } = await createAgentSession({
    customTools: [echoTool],
    tools: ["echo"], // Explicit enable required
  });

  await session.sendMessage({
    role: "user",
    content: "Use the echo tool to say hello.",
    timestamp: Date.now()
  });
  await session.runTurn();
}

demo();

```

*Source: Tool registration API in* [[`packages/coding-agent/src/tools/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/tools/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/tools/index.ts)

## CLI Interface as API Consumer

The `prime-agent` binary is a thin wrapper over the host API defined in [`packages/coding-agent/src/cli/args.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/args.ts):

| Command | API Mapping |
|---------|-------------|
| Interactive TUI | `createAgentSession()` with default options → [`packages/tui/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts) |
| `--mode json` | Direct `streamSimple`/`completeSimple` invocation |
| `list-models` | `ModelRegistry` enumeration |
| `agents`, `attach`, `resume` | `SessionManager` persistence operations |

All CLI flags map directly to `CreateAgentSessionOptions` fields, ensuring behavioral parity between programmatic and command-line usage.

## Extension Points and Customization

### Provider Extensions

Implement the `Provider` interface to add new LLM backends:

- Handle transport-specific authentication
- Translate native streaming formats to `AssistantMessageEvent` protocol
- Register via [`register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/register-builtins.ts)

### Tool Extensions

Custom tools follow the `ToolDefinition` contract:

- JSON Schema for parameter validation
- Async `invoke` function returning `ToolResultMessage`
- Injection via `customTools` option or package registry

### Lifecycle Hooks

Extensions loaded by `DefaultResourceLoader` can intercept:

- `before_provider_request` – Modify payloads before transmission
- `after_provider_response` – Inspect or transform raw responses
- `context` events – Access conversation state for analytics or logging

## Summary

- **Two-layer architecture**: Host layer (`createAgentSession`) for session management, model layer (`stream`/`complete`) for direct LLM access
- **Entry point**: `createAgentSession()` in [`packages/coding-agent/src/core/sdk.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/sdk.ts) returns a configured `AgentSession` with tool and model resolution
- **Streaming primitives**: `stream`, `streamSimple`, `complete`, `completeSimple` in [`packages/ai/src/stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/stream.ts) provide unified provider abstraction
- **Type safety**: Shared `Message` and `AssistantMessageEvent` types in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) ensure cross-layer consistency
- **Extensibility**: Provider interface, `ToolDefinition` type, and lifecycle hooks enable customization without core modification
- **CLI parity**: All command-line functionality maps directly to programmatic API options

## Frequently Asked Questions

### What is the difference between `stream` and `streamSimple` in the PrimeAgent API?

**`stream`** accepts raw `ProviderStreamOptions` for maximum control over provider-specific parameters, while **`streamSimple`** exposes a streamlined `SimpleStreamOptions`interface with explicit `reasoning` levels and `thinkingBudgets`. Both return the same `AssistantMessageEventStream`, but `streamSimple` is recommended for most use cases as it handles common configuration patterns automatically.

### How do I persist conversation history across process restarts?

PrimeAgent's `SessionManager` automatically persists conversations to JSONL files. When calling `createAgentSession()`, omit the `sessionId` option to create a fresh session, or provide a previously saved ID to resume. The `session.attach(sessionId)` method on `AgentSession` also allows dynamic reconnection to running sessions for debugging or multi-process coordination.

### Can I use PrimeAgent with custom LLM providers not in the builtin registry?

Yes. Implement the `Provider` interface with methods for request streaming and response parsing, then register your implementation in [`packages/ai/src/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/register-builtins.ts). Your provider will integrate seamlessly with `stream()`, `complete()`, and all higher-level APIs. The `getApiProvider()` resolver in [`packages/ai/src/api-registry.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/api-registry.ts) handles runtime selection based on `Model` metadata.