import { type LLMToolDefinition } from '../LLMService.typedefs';
import { type LLMSchemaInterface } from '../utilities/schema';
import { type LLMPromptRegistry } from '../client/defineLLMPrompts';
import { type LLMVariableValue } from '../client/promptSnapshot.typedefs';
import { type LLMAgentGroundingRequirement, type LLMDelegationGate, type LLMPromptVariables, type LLMSubagentVariableSource } from '../client/llmClient.typedefs';
import { type LLMAgentSubagentReportCap } from '../client/agentRun.typedefs';
/**
 * A bounded specialist the root agent may delegate to, as a plain object.
 * `prompt` names the registry entry whose Langfuse prompt is the subagent's
 * instructions (and whose config routes its model); `name`/`description` are
 * what the root model sees when deciding to delegate. A plain-object subagent
 * cannot declare its own subagents — use `LLMAgent` instances (via
 * `llm.defineAgent`) when deeper composition is needed.
 */
export type LLMAgentSubagentDefinition<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>> = {
    [Key in keyof Registry]: {
        prompt: Key;
        name: string;
        description: string;
        tools?: LLMToolDefinition[];
        canExecute?: LLMDelegationGate;
        reportCap?: LLMAgentSubagentReportCap;
        grounding?: LLMAgentGroundingRequirement;
        maxToolIterations?: number;
    } & LLMSubagentVariableSource<VariableMap[Key]>;
}[keyof Registry];
/**
 * Anything accepted in a `subagents` list: a plain definition object or an
 * `LLMAgent` instance — both describe the same delegation tool.
 */
export type LLMAgentSubagent<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>> = LLMAgentSubagentDefinition<Registry, VariableMap> | LLMAgent<Registry, VariableMap>;
/**
 * The declarative description of one agent. `prompt` names the registry entry
 * whose Langfuse prompt is the agent's instructions (and whose config routes
 * its model). `name`/`description` are required when the agent is used as a
 * subagent — the name becomes the delegation tool the parent model calls.
 * `variables` given here are a base merged under the per-run variables (for a
 * subagent they are the only source, unless `inputSchema` lets the parent
 * model supply more).
 */
export interface LLMAgentDefinition<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>, Key extends keyof Registry> {
    prompt: Key;
    name?: string;
    description?: string;
    variables?: LLMPromptVariables<VariableMap[Key]>;
    tools?: LLMToolDefinition[];
    subagents?: LLMAgentSubagent<Registry, VariableMap>[];
    /**
     * The arguments the parent model must supply when delegating to this agent,
     * replacing the default single `prompt` string. Each argument joins the
     * subagent's prompt variables (over the definition's own), so the delegated
     * prompt can reference them as `{{name}}`. Only meaningful as a subagent.
     */
    inputSchema?: LLMSchemaInterface;
    /** Refuses a delegation call before it runs; see `LLMDelegationGate`. */
    canExecute?: LLMDelegationGate;
    /**
     * How much prose this agent may hand a parent back when it is delegated to.
     * Only meaningful as a subagent.
     */
    reportCap?: LLMAgentSubagentReportCap;
    /**
     * Flags this agent's report when the delegated run used none of the tools
     * that ground it. Only meaningful as a subagent.
     */
    grounding?: LLMAgentGroundingRequirement;
    maxToolIterations?: number;
}
/**
 * An immutable agent definition bound to the prompt registry. Optional sugar
 * over the plain-object `runAgent` options: build instances with
 * `llm.defineAgent(...)` — the client factory carries the registry generics,
 * so `prompt`, `variables`, and the `runAgent` return type stay fully typed.
 * Agents compose: a subagent may itself be an `LLMAgent` with its own
 * subagents; because instances are immutable, a delegation cycle cannot be
 * constructed and nesting depth is always finite.
 */
export declare class LLMAgent<Registry extends LLMPromptRegistry = LLMPromptRegistry, VariableMap extends Record<keyof Registry, string> = Record<keyof Registry, string>, Key extends keyof Registry = keyof Registry> {
    readonly prompt: Key;
    readonly name: string | undefined;
    readonly description: string | undefined;
    readonly variables: Record<string, LLMVariableValue> | undefined;
    readonly tools: LLMToolDefinition[] | undefined;
    readonly subagents: LLMAgentSubagent<Registry, VariableMap>[] | undefined;
    readonly inputSchema: LLMSchemaInterface | undefined;
    readonly canExecute: LLMDelegationGate | undefined;
    readonly reportCap: LLMAgentSubagentReportCap | undefined;
    readonly grounding: LLMAgentGroundingRequirement | undefined;
    readonly maxToolIterations: number | undefined;
    constructor(definition: LLMAgentDefinition<Registry, VariableMap, Key>);
}