Core Types - AgentLIB

Overview

AgentLIB is fully typed with TypeScript. This reference documents the core types and interfaces used throughout the library.

Model Types

ModelMessage

Represents a single message in a conversation.

role

'system' | 'user' | 'assistant' | 'tool'

required

The role of the message sender.

content

string

required

The text content of the message.

reasoning

string

Extended thinking or reasoning content (for models that support extended reasoning).

toolCallId

string

ID linking this message to a tool call (for role: 'tool' messages).

toolCalls

ToolCall[]

Array of tool calls requested by the assistant.

interface ModelMessage {
  role: 'system' | 'user' | 'assistant' | 'tool'
  content: string
  reasoning?: string
  toolCallId?: string
  toolCalls?: ToolCall[]
}

ToolCall

Represents a request to execute a tool.

string

required

Unique identifier for this tool call.

name

string

required

Name of the tool to execute.

arguments

Record<string, unknown>

required

Arguments to pass to the tool.

interface ToolCall {
  id: string
  name: string
  arguments: Record<string, unknown>
}

ModelRequest

Request sent to a model provider.

messages

ModelMessage[]

required

Conversation history.

tools

ToolSchema[]

Available tools the model can use.

stream

boolean

Whether to stream the response.

ModelResponse

Response from a model provider.

message

ModelMessage

required

The generated message.

toolCalls

ToolCall[]

Tool calls requested by the model.

usage

TokenUsage

Token usage statistics.

raw

unknown

Raw response from the provider.

TokenUsage

Token usage statistics.

promptTokens

number

required

Number of tokens in the prompt.

completionTokens

number

required

Number of tokens in the completion.

totalTokens

number

required

Total tokens used (prompt + completion).

ModelProvider

Interface that all model providers must implement.

name

string

required

Provider name.

complete

(request: ModelRequest) => Promise<ModelResponse>

required

Generate a completion.

stream

(request: ModelRequest) => AsyncIterable<ModelResponseChunk>

Stream a completion (optional).

Tool Types

ToolSchema

JSON Schema definition for a tool.

name

string

required

Tool name (must be unique).

description

string

required

Human-readable description of what the tool does.

parameters

Record<string, unknown>

required

JSON Schema object describing the tool’s parameters.

interface ToolSchema {
  name: string
  description: string
  parameters: Record<string, unknown> // JSON Schema
}

ToolDefinition

Complete tool definition including execution logic.

schema

ToolSchema

required

The tool’s schema.

execute

(args: Record<string, unknown>, ctx: ExecutionContext<TData>) => Promise<unknown>

required

Function that executes the tool.

interface ToolDefinition<TData = unknown> {
  schema: ToolSchema
  execute(args: Record<string, unknown>, ctx: ExecutionContext<TData>): Promise<unknown>
}

Memory Types

MemoryEntry

A single stored memory entry with metadata.

string

required

Unique entry identifier.

sessionId

string

required

Session this entry belongs to.

messages

ModelMessage[]

required

Conversation messages in this entry.

metadata

MemoryMetadata

required

Entry metadata.

interface MemoryEntry {
  id: string
  sessionId: string
  messages: ModelMessage[]
  metadata: MemoryMetadata
}

MemoryMetadata

Metadata associated with a memory entry.

createdAt

Date

required

When the entry was created.

accessedAt

Date

When the entry was last accessed.

agentName

string

Agent that created this entry.

MemoryReadOptions

Options for reading from memory.

limit

number

Maximum number of messages to return.

sessionId

string

Only return messages from this session.

query

string

Semantic query for vector-based providers.

MemoryWriteOptions

Options for writing to memory.

sessionId

string

Session identifier for this write.

MemoryProvider

Interface that all memory providers must implement.

type

string

required

Provider type identifier.

read

(options: MemoryReadOptions) => Promise<ModelMessage[]>

required

Load prior conversation history.

write

(messages: ModelMessage[], options: MemoryWriteOptions) => Promise<void>

required

Persist messages from a completed run.

clear

(sessionId?: string) => Promise<void>

Remove all stored memory (optional).

entries

(sessionId?: string) => Promise<MemoryEntry[]>

Return raw entries for inspection (optional).

Reasoning Types

ReasoningStrategy

Built-in reasoning strategies.

type ReasoningStrategy = 'react' | 'planner' | 'cot' | 'reflect' | 'autonomous'

react: ReAct (Reason + Act) pattern
planner: Plan-and-execute pattern
cot: Chain of Thought
reflect: Self-reflection and refinement
autonomous: Autonomous agent loop

ReasoningStep

Union type representing any reasoning step.

type ReasoningStep =
  | ThoughtStep
  | PlanStep
  | ToolCallStep
  | ToolResultStep
  | ReflectionStep
  | ResponseStep

ThoughtStep

type

'thought'

required

content

string

required

The thought content.

engine

string

required

Engine that produced this step.

PlanStep

type

'plan'

required

tasks

PlanTask[]

required

Ordered list of subtasks.

engine

string

required

ToolCallStep

type

'tool_call'

required

toolName

string

required

args

Record<string, unknown>

required

callId

string

required

engine

string

required

ToolResultStep

type

'tool_result'

required

toolName

string

required

callId

string

required

result

unknown

required

error

string

Error message if the tool failed.

engine

string

required

ReflectionStep

type

'reflection'

required

assessment

string

required

What the engine assessed about its previous output.

needsRevision

boolean

required

Whether the answer needs revision.

engine

string

required

ResponseStep

type

'response'

required

content

string

required

engine

string

required

ReasoningEngine

Interface for custom reasoning engines.

name

string

required

Engine name.

execute

(rCtx: ReasoningContext<TData>) => Promise<string>

required

Execute the reasoning loop and return final output.

ReasoningContext

Runtime context passed to reasoning engines.

ctx

ExecutionContext<TData>

required

The enclosing execution context.

model

ModelProvider

required

The configured model provider.

tools

ToolRegistry

required

All registered tools.

policy

AgentPolicy

required

Agent policy constraints.

systemPrompt

string

System prompt (if set).

pushStep

(step: ReasoningStep) => void

required

Append a step to state.steps and emit an event.

callTool

(name: string, args: Record<string, unknown>, callId: string) => Promise<unknown>

required

Execute a tool by name and record the result.

Execution Types

ExecutionState

Internal runtime state during agent execution.

steps

ReasoningStep[]

required

All reasoning steps taken.

messages

ModelMessage[]

required

Full conversation history.

toolCalls

Array<{ call: ToolCall; result: unknown }>

required

All tool calls and their results.

usage

TokenUsage

required

Cumulative token usage.

startedAt

Date

required

When execution started.

finishedAt

Date

When execution finished.

ExecutionContext

Context object passed to tools and middleware.

input

string

required

User input for this run.

data

TData

required

User-defined typed state.

state

ExecutionState

required

Internal runtime state (do not mutate).

sessionId

string

required

Active session ID for this run.

memory

MemoryProvider | null

required

Memory provider scoped to this run.

cancel

() => void

required

Cancel the current execution.

emit

(event: string, payload?: unknown) => void

required

Emit a custom event.

Middleware Types

MiddlewareScope

Execution lifecycle points where middleware can hook in.

type MiddlewareScope =
  | 'run:before'
  | 'run:after'
  | 'step:before'
  | 'step:after'
  | 'tool:before'
  | 'tool:after'

Middleware

Middleware definition.

name

string

Middleware name (for debugging).

scope

MiddlewareScope | MiddlewareScope[]

Scopes this middleware applies to. If not specified, applies to all scopes.

run

(mCtx: MiddlewareContext<TData>, next: NextFn) => Promise<void>

required

Middleware execution function.

MiddlewareContext

Context passed to middleware functions.

scope

MiddlewareScope

required

Current scope.

ctx

ExecutionContext<TData>

required

Execution context.

tool

{ name: string; args: Record<string, unknown>; result?: unknown }

Tool-specific context (present when scope is tool:*).

Policy Types

AgentPolicy

Constraints applied to agent execution.

maxSteps

number

Maximum reasoning steps allowed.

maxCost

number

Maximum cost (in USD) allowed.

timeout

number

Execution timeout in milliseconds.

allowedTools

string[]

Whitelist of allowed tool names.

tokenBudget

number

Maximum total tokens allowed.

maxParallelTools

number

Maximum number of tools to execute in parallel.

Configuration Types

AgentConfig

Configuration for creating an agent.

name

string

required

Agent name.

description

string

Agent description.

model

ModelProvider

Model provider to use.

tools

ToolDefinition<TData>[]

Tools available to the agent.

memory

MemoryProvider

Memory provider for conversation history.

reasoning

ReasoningStrategy | ReasoningEngine<TData>

Reasoning strategy or custom engine.

middleware

Middleware<TData>[]

Middleware to apply.

policy

AgentPolicy

Policy constraints.

systemPrompt

string

System prompt.

data

TData

Initial custom state.

RunOptions

Options for running an agent.

input

string

required

User input.

data

Partial<TData>

Override custom state for this run.

signal

AbortSignal

Abort signal for cancellation.

sessionId

string

Session identifier for memory scoping. Defaults to a random UUID.

RunResult

Result from an agent run.

output

string

required

Final text output.

state

ExecutionState

required

Complete execution state including steps and token usage.

Core

Model Providers

Memory

Reasoning

Orchestrator

Logger

Types

​Overview

​Model Types

​ModelMessage

​ToolCall

​ModelRequest

​ModelResponse

​TokenUsage

​ModelProvider

​Tool Types

​ToolSchema

​ToolDefinition

​Memory Types

​MemoryEntry

​MemoryMetadata

​MemoryReadOptions

​MemoryWriteOptions

​MemoryProvider

​Reasoning Types

​ReasoningStrategy

​ReasoningStep

​ThoughtStep

​PlanStep

​ToolCallStep

​ToolResultStep

​ReflectionStep

​ResponseStep

​ReasoningEngine

​ReasoningContext

​Execution Types

​ExecutionState

​ExecutionContext

​Middleware Types

​MiddlewareScope

​Middleware

​MiddlewareContext

​Policy Types

​AgentPolicy

​Configuration Types

​AgentConfig

​RunOptions

​RunResult

Build docs developers (and LLMs) love

Overview

Model Types

ModelMessage

ToolCall

ModelRequest

ModelResponse

TokenUsage

ModelProvider

Tool Types

ToolSchema

ToolDefinition

Memory Types

MemoryEntry

MemoryMetadata

MemoryReadOptions

MemoryWriteOptions

MemoryProvider

Reasoning Types

ReasoningStrategy

ReasoningStep

ThoughtStep

PlanStep

ToolCallStep

ToolResultStep

ReflectionStep

ResponseStep

ReasoningEngine

ReasoningContext

Execution Types

ExecutionState

ExecutionContext

Middleware Types

MiddlewareScope

Middleware

MiddlewareContext

Policy Types

AgentPolicy

Configuration Types

AgentConfig

RunOptions

RunResult