Agent
Agent runtime, builders, prompt requests, hooks, and run events.
Import from @anvia/core or @anvia/core/agent.
Agent
class Agent<M extends CompletionModel = CompletionModel> {
readonly id: string;
readonly name?: string;
readonly description?: string;
readonly model: M;
readonly instructions?: string;
readonly staticContext: Document[];
readonly temperature?: number;
readonly maxTokens?: number;
readonly additionalParams?: JsonValue;
readonly toolSet: ToolSet;
readonly toolChoice?: ToolChoice;
readonly defaultMaxTurns?: number;
readonly hook?: PromptHook;
readonly outputSchema?: JsonObject;
readonly observers: AgentObserverRegistration[];
readonly dynamicContexts: DynamicContextRegistration[];
readonly dynamicTools: DynamicToolRegistration[];
readonly middlewares: AgentMiddleware[];
/** @deprecated Use middlewares instead. */
readonly toolMiddlewares: ToolMiddleware[];
readonly memory?: MemoryRegistration;
readonly eventStore?: AgentEventStoreRegistration;
constructor(options: AgentOptions<M>);
prompt(prompt: string | Message | Message[]): PromptRequest<M>;
session(sessionId: string, options?: SessionOptions): AgentSession<M>;
asTool(options: AgentToolOptions): Tool<{ prompt: string }, string>;
getTool(toolName: string): Tool | undefined;
callTool(toolName: string, args: string, context?: ToolCallContext): Promise<string>;
}Purpose: immutable runnable agent configuration around one completion model.
Return behavior: prompt(...) creates a mutable PromptRequest; prompt(Message[]) treats the last message as the active prompt and earlier messages as stateless history; session(...) creates a durable memory-backed session; asTool(...) exposes the agent as a tool that returns the nested agent output string. asTool({ stream: true }) forwards child stream events when the parent run uses .stream().
Notable errors: the constructor throws TypeError when id is not a non-empty string. asTool(...) forwards errors from the nested prompt run.
AgentOptions
type AgentOptions<M extends CompletionModel = CompletionModel> = {
id: string;
name?: string;
description?: string;
model: M;
instructions?: string;
staticContext?: Document[];
temperature?: number;
maxTokens?: number;
additionalParams?: JsonValue;
toolSet?: ToolSet;
toolChoice?: ToolChoice;
defaultMaxTurns?: number;
hook?: PromptHook;
outputSchema?: JsonObject;
observers?: AgentObserverRegistration[];
dynamicContexts?: DynamicContextRegistration[];
dynamicTools?: DynamicToolRegistration[];
middlewares?: AgentMiddleware[];
/** @deprecated Use middlewares instead. */
toolMiddlewares?: ToolMiddleware[];
memory?: MemoryRegistration;
eventStore?: AgentEventStoreRegistration;
};Purpose: constructor contract for Agent. Prefer AgentBuilder for application code.
Return behavior: used only as input to new Agent(...).
Notable errors: invalid id is rejected by the Agent constructor.
AgentBuilder
class AgentBuilder<M extends CompletionModel = CompletionModel> {
constructor(agentId: string, completionModel: M);
name(name: string): this;
description(description: string): this;
instructions(instructions: string): this;
context(text: string, id?: string): this;
dynamicContext<T>(index: VectorSearchIndex<T>, options: DynamicContextOptions<T>): this;
dynamicTools(index: VectorSearchIndex<ToolSearchDocument>, options: DynamicToolOptions): this;
tool(tool: Tool): this;
tools(tools: Tool[]): this;
useToolSet(toolSet: ToolSet): this;
mcp(servers: McpServer[]): this;
skills(skillSet: SkillSet): this;
temperature(temperature: number): this;
maxTokens(maxTokens: number): this;
additionalParams(params: JsonValue): this;
toolChoice(toolChoice: ToolChoice): this;
defaultMaxTurns(defaultMaxTurns: number): this;
hook(hook: PromptHook): this;
middleware(middleware: AgentMiddleware): this;
middlewares(middlewares: AgentMiddleware[]): this;
/** @deprecated Use middleware instead. */
toolMiddleware(middleware: ToolMiddleware): this;
/** @deprecated Use middlewares instead. */
toolMiddlewares(middlewares: ToolMiddleware[]): this;
observe(observer: AgentObserver, options?: ObserveOptions): this;
approvals(options: ToolApprovalsOptions): this;
memory(store: MemoryStore, options?: MemoryOptions): this;
eventStore(store: AgentEventStore, options?: AgentEventStoreOptions): this;
outputSchema(schema: ZodSchema): this;
build(): Agent<M>;
}Purpose: fluent builder for agent configuration.
Return behavior: all mutator methods return this; build() returns an Agent.
Notable errors: the constructor rejects an empty agent id. outputSchema(...) can throw if the schema cannot be converted to provider JSON schema.
AgentSession
class AgentSession<M extends CompletionModel = CompletionModel> {
prompt(prompt: string | Message): PromptRequest<M>;
messages(): Promise<Message[]>;
clear(): Promise<void>;
}Purpose: durable conversation scope created by agent.session(sessionId, options?).
Return behavior: prompt(...) loads messages from the configured memory store before the run and appends new messages according to the agent memory policy. Session prompts do not accept Message[]; use agent.prompt(Message[]) for explicit stateless transcripts.
Notable errors: agent.session(...) throws when no memory store is configured or when the session id is empty.
Memory
type MemorySavePolicy = "message" | "turn" | "run";
type MemoryContext = {
sessionId: string;
userId?: string;
metadata?: JsonObject;
};
interface MemoryStore {
load(context: MemoryContext): Promise<Message[]>;
append(input: {
context: MemoryContext;
runId: string;
turn: number;
messages: Message[];
}): Promise<void>;
clear(context: MemoryContext): Promise<void>;
recordError?(input: {
context: MemoryContext;
runId: string;
error: unknown;
messages: Message[];
}): Promise<void>;
}
type MemoryOptions = {
savePolicy?: MemorySavePolicy;
};Purpose: configure durable conversation storage for agent.session(...).
Return behavior: savePolicy defaults to "message". Core provides the interface; applications provide the storage implementation.
AgentEventStore
interface AgentEventStore {
append(input: AgentEventAppendInput): Promise<void>;
load(runId: string): Promise<AgentEventRecord[]>;
clear?(runId: string): Promise<void>;
}
type AgentEventStoreInclude = "all" | "agent_tool_events";
type AgentEventStoreOptions = {
include?: AgentEventStoreInclude;
};
type AgentEventAppendInput = {
runId: string;
agentId: string;
agentName?: string;
turn?: number;
toolName?: string;
toolCallId?: string;
internalCallId?: string;
event: unknown;
};
type AgentEventRecord = AgentEventAppendInput & {
createdAt?: Date;
};Purpose: persist runtime stream events for replay, debugging, or local inspection.
Return behavior: include: "all" stores parent and child stream events. include: "agent_tool_events" stores only nested child-agent events from streaming agent-tools. Event storage is separate from MemoryStore, which remains transcript-oriented.
Dynamic Tools
type DynamicToolOptions = {
topK: number;
threshold?: number;
filter?: VectorFilter;
};
type DynamicToolRegistration = {
index: VectorSearchIndex<ToolSearchDocument>;
options: DynamicToolOptions;
};Purpose: retrieve relevant tool definitions before each model turn.
Return behavior: static tools are always sent; matching dynamic tools are added after static tools and deduped by name.
Notable errors: errors from the vector index surface before the model request is sent.
PromptRequest
class PromptRequest<M extends CompletionModel = CompletionModel> {
static fromAgent<M extends CompletionModel>(
agent: Agent<M>,
prompt: string | Message | Message[],
): PromptRequest<M>;
maxTurns(maxTurns: number): this;
withHook(hook: PromptHook): this;
/** @deprecated Use withHook instead. */
requestHook(hook: PromptHook): this;
withToolConcurrency(concurrency: number): this;
withMiddleware(middleware: AgentMiddleware): this;
withMiddlewares(middlewares: AgentMiddleware[]): this;
/** @deprecated Use withMiddleware instead. */
withToolMiddleware(middleware: ToolMiddleware): this;
/** @deprecated Use withMiddlewares instead. */
withToolMiddlewares(middlewares: ToolMiddleware[]): this;
withTrace(trace: AgentTraceOptions): this;
approvals(options: ToolApprovalsOptions): this;
send(): Promise<PromptResponse>;
stream(): AsyncIterable<AgentStreamEvent>;
readableStream(options?: ReadableStreamOptions): ReadableStream<AgentStreamEvent>;
}Purpose: per-run request state for an agent prompt.
Return behavior: send() resolves a final PromptResponse; stream() yields run events and ends with a final event; readableStream() wraps the stream in a web stream.
Notable errors: throws MaxTurnsError when the tool loop exceeds the configured turn limit, PromptCancelledError when a hook terminates the run, ToolApprovalRequiredError when a protected tool call has no approval handler, and a plain Error when streaming is requested for a non-streaming model.
PromptResponse
type PromptResponse = {
output: string;
usage: Usage;
messages: Message[];
trace?: AgentTraceInfo;
};Purpose: final non-streaming agent result.
Return behavior: messages contains the new run messages, not the full prior history unless history was manually included.
Notable errors: none directly.
AgentStreamEvent
type AgentChildStreamEvent = Exclude<AgentStreamEvent, { type: "agent_tool_event" }>;
type AgentStreamEvent =
| { type: "turn_start"; turn: number; prompt: Message; history: Message[] }
| { type: "text_delta"; turn: number; delta: string }
| { type: "reasoning_delta"; turn: number; delta: string; id?: string; contentType?: "text" | "summary" | "encrypted" | "redacted"; signature?: string }
| { type: "tool_call"; turn: number; toolCall: ToolCall }
| { type: "tool_result"; turn: number; toolName: string; toolCallId?: string; internalCallId: string; args: string; result: string }
| { type: "agent_tool_event"; turn: number; toolName: string; toolCallId?: string; internalCallId: string; agentId: string; agentName?: string; event: AgentChildStreamEvent }
| { type: "turn_end"; turn: number; response: CompletionResponse }
| { type: "final"; runId: string; output: string; usage: Usage; messages: Message[]; trace?: AgentTraceInfo }
| { type: "error"; error: unknown };Purpose: streaming event union for observing agent execution.
Return behavior: emitted by PromptRequest.stream() and readableStream(). agent_tool_event appears when a child agent is exposed with asTool({ stream: true }). The terminal final event includes runId, which can be used with AgentEventStore.load(...).
Notable errors: terminal failures are yielded as { type: "error" } and also originate from the same conditions as send().
Hooks
type HookAction = { type: "continue" } | { type: "terminate"; reason: string };
type ToolApprovalRequestOptions = {
reason?: string;
rejectMessage?: string;
};
type ToolCallHookAction =
| { type: "continue" }
| { type: "skip"; reason: string }
| { type: "terminate"; reason: string }
| ({ type: "approval_request" } & ToolApprovalRequestOptions);
type RunControl = {
continue(): HookAction;
cancel(reason: string): HookAction;
};
type ToolCallControl = {
run(): ToolCallHookAction;
skip(reason: string): ToolCallHookAction;
cancel(reason: string): ToolCallHookAction;
requestApproval(options?: ToolApprovalRequestOptions): ToolCallHookAction;
};
type HookResult = HookAction | undefined;
type ToolCallHookResult = ToolCallHookAction | undefined;
type CompletionCallHookArgs = {
prompt: Message;
history: Message[];
run: RunControl;
};
type RunStartHookArgs = {
prompt: Message;
history: Message[];
maxTurns: number;
run: RunControl;
};
type RunEndHookArgs = {
output: string;
usage: Usage;
messages: Message[];
run: RunControl;
};
type RunErrorHookArgs = {
error: unknown;
usage: Usage;
messages: Message[];
run: RunControl;
};
type TurnStartHookArgs = {
turn: number;
prompt: Message;
history: Message[];
run: RunControl;
};
type TurnEndHookArgs<RawResponse = unknown> = {
turn: number;
response: CompletionResponse<RawResponse>;
run: RunControl;
};
type CompletionResponseHookArgs<RawResponse = unknown> = {
prompt: Message;
response: CompletionResponse<RawResponse>;
run: RunControl;
};
type CompletionErrorHookArgs = {
prompt: Message;
error: unknown;
run: RunControl;
};
type ToolHookArgs = {
toolName: string;
toolCallId?: string;
internalCallId: string;
args: string;
};
type ToolCallHookArgs = ToolHookArgs & {
tool: ToolCallControl;
};
type ToolResultHookArgs = ToolHookArgs & {
result: string;
run: RunControl;
};
type ToolErrorHookArgs = ToolHookArgs & {
error: unknown;
run: RunControl;
};
const runControl: RunControl;
const toolCallControl: ToolCallControl;
function createHook<RawResponse = unknown>(hook: PromptHook<RawResponse>): PromptHook<RawResponse>;
function cancelPrompt(reason: string): HookAction;
function skipTool(reason: string): ToolCallHookAction;
function requestToolApproval(options?: ToolApprovalRequestOptions): ToolCallHookAction;Purpose: intercept run lifecycle, turn lifecycle, completion calls, completion responses, completion errors, tool calls, tool results, and tool errors.
Return behavior: callback controls such as tool.run(), tool.skip(...), tool.cancel(...), tool.requestApproval(...), run.continue(), and run.cancel(...) create actions consumed by PromptRequest. The low-level cancelPrompt(...), skipTool(...), and requestToolApproval(...) helpers are also available.
Notable errors: a terminating hook produces PromptCancelledError. If tool.requestApproval(...) reaches core without Studio or another approval handler, the request throws ToolApprovalRequiredError.
Tool Approvals
type ToolApprovalDecision =
| boolean
| { approved: true; reason?: string }
| { approved: false; reason?: string; rejectMessage?: string };
type ToolApprovalsOptions = {
handler(request: ToolApprovalRequest): ToolApprovalDecision | Promise<ToolApprovalDecision>;
};Purpose: provide the decision source for ToolApprovalPolicy and hook-based tool.requestApproval(...) requests.
Return behavior: configure with AgentBuilder.approvals(...) or per request with prompt(...).approvals(...); request-level approvals override agent-level approvals. Approved decisions run the tool. Rejected decisions skip execution and return the rejection text as the tool result.
Notable errors: if a tool call requires approval and no handler is configured, core throws ToolApprovalRequiredError.
Error Classes
class MaxTurnsError extends Error {
readonly maxTurns: number;
readonly chatHistory: Message[];
readonly prompt: Message;
}
class PromptCancelledError extends Error {
readonly chatHistory: Message[];
readonly reason: string;
}
class ToolApprovalRequiredError extends Error {
readonly request: ToolApprovalRequest;
}Purpose: typed agent-run failures.
Return behavior: thrown by PromptRequest.
Notable errors: these are the notable agent errors.
Constants and Small Types
const DEFAULT_MAX_TURNS = 20;
type AgentToolOptions = {
name: string;
description?: string;
maxTurns?: number;
stream?: boolean;
};
type DynamicContextOptions<T = unknown> = {
topK: number;
threshold?: number;
filter?: VectorFilter;
format?: (result: VectorSearchResult<T>) => Document;
};
type DynamicContextRegistration<T = unknown> = {
index: VectorSearchIndex<T>;
options: DynamicContextOptions<T>;
};Purpose: defaults and supporting agent configuration types.
Return behavior: used as builder or constructor inputs.
Notable errors: none directly.
For workflow guidance, see Creating Agents.