@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/dist/src/ai/FlinkAgent.d.ts

@@ -0,0 +1,690 @@
+import { FlinkContext } from "../FlinkContext";
+import { FlinkToolFile, FlinkToolProps } from "./FlinkTool";
+import { type InstructionsReturn } from "./instructionFileLoader";
+export type { InstructionsReturn } from "./instructionFileLoader";
+import { LLMContentBlock, LLMMessage } from "./LLMAdapter";
+import { ToolExecutor } from "./ToolExecutor";
+/**
+ * Callback function for dynamic instruction generation
+ * Receives agent context and execution context to build custom instructions
+ *
+ * @param ctx - FlinkContext with access to repos, plugins, etc.
+ * @param agentContext - AgentExecuteContext with user, conversationId, metadata, etc.
+ * @returns Instructions string (can be async)
+ *
+ * @example
+ * const instructions = async (ctx, agentContext) => {
+ *     const profile = await ctx.repos.userRepo.getById(agentContext.user.id);
+ *     return `You are a support agent. Customer tier: ${profile.tier}`;
+ * };
+ */
+export type InstructionsCallback<Ctx extends FlinkContext> = (ctx: Ctx, agentContext: AgentExecuteContext) => Promise<string> | string;
+/**
+ * Agent instructions can be either a static string or a dynamic callback
+ */
+export type AgentInstructions<Ctx extends FlinkContext> = string | InstructionsCallback<Ctx>;
+/**
+ * Callback to determine if history compaction is needed
+ * Called before each LLM call to check if messages should be compacted
+ *
+ * @param messages - Current conversation messages
+ * @param step - Current step number (1-indexed)
+ * @returns true if compaction should be performed
+ *
+ * @example Check message count
+ * shouldCompact: (messages) => messages.length > 20
+ *
+ * @example Check total size in bytes
+ * shouldCompact: (messages) => {
+ *     const totalSize = JSON.stringify(messages).length;
+ *     return totalSize > 100_000; // ~100KB
+ * }
+ *
+ * @example Estimate token count (rough: 1 token ≈ 4 chars)
+ * shouldCompact: (messages) => {
+ *     const totalChars = messages.reduce((sum, m) => {
+ *         if (typeof m.content === 'string') return sum + m.content.length;
+ *         if (Array.isArray(m.content)) {
+ *             return sum + m.content.reduce((s, block) => {
+ *                 if (block.type === 'text') return s + block.text.length;
+ *                 if (block.type === 'tool_result') return s + JSON.stringify(block.content).length;
+ *                 return s;
+ *             }, 0);
+ *         }
+ *         return sum;
+ *     }, 0);
+ *     return totalChars > 60_000; // ~15k tokens
+ * }
+ */
+export type ShouldCompactCallback = (messages: LLMMessage[], step: number) => boolean | Promise<boolean>;
+/**
+ * Callback to compact conversation history
+ * Called when shouldCompact returns true
+ *
+ * @param messages - Current conversation messages to compact
+ * @param step - Current step number (1-indexed)
+ * @returns Compacted messages array (must not be empty)
+ *
+ * @example Sliding window (keep last N messages)
+ * compactHistory: (messages) => messages.slice(-10)
+ *
+ * @example Keep first message + last N (preserve initial context)
+ * compactHistory: (messages) => [messages[0], ...messages.slice(-8)]
+ *
+ * @example LLM-based summarization
+ * compactHistory: async (messages, step) => {
+ *     const oldMessages = messages.slice(0, -5);
+ *     const recentMessages = messages.slice(-5);
+ *     const summary = await this.summarize(oldMessages);
+ *     return [
+ *         { role: "user", content: `[Summary: ${summary}]` },
+ *         ...recentMessages
+ *     ];
+ * }
+ */
+export type CompactHistoryCallback = (messages: LLMMessage[], step: number) => Promise<LLMMessage[]> | LLMMessage[];
+export interface FlinkAgentProps<Ctx extends FlinkContext> {
+    id: string;
+    description: string;
+    /**
+     * Instructions that define the agent's behavior and personality.
+     * Can be a static string or a callback function that generates dynamic instructions.
+     *
+     * @example Static instructions
+     * instructions: "You are a helpful customer support agent."
+     *
+     * @example Dynamic instructions
+     * instructions: async (ctx, agentContext) => {
+     *     const user = await ctx.repos.userRepo.getById(agentContext.user.id);
+     *     return `You are a support agent. Customer: ${user.name}, Tier: ${user.tier}`;
+     * }
+     */
+    instructions: string | InstructionsCallback<Ctx>;
+    tools?: Array<string | FlinkToolFile | FlinkToolProps>;
+    model?: {
+        /**
+         * ID of the LLM adapter to use (must be registered in FlinkOptions.ai.llmAdapters)
+         * Examples: "anthropic", "openai", "anthropic-eu", "gpt4", etc.
+         * Defaults to "default" if not specified
+         */
+        adapterId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    limits?: {
+        maxSteps?: number;
+        timeoutMs?: number;
+    };
+    permissions?: string | string[] | ((user?: any) => boolean);
+    /**
+     * Callback to determine if history compaction is needed
+     * Called before each LLM call in the agentic loop
+     *
+     * When shouldCompact returns true, the framework calls compactHistory
+     * to reduce the message array size before the next LLM call
+     *
+     * If not provided, no compaction occurs (backward compatible)
+     */
+    shouldCompact?: ShouldCompactCallback;
+    /**
+     * Callback to compact conversation history
+     * Called when shouldCompact returns true
+     *
+     * Must return a non-empty array of messages
+     * If not provided but shouldCompact triggers, uses default strategy (keep last 10 messages)
+     */
+    compactHistory?: CompactHistoryCallback;
+    beforeRun?: (input: AgentExecuteInput<any>, context: AgentExecuteContext) => void | Promise<void>;
+    onStep?: (context: AgentStepContext) => void | Promise<void>;
+    afterRun?: (result: AgentExecuteResult, context: AgentFinishContext) => void | Promise<void>;
+}
+export type FlinkAgentFile<Ctx extends FlinkContext, ConversationCtx = any> = {
+    default?: new () => FlinkAgent<Ctx, ConversationCtx>;
+    __file?: string;
+};
+/**
+ * Base class for Flink agents (similar to FlinkRepo pattern)
+ *
+ * Agents extend this class and define their configuration as properties.
+ * Auto-registered by scanning src/agents/ directory.
+ *
+ * Tool references are validated at startup to ensure all referenced tools exist.
+ *
+ * Agents define their own domain-specific entry points that call `this.execute()`.
+ * This provides better type safety and developer experience than a generic `run()` method.
+ *
+ * ## Lifecycle Hooks
+ *
+ * Agents support lifecycle hooks for advanced orchestration:
+ * - `beforeRun`: Load conversation history, prepare context
+ * - `onStep`: Save state after each LLM turn
+ * - `afterRun`: Persist final conversation state
+ *
+ * ## Context Compaction
+ *
+ * Long-running agents can accumulate large message histories. Use context compaction
+ * to automatically manage history size during execution:
+ *
+ * ```typescript
+ * export default class MyAgent extends FlinkAgent<AppCtx> {
+ *     id = "my-agent";
+ *     description = "Agent with automatic context management";
+ *     instructions = "You are a helpful assistant...";
+ *
+ *     // Compact when history exceeds 20 messages
+ *     shouldCompact = (messages) => messages.length > 20;
+ *
+ *     // Keep only last 10 messages
+ *     compactHistory = (messages) => messages.slice(-10);
+ * }
+ * ```
+ *
+ * Compaction happens before each LLM call in the agentic loop, ensuring consistent
+ * token usage and preventing context window overflow.
+ *
+ * Example:
+ * ```typescript
+ * import { Tool as GetCarsTool } from "./tools/GetCarsTool";
+ * import * as UpdateCarTool from "./tools/UpdateCarTool";
+ *
+ * export default class CarAgent extends FlinkAgent<AppCtx> {
+ *     id = "car-agent"; // Optional: defaults to kebab-case class name "car-agent"
+ *     description = "Expert in car models";
+ *     instructions = "You are a car expert...";
+ *     tools = [
+ *         "get-cars-tool",      // String ID reference
+ *         GetCarsTool,          // Direct FlinkToolProps import
+ *         UpdateCarTool,        // Tool file reference
+ *     ];
+ *
+ *     // Domain-specific entry points with proper types
+ *     async searchByBrand(brand: string) {
+ *         const response = this.run({
+ *             message: `Find all ${brand} cars`
+ *         });
+ *         return await response.result;
+ *     }
+ *
+ *     async compareModels(model1: string, model2: string) {
+ *         const response = this.run({
+ *             message: `Compare ${model1} and ${model2}`
+ *         });
+ *         return await response.result;
+ *     }
+ *
+ *     // Lifecycle hook: Load conversation history
+ *     protected async beforeRun(input, context) {
+ *         if (context.conversationId) {
+ *             const conv = await this.ctx.repos.conversationRepo.getById(context.conversationId);
+ *             input.history = conv.messages;
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export declare abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any> {
+    ctx: Ctx;
+    private runner?;
+    private _boundUser?;
+    private _boundUserPermissions?;
+    private _boundConversationContext?;
+    private _llmAdapters?;
+    private _tools?;
+    private _observer?;
+    abstract id: string;
+    abstract description: string;
+    /**
+     * Define the agent's instructions. Override this method in your agent subclass.
+     *
+     * `ctx` is automatically typed as your app's context — no annotation needed.
+     *
+     * Supported return values:
+     * - `string` — Plain text used as-is
+     * - `string` ending with a known text extension (`.md`, `.txt`, `.yaml`, `.yml`, `.xml`, …) — Auto-loaded from disk (project-root-relative)
+     * - `{ file, params? }` — Explicitly load a file (any extension) with optional Handlebars template params
+     *
+     * @example Plain text
+     * instructions() {
+     *     return "You are a helpful car assistant.";
+     * }
+     *
+     * @example Dynamic instructions using ctx and agentContext
+     * async instructions(ctx, agentContext) {
+     *     const user = await ctx.repos.userRepo.getById(agentContext.user?.id);
+     *     return `You are a support agent for ${user.name}.`;
+     * }
+     *
+     * @example Auto-load file by extension (.md, .txt, .yaml, .yml, .xml, … — path relative to project root)
+     * instructions() {
+     *     return "src/agents/instructions/car-agent.md";
+     * }
+     *
+     * @example File with template params
+     * async instructions(ctx, agentContext) {
+     *     return {
+     *         file: "src/agents/instructions/support.md",
+     *         params: {
+     *             customerTier: agentContext.user?.tier || "standard",
+     *             isBusinessHours: new Date().getHours() >= 9,
+     *         },
+     *     };
+     * }
+     *
+     * @example Agent-file-relative path (use agentInstructions helper)
+     * instructions(ctx, agentContext) {
+     *     return agentInstructions("./instructions/support.md", { date: new Date() })(ctx, agentContext);
+     * }
+     */
+    abstract instructions(ctx: Ctx, agentContext: AgentExecuteContext): Promise<InstructionsReturn> | InstructionsReturn;
+    tools?: Array<string | FlinkToolFile | FlinkToolProps>;
+    model?: {
+        adapterId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    limits?: {
+        maxSteps?: number;
+        timeoutMs?: number;
+    };
+    permissions?: string | string[] | ((user?: any) => boolean);
+    protected shouldCompact?: ShouldCompactCallback;
+    protected compactHistory?: CompactHistoryCallback;
+    /**
+     * Internal initialization called by FlinkApp
+     * @internal
+     */
+    __init(llmAdapters: Map<string, any>, tools: {
+        [x: string]: ToolExecutor<Ctx>;
+    }, observer?: AgentObserver): void;
+    /**
+     * Bind a user to this agent for permission checks
+     *
+     * This creates a new agent instance with the user bound, allowing clean API:
+     * ```typescript
+     * const result = await ctx.agents.carAgent
+     *     .withUser(req.user)
+     *     .searchByBrand("Volvo");
+     * ```
+     *
+     * The bound user is used for:
+     * - Agent-level permission checks
+     * - Tool filtering (only allowed tools shown to LLM)
+     * - Tool-level permission checks
+     */
+    withUser(user: any): this;
+    /**
+     * Bind resolved permissions to this agent for permission checks
+     *
+     * This creates a new agent instance with permissions bound, allowing clean API:
+     * ```typescript
+     * const result = await ctx.agents.carAgent
+     *     .withUser(req.user)
+     *     .withPermissions(req.userPermissions) // Resolved permissions from auth plugin
+     *     .searchByBrand("Volvo");
+     * ```
+     *
+     * The bound permissions are used for:
+     * - Tool filtering (only allowed tools shown to LLM)
+     * - Tool-level permission checks
+     *
+     * Permissions are typically populated by auth plugins during authentication
+     * based on roles, dynamic roles, or custom permission resolution.
+     */
+    withPermissions(userPermissions?: string[]): this;
+    /**
+     * Override the LLM adapter for this agent
+     *
+     * This creates a new agent instance with a different LLM adapter, allowing runtime selection:
+     * ```typescript
+     * const result = await ctx.agents.carAgent
+     *     .withUser(req.user)
+     *     .withLlm("fast")  // Use fast LLM instead of default
+     *     .searchByBrand("Volvo");
+     * ```
+     *
+     * The LLM adapter ID must be registered in FlinkApp's ai.llms configuration.
+     *
+     * @param adapterId - The ID of the LLM adapter to use (e.g., "default", "fake", "fast", "anthropic")
+     * @returns A new agent instance with the specified LLM adapter
+     */
+    withLlm(adapterId: string): this;
+    /**
+     * Bind conversation context to this agent for passing to tools
+     *
+     * This creates a new agent instance with the conversation context bound, allowing clean API:
+     * ```typescript
+     * const result = await ctx.agents.carAgent
+     *     .withUser(req.user)
+     *     .withConversationContext({ sessionId: req.session.id, featureFlags: req.flags })
+     *     .searchByBrand("Volvo");
+     * ```
+     *
+     * The bound conversation context is used for:
+     * - Passing request-scoped data to tools
+     * - Sharing state between agent and tools without polluting global context
+     * - Propagating to sub-agents automatically
+     */
+    withConversationContext(conversationContext: ConversationCtx): this;
+    /**
+     * Public execution method for external callers (handlers, sub-agents, etc.)
+     *
+     * Use this when calling an agent from outside the agent class.
+     * For internal use within agent subclasses, use `execute()` instead.
+     */
+    run(input: AgentExecuteInput<ConversationCtx>): AgentResponse;
+    /**
+     * Internal execution method - supports both awaiting and streaming
+     *
+     * Uses lazy generator pattern (similar to Vercel AI SDK) to allow
+     * multiple consumption without re-execution.
+     *
+     * Agents call this method from their run() implementation to execute the AI logic.
+     *
+     * Examples:
+     *   const response = this.execute({ message: "Hello" });
+     *   const result = await response.result;  // Await final result
+     *   for await (const text of response.textStream) { ... }  // Stream text
+     *   for await (const chunk of response.fullStream) { ... }  // Stream all events
+     */
+    protected execute(input: AgentExecuteInput<ConversationCtx>): AgentResponse;
+    /**
+     * Called before agent execution starts
+     * Use this to load conversation history, prepare context, etc.
+     *
+     * @example
+     * protected async beforeRun(input: AgentExecuteInput, context: AgentExecuteContext) {
+     *     if (input.conversationId) {
+     *         const conv = await this.ctx.repos.conversationRepo.getById(input.conversationId);
+     *         input.history = conv?.messages;
+     *     }
+     * }
+     */
+    protected beforeRun?(input: AgentExecuteInput<ConversationCtx>, context: AgentExecuteContext): void | Promise<void>;
+    /**
+     * Called after each step (LLM call + tool executions)
+     * Use this to save intermediate state, emit progress events, etc.
+     *
+     * @example
+     * protected async onStep(context: AgentStepContext) {
+     *     if (context.conversationId) {
+     *         await this.saveConversationState(context.conversationId, context.messages);
+     *     }
+     * }
+     */
+    protected onStep?(context: AgentStepContext): void | Promise<void>;
+    /**
+     * Called when agent execution completes
+     * This is where you typically save the final conversation state
+     *
+     * @example
+     * protected async afterRun(result: AgentExecuteResult, context: AgentFinishContext) {
+     *     if (context.conversationId && !context.isSubAgent) {
+     *         await this.ctx.repos.conversationRepo.save({
+     *             id: context.conversationId,
+     *             messages: context.messages,
+     *             result
+     *         });
+     *     }
+     * }
+     */
+    protected afterRun?(result: AgentExecuteResult, context: AgentFinishContext): void | Promise<void>;
+    /**
+     * Consume stream as final result (for await pattern)
+     */
+    private consumeAsResult;
+    /**
+     * Consume stream as text-only stream (for simple streaming UX)
+     */
+    private consumeAsTextStream;
+    private getRunner;
+    /**
+     * Get agent id - uses explicit id property or falls back to kebab-case class name
+     *
+     * Examples:
+     * - CarAgent → car-agent
+     * - APIAgent → api-agent
+     * - HTMLParserAgent → html-parser-agent
+     */
+    private getAgentId;
+    private toAgentProps;
+    private resolveTools;
+    private checkPermissionsSync;
+}
+/**
+ * Execution context shared across agent lifecycle hooks
+ */
+export interface AgentExecuteContext {
+    agentId: string;
+    conversationId?: string;
+    user?: any;
+    metadata?: Record<string, any>;
+    conversationContext?: any;
+}
+/**
+ * Context for onStep hook - includes current conversation state
+ */
+export interface AgentStepContext extends AgentExecuteContext {
+    step: number;
+    maxSteps: number;
+    messages: LLMMessage[];
+}
+/**
+ * Context for afterRun hook - includes final conversation and result
+ */
+export interface AgentFinishContext extends AgentExecuteContext {
+    messages: LLMMessage[];
+    result: AgentExecuteResult;
+}
+/**
+ * Message structure for agent conversations
+ * Supports both simple strings and structured message arrays
+ */
+export type Message = {
+    role: "user";
+    content: string;
+} | {
+    role: "assistant";
+    content: string;
+    toolCalls?: ToolCall[];
+} | {
+    role: "tool";
+    toolCallId: string;
+    toolName: string;
+    result: string;
+};
+export interface ToolCall {
+    id: string;
+    name: string;
+    input: any;
+}
+export interface AgentExecuteInput<ConversationCtx = any> {
+    message: string | LLMContentBlock[] | Message[];
+    user?: any;
+    userPermissions?: string[];
+    /**
+     * Optional ID for tracking multi-turn conversations
+     * Used in lifecycle hooks (beforeRun/onStep/afterRun) to load/save conversation state
+     * @example "conv_abc123" - caller-provided ID to persist conversation history
+     */
+    conversationId?: string;
+    /**
+     * Transient, conversation-scoped data that flows from agent to tools
+     * Examples: session IDs, feature flags, request tracing, tenant config
+     * Typed by agent's ConversationCtx parameter
+     */
+    conversationContext?: ConversationCtx;
+    /**
+     * Previous conversation messages for context, in chronological order (oldest first).
+     * The new `message` will be appended after these history messages.
+     * Agent can load this in beforeRun hook based on conversationId.
+     */
+    history?: Message[];
+    /**
+     * Provider-specific metadata for optimizations like server-side persistence
+     *
+     * Examples:
+     * - OpenAI Responses API: `{ openai: { previousResponseId: "resp_123" } }`
+     * - Anthropic: `{ anthropic: { ... } }`
+     *
+     * When provided, adapters may use this instead of full history for better performance
+     */
+    providerMetadata?: Record<string, any>;
+    /**
+     * Arbitrary metadata that flows through the execution
+     * Available in all callbacks
+     */
+    metadata?: Record<string, any>;
+    options?: {
+        maxSteps?: number;
+        timeoutMs?: number;
+    };
+}
+export interface AgentExecuteResult {
+    /**
+     * Framework-generated unique ID for this agent execution.
+     * Matches the `runId` emitted in AgentObserver events, enabling apps to
+     * correlate persisted results with observer traces.
+     */
+    runId: string;
+    message: string;
+    toolCalls: Array<{
+        name: string;
+        input: any;
+        output: any;
+        error?: string;
+    }>;
+    stepsUsed: number;
+    usage?: import("./LLMAdapter").LLMUsage;
+    stoppedEarly: boolean;
+    /**
+     * Provider-specific metadata for conversation continuation
+     *
+     * Examples:
+     * - OpenAI Responses API: `{ openai: { responseId: "resp_123" } }`
+     * - Anthropic: `{ anthropic: { ... } }`
+     *
+     * Use this for next turn's `providerMetadata` input for optimized server-side history
+     */
+    providerMetadata?: Record<string, any>;
+}
+/**
+ * Stream chunk types for different streaming events
+ *
+ * Phase 1: Only "complete" event is emitted
+ * Phase 2: Will emit real-time "text_delta", "tool_call_start", and "tool_call_result" events
+ */
+export type StreamChunk = {
+    type: "text_delta";
+    delta: string;
+} | {
+    type: "tool_call_start";
+    toolCall: ToolCall;
+} | {
+    type: "tool_call_result";
+    toolCall: ToolCall;
+    output: any;
+    error?: string;
+} | {
+    type: "complete";
+    result: AgentExecuteResult;
+};
+/**
+ * Unified response that supports both awaiting and streaming
+ */
+export interface AgentResponse {
+    result: Promise<AgentExecuteResult>;
+    textStream: AsyncGenerator<string>;
+    fullStream: AsyncGenerator<StreamChunk>;
+}
+/**
+ * Event fired once per agent execution, before the first LLM call.
+ * Contains the resolved system instructions and the initial message array
+ * (post-history, pre-compaction, pre-tool-filtering).
+ */
+export interface AgentObserverRunEvent {
+    runId: string;
+    agentId: string;
+    instructions: string;
+    input: AgentExecuteInput;
+    messages: LLMMessage[];
+    tools: string[];
+    model: {
+        adapterId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    context: AgentExecuteContext;
+}
+/**
+ * Event fired immediately before each LLM call in the agentic loop.
+ * Reflects the messages and tools actually sent to the model after
+ * compaction and per-step permission filtering.
+ */
+export interface AgentObserverLlmCallEvent {
+    runId: string;
+    agentId: string;
+    step: number;
+    maxSteps: number;
+    instructions: string;
+    messages: LLMMessage[];
+    tools: string[];
+    model: {
+        adapterId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    context: AgentExecuteContext;
+}
+/**
+ * Event fired after each step (LLM call + tool executions) completes.
+ * `toolCalls` contains only the tool calls executed during this step.
+ */
+export interface AgentObserverStepEvent {
+    runId: string;
+    agentId: string;
+    step: number;
+    maxSteps: number;
+    messages: LLMMessage[];
+    assistantText?: string;
+    toolCalls: AgentExecuteResult["toolCalls"];
+    usage?: import("./LLMAdapter").LLMUsage;
+    context: AgentExecuteContext;
+}
+/**
+ * Event fired when an agent execution completes (successfully or with error).
+ * On error, `result` contains whatever was accumulated before the throw.
+ */
+export interface AgentObserverFinishEvent {
+    runId: string;
+    agentId: string;
+    result: AgentExecuteResult;
+    messages: LLMMessage[];
+    durationMs: number;
+    error?: string;
+    context: AgentExecuteContext;
+}
+/**
+ * Global agent observer for app-level tracing, APM, cost accounting, dev tools, etc.
+ *
+ * Register once on `FlinkOptions.ai.observer`; fires for every agent execution in the app.
+ *
+ * Observer callbacks are invoked fire-and-forget: they may return a Promise but the
+ * framework does not await them, and any thrown/rejected errors are caught and logged
+ * without affecting agent execution. Observers are read-only — they must not mutate
+ * inputs, messages, or results. Use the per-agent `beforeRun`/`onStep`/`afterRun` hooks
+ * for business logic that needs to block or mutate.
+ *
+ * Typical use cases:
+ * - Persisted traces for a dev tools page (correlate via `context.metadata`)
+ * - OpenTelemetry / Sentry integration
+ * - Cost accounting and token-usage dashboards
+ *
+ * All events share a stable `runId` per execution so persisted records can be joined
+ * across events. The same `runId` is returned on `AgentExecuteResult.runId`.
+ */
+export interface AgentObserver {
+    onRun?(event: AgentObserverRunEvent): void | Promise<void>;
+    onLlmCall?(event: AgentObserverLlmCallEvent): void | Promise<void>;
+    onStep?(event: AgentObserverStepEvent): void | Promise<void>;
+    onFinish?(event: AgentObserverFinishEvent): void | Promise<void>;
+}