102 lines
3.6 KiB
TypeScript
102 lines
3.6 KiB
TypeScript
import type {
|
|
ISmartAiCacheOptions,
|
|
ToolSet,
|
|
ModelMessage,
|
|
LanguageModelV3,
|
|
ProviderOptions,
|
|
TSmartAiCacheRetention,
|
|
TSmartAiCacheSetting,
|
|
} from './plugins.js';
|
|
|
|
export type { ProviderOptions };
|
|
export type IAgentCacheOptions = ISmartAiCacheOptions;
|
|
export type TAgentCacheRetention = TSmartAiCacheRetention;
|
|
export type TAgentCacheSetting = TSmartAiCacheSetting;
|
|
|
|
export interface IAgentToolCallRecord {
|
|
toolName: string;
|
|
input: unknown;
|
|
output?: unknown;
|
|
error?: string;
|
|
}
|
|
|
|
export interface IAgentRunOptions {
|
|
/** The LanguageModelV3 to use — from smartai.getModel() */
|
|
model: LanguageModelV3;
|
|
/** Initial user message or task description */
|
|
prompt: string;
|
|
/** System prompt override */
|
|
system?: string;
|
|
/** Tools available to the agent */
|
|
tools?: ToolSet;
|
|
/** Provider-specific AI SDK request options passed through to streamText() */
|
|
providerOptions?: ProviderOptions;
|
|
/** Stable session id used as provider prompt-cache affinity key where supported. */
|
|
sessionId?: string;
|
|
/** Prompt-cache policy. Default: 'auto'. Set false to disable smartagent cache defaults. */
|
|
cache?: TAgentCacheSetting;
|
|
/**
|
|
* Maximum number of LLM↔tool round trips.
|
|
* Each step may execute multiple tools in parallel.
|
|
* Default: 20
|
|
*/
|
|
maxSteps?: number;
|
|
/** Prior conversation messages to include */
|
|
messages?: ModelMessage[];
|
|
/** Called for each streamed text delta */
|
|
onToken?: (delta: string) => void;
|
|
/** Called when the model starts a streamed reasoning summary */
|
|
onReasoningStart?: (id: string, providerMetadata?: unknown) => void;
|
|
/** Called for each streamed reasoning summary delta */
|
|
onReasoningDelta?: (id: string, delta: string, providerMetadata?: unknown) => void;
|
|
/** Called when a streamed reasoning summary completes */
|
|
onReasoningEnd?: (id: string, text: string, providerMetadata?: unknown) => void;
|
|
/** Called when a tool call starts */
|
|
onToolCall?: (toolName: string, input: unknown) => void;
|
|
/** Called when a tool call completes */
|
|
onToolResult?: (toolName: string, result: unknown) => void;
|
|
/**
|
|
* Validate the completed run. Return a string to reject the run and reprompt,
|
|
* or return void to accept the result.
|
|
*/
|
|
validateCompletion?: (result: IAgentRunResult) => Promise<string | void> | string | void;
|
|
/** Number of validation-triggered reprompts allowed. Default: 0 */
|
|
maxValidationRetries?: number;
|
|
/**
|
|
* Called when total token usage approaches the model's context limit.
|
|
* Receives the full message history and must return a compacted replacement.
|
|
* If not provided, runAgent throws a ContextOverflowError instead.
|
|
*/
|
|
onContextOverflow?: (messages: ModelMessage[]) => Promise<ModelMessage[]>;
|
|
/** AbortSignal to cancel the run mid-flight */
|
|
abort?: AbortSignal;
|
|
}
|
|
|
|
export interface IAgentRunResult {
|
|
/** Final text output from the model */
|
|
text: string;
|
|
/** All messages in the completed conversation */
|
|
messages: ModelMessage[];
|
|
/** Total steps taken */
|
|
steps: number;
|
|
/** Finish reason from the final step */
|
|
finishReason: string;
|
|
/** Accumulated token usage across all steps */
|
|
usage: {
|
|
inputTokens: number;
|
|
outputTokens: number;
|
|
totalTokens: number;
|
|
cacheReadTokens: number;
|
|
cacheWriteTokens: number;
|
|
};
|
|
/** Tool calls observed during the run, including inputs and outputs/errors when available */
|
|
toolCalls: IAgentToolCallRecord[];
|
|
}
|
|
|
|
export class ContextOverflowError extends Error {
|
|
constructor(message = 'Agent context limit reached and no onContextOverflow handler provided') {
|
|
super(message);
|
|
this.name = 'ContextOverflowError';
|
|
}
|
|
}
|