Runner

The Runner class orchestrates the execution of Agents, handling multi-turn interactions and providing execution context.

Creating a Runner

import { Agent, Runner } from "loom-agents";

const agent = new Agent({
  name: "Assistant",
  purpose: "Help with general tasks",
  // ... other config
});

const runner = new Runner(agent, {
  name: "MainRunner",
  max_depth: 5,
  context: {
    user_id: "user-123",
    session_start: Date.now(),
  },
});

Runner Configuration

The RunnerConfig interface defines available configuration options:

interface RunnerConfig {
  max_depth?: number; // Optional: Maximum number of turns (default: 10)
  name?: string; // Optional: Runner name (default: "Runner")
  id?: string; // Optional: Unique ID (default: auto-generated UUID)
  context?: Record<string, any>; // Optional: Additional context data
}

Running an Agent

The run method executes the agent and manages the interaction flow:

// Simple string input
const result = await runner.run("Help me write a resume");

// Rich context input
const result = await runner.run({
  context: [
    { role: "user", content: "I need help with my resume" },
    { role: "assistant", content: "I can help! What industry are you in?" },
    { role: "user", content: "Software engineering" },
  ],
});

Managing Execution Flow

The Runner handles:

1. Executing the agent with the provided input
2. Processing agent responses and tool calls
3. Managing multi-turn conversations up to max_depth
4. Tracing execution with the integrated Tracer

Handling Results

The run method returns a RunnerResponse which is a souped-up AgentResponse

interface RunnerResponse<T> extends AgentResponse<T> {
  trace: Trace; // The execution trace
}

Accessing Execution Data

The Runner provides methods to access execution details:

// Get the most recent trace
const lastTrace = runner.getLastTrace();

// Get all traces from this runner
const traces = runner.getTraces();

// Render the last trace for debugging
console.log(lastTrace.render());

Execution Depth and Handling

The Runner prevents infinite loops by enforcing a maximum execution depth:

const runner = new Runner(agent, {
  max_depth: 5, // Agent will stop after 5 interaction turns
});

If the maximum depth is reached before the agent completes its task, the runner will return the current state with the status from the agent’s last response.

Related

• Agent: The core AI component orchestrated by Runners
• Trace: Provides detailed execution logs
• Loom: Global configuration for OpenAI settings