Dashboard|

Running agents

Run, stream, continue a conversation, and read the result.

run(agent, input, options?) runs an agent until it answers, running its tools along the way.

import { run } from 'cencori/agents';
 
const result = await run(support, 'Where is order 1042?');

Options
OptionUse it for
contextYour value for tools, guardrails and instructions. Never sent to Cencori
sessionIdContinue an earlier conversation
streamGet events as they happen
maxTurnsMost model calls the run may make (each tool round is one). Default 10
userYour end user's id: per-user quotas, billing and memory
memoryTurn on memory for a user: { userId }
metadataStrings stored on the session, shown in traces
signalAn AbortSignal to stop the run
apiKey, baseUrl, fetchOverride the key (default CENCORI_API_KEY), endpoint or fetch

The result
FieldWhat it is
finalOutputThe answer: text, or the parsed outputType. undefined while waiting on an approval
sessionIdThe Cencori session. Pass it back to continue
lastAgentThe agent that answered, after any handoffs
newItemsMessages, tool calls, tool outputs, handoffs and widgets, in order
interruptionsTool calls waiting for approval
stateA RunState to resume after deciding on them
usageInput, output and total tokens across the run

Streaming

 
const stream = run(support, 'Where is order 1042?', { stream: true });
 
for await (const event of stream) {
    switch (event.type) {
        case 'text_delta': process.stdout.write(event.delta); break;
        case 'tool_call': console.log('calling', event.toolName); break;
        case 'handoff': console.log(`${event.from} → ${event.to}`); break;
    }
}
 
const result = await stream.completed;
EventWhen
agent_updatedThe answering agent starts, or changes after a handoff
text_deltaText as it's written
tool_callThe model asked for a tool
tool_outputA tool returned
handoffThe conversation moved to another agent
widget_partial, widgetUI being drawn, then finished (Agent UI)
interruptionThe run is waiting for approvals

stream.toTextStream() yields only the text.

Conversations

Each run lives in a Cencori session. Pass sessionId to continue it: the agent sees the earlier turns.

const first = await run(support, 'Where is order 1042?');
const next = await run(support, 'Can you cancel it?', { sessionId: first.sessionId });

A session the user stops using expires on its own; idle sessions cost nothing.

Errors
ErrorWhen
MaxTurnsExceededErrorThe run hit maxTurns
GuardrailTripwireTriggeredA guardrail stopped the run
CencoriRunErrorCencori refused or failed a turn. Has status, code and sessionId
SchemaValidationErroroutputType didn't match

All extend AgentsError.

import { CencoriRunError, MaxTurnsExceededError } from 'cencori/agents';
 
try {
    await run(support, input);
} catch (error) {
    if (error instanceof CencoriRunError && error.status === 402) {
        // Out of credits
    }
}
Did you like the content?