Skip to content

executor-api.md

Latest commit

 

History

History
73 lines (60 loc) · 4.46 KB

executor-api.md

File metadata and controls

73 lines (60 loc) · 4.46 KB
Raw

The executor API

createAgent() is the recommended entry point (see the Quick Start). This page is for code that needs the lower-level options it does not take. To move existing executor code over to createAgent(), see Migrating to createAgent().

AgentBuilder and AgentExecutor

createAgent() is a thin wrapper over AgentBuilder and the static AgentExecutor.execute(). Use them directly only for what createAgent() does not take: temperature and maxTokens (exporter, captureContent and redactContent are createAgent() options too). createAgent() already takes maxSteps, limits, onEvent, approvals, store (checkpoints), hooks and compaction. AgentExecutor is a static API - there is no new AgentExecutor().

import {
  AgentBuilder,
  AgentExecutor,
} from '@lousho/build-ai-agent/executor';
import { createMockProvider } from '@lousho/build-ai-agent';

const agent = AgentBuilder.create()
  .setName('Customer Support Agent')
  .setPrompt('You are a helpful customer support assistant.')
  .build();

const events: string[] = [];
const result = await AgentExecutor.execute({
  agent,
  input: 'My order arrived damaged.',
  provider: createMockProvider({ responses: ["I'm sorry to hear that - what's your order number?"] }),
  maxSteps: 5,
  onAgentEvent: (event) => events.push(event.type),
});

console.log(result.text);
console.log(result.usage.totalTokens, result.finishReason, result.steps);
console.log(events); // includes 'run.start' and 'run.done'

Sharing tools with ToolRegistry

Advanced: ToolRegistry. To share tools across agents or register raw ToolDescriptors, use registry.register(tool) for a defined tool or registry.register(name, descriptor) for a descriptor. Pass the registry as toolRegistry to AgentExecutor.execute(). See Tools for a full example.

Options of AgentExecutor.execute()

AgentExecutor is static: call AgentExecutor.execute(options). Only agent, input and provider are required. Commonly used options:

Option Description
agent An AgentConfig, usually built with AgentBuilder.
input A user message string, or a Message[] conversation.
provider The LLMProvider to generate with.
toolRegistry A ToolRegistry holding the tools the agent config refers to.
maxSteps Upper bound on LLM/tool steps.
limits Token, cost, time and step budgets of the run; see Budgets.
temperature, maxTokens Generation parameters.
onAgentEvent Listener for the run's AgentEvents (run.start, tool.start, run.done, ...); see Streaming.
streamModelCalls With a listener, stream each model call so text arrives as several text.delta events (default true); false generates whole steps, one text.delta each. Ignored by stream().
approvalStore, sessionId Human-in-the-loop approvals (see resumeAfterApproval()).
checkpointStore Persist/resume execution checkpoints.
exporter A TraceExporter for tracing spans (OpenTelemetry GenAI conventions, see observability).
captureContent, redactContent Record message/tool content on gen_ai.* span attributes (opt-in) / omit the deprecated content attributes.
onLLMRequest, onLLMResponse, onToolCall, onToolResult Observability hooks.
toolSearch Tunes tool search for tools marked deferLoading, or false to send every tool on every call.

It resolves to an ExecutionResult: { text, reasoning?, messages, toolCalls, usage, stepUsage?, finishReason, steps, approvalId?, object?, outputError?, backgroundTasks?, budget?, guardrail?, agentName? }.