/**
 * Unified Agent class — a single agent primitive that supports both
 * standalone usage (generate, stream, asTool) and runtime-orchestrated
 * usage (run, canHandle, initialize, cleanup).
 *
 * Standalone agents can be used directly via {@link Agent.generate} or
 * {@link Agent.stream}. They can also be converted into tools via
 * {@link Agent.asTool}, enabling the "agent-as-tool" composition pattern.
 *
 * When used with a Runtime, the {@link Agent.run} method provides the
 * default LLM agent implementation (streaming text with tool support).
 * Subclasses like FlowAgent, TriageAgent, and CompositeAgent override
 * `run()` with their specific logic.
 *
 * @module
 */
import { type LanguageModel, type ToolSet } from 'ai';
import { z } from 'zod';
import { createTool } from '../tools/Tool.js';
import type { AgentPrompt } from '../prompts/AgentPrompt.js';
import type { AgentContext, AgentStreamPart as RuntimeAgentStreamPart } from '../types/index.js';
/**
 * Configuration for creating an {@link Agent}.
 */
export interface AgentConstructorConfig {
    /** Unique identifier for this agent. */
    id: string;
    /** Human-readable name. Defaults to `id`. */
    name?: string;
    /** Description of the agent's capabilities (used by `.asTool()`). */
    description?: string;
    /** The language model to use (e.g. `openai('gpt-4o')`). */
    model: LanguageModel;
    /** System prompt — either a plain string or an {@link AgentPrompt} instance. */
    prompt: string | AgentPrompt;
    /** Optional tool set available to the agent during generation. */
    tools?: ToolSet;
    /** Maximum number of tool-call steps before stopping. Defaults to 10. */
    maxSteps?: number;
    /** List of agent IDs this agent can hand off to. Defaults to []. */
    canHandoffTo?: string[];
}
/**
 * Options for {@link Agent.generate} and {@link Agent.stream}.
 */
export interface GenerateOptions {
    /** Prior conversation messages to prepend before the user input. */
    messages?: Array<{
        role: string;
        content: string;
    }>;
    /** Abort signal for cancelling the generation. */
    abortSignal?: AbortSignal;
}
/**
 * Result returned by {@link Agent.generate}.
 */
export interface GenerateResult {
    /** The final text response from the agent. */
    text: string;
    /** Token usage breakdown, if available. */
    usage?: {
        inputTokens: number | undefined;
        outputTokens: number | undefined;
    };
    /** Reason the generation finished (e.g. 'stop', 'tool-calls'). */
    finishReason: string;
}
/**
 * A single part emitted by {@link Agent.stream}.
 */
export interface AgentStreamPart {
    type: 'text-delta' | 'tool-call' | 'tool-result' | 'error' | 'finish-step' | 'done';
    text?: string;
    toolName?: string;
    toolCallId?: string;
    args?: unknown;
    result?: unknown;
    error?: string;
}
/**
 * Configuration for {@link Agent.asTool}.
 */
export interface AsToolConfig {
    /** Override the tool description. Defaults to the agent's description. */
    description?: string;
    /** Custom input schema. Defaults to `z.object({ query: z.string() })`. */
    inputSchema?: z.ZodType;
    /** How to handle execution errors. Defaults to 'return_error'. */
    errorBehavior?: 'throw' | 'return_error';
}
/**
 * A unified agent that supports both standalone usage (generate/stream/asTool)
 * and runtime-orchestrated usage (run/canHandle/initialize/cleanup).
 *
 * @example
 * ```ts
 * const agent = new Agent({
 *   id: 'helper',
 *   model: openai('gpt-4o'),
 *   prompt: 'You are a helpful assistant.',
 * });
 *
 * // One-shot generation
 * const result = await agent.generate('Hello!');
 * console.log(result.text);
 *
 * // Streaming
 * for await (const part of agent.stream('Hello!')) {
 *   if (part.type === 'text-delta') process.stdout.write(part.text!);
 * }
 *
 * // Use as a tool in another agent
 * const tool = agent.asTool({ description: 'Ask the helper' });
 * ```
 */
export declare class Agent {
    /** Unique identifier. */
    readonly id: string;
    /** Human-readable name. */
    readonly name: string;
    /** Description of capabilities. */
    readonly description: string;
    /** The language model backing this agent. */
    readonly model: LanguageModel;
    /** System prompt (string or AgentPrompt). */
    readonly prompt: string | AgentPrompt;
    /** Tools available to the agent. */
    readonly tools: ToolSet;
    /** Maximum tool-call steps per generation. */
    readonly maxSteps: number;
    /** List of agent IDs this agent can hand off to. */
    readonly canHandoffTo: string[];
    constructor(config: AgentConstructorConfig);
    /**
     * Resolves the system prompt to a string. If `this.prompt` is an
     * {@link AgentPrompt}, calls its `.render()` method.
     */
    protected resolveSystemPrompt(): Promise<string>;
    /**
     * Generates a complete response for the given input (non-streaming).
     *
     * @param input - The user message to process.
     * @param options - Optional prior messages and abort signal.
     * @returns The complete generation result.
     */
    generate(input: string, options?: GenerateOptions): Promise<GenerateResult>;
    /**
     * Streams a response for the given input, yielding {@link AgentStreamPart}
     * chunks as they arrive.
     *
     * @param input - The user message to process.
     * @param options - Optional prior messages and abort signal.
     * @yields Stream parts: text-delta, tool-call, tool-result, error, finish-step, done.
     */
    stream(input: string, options?: GenerateOptions): AsyncGenerator<AgentStreamPart>;
    /**
     * Wraps this agent as a tool that can be given to another agent.
     *
     * The returned tool accepts a `{ query: string }` input (or a custom schema),
     * calls {@link Agent.generate} internally, and returns the text response.
     *
     * @param config - Optional overrides for description, schema, and error handling.
     * @returns A tool compatible with the AI SDK tool set.
     */
    asTool(config?: AsToolConfig): ReturnType<typeof createTool<unknown, unknown>>;
    /**
     * Processes a user message within a runtime context, yielding stream parts.
     * This is the default LLM agent implementation that streams text with tool support.
     *
     * Subclasses (FlowAgent, TriageAgent, CompositeAgent) override this method
     * with their specific logic.
     *
     * @param _input - The user message to process.
     * @param context - The runtime agent context with session, messages, etc.
     * @yields AgentStreamPart chunks.
     */
    run(_input: string, context: AgentContext): AsyncGenerator<RuntimeAgentStreamPart>;
    /**
     * Determines whether this agent can handle the given input.
     * Returns true by default. Subclasses can override for conditional routing.
     */
    canHandle(_input: string, _context: AgentContext): Promise<boolean>;
    /**
     * Called when the agent is first activated in a runtime context.
     * No-op by default. Subclasses can override for setup logic.
     */
    initialize(_context: AgentContext): Promise<void>;
    /**
     * Called when the agent is deactivated in a runtime context.
     * No-op by default. Subclasses can override for teardown logic.
     */
    cleanup(_context: AgentContext): Promise<void>;
}