tinyagent-ts/dist/src/agent.d.ts

Modern TypeScript framework for building AI agents with pluggable tools and ReAct reasoning

import 'reflect-metadata';
import { ToolMetadata } from './decorators';
import { PromptEngine } from './promptEngine';
import { FinalAnswerArgs } from './final-answer.tool';
/**
 * Represents a tool's runtime information, including its metadata and
 * a callable function to execute it.
 * @internal
 */
interface ToolHandle {
    /** The metadata associated with the tool, as defined by the `@tool` decorator. */
    meta: ToolMetadata;
    /**
     * An asynchronous function that executes the tool's logic.
     * @param args - The arguments to pass to the tool, expected to conform to `meta.schema`.
     * @returns A promise that resolves with the result of the tool execution.
     */
    call: (args: Record<string, unknown>) => Promise<unknown>;
}
/**
 * Defines the expected structure of a successful response from the OpenRouter API.
 * @internal
 */
interface OpenRouterResponse {
    /** An array of choices, typically containing one primary response. */
    choices: Array<{
        /** The message object containing the content generated by the LLM. */
        message: {
            /** The textual content of the LLM's response. */
            content: string;
        };
    }>;
}
/**
 * Defines the structure for messages sent to the LLM.
 * @internal
 */
export interface LLMMessage {
    role: 'system' | 'user' | 'assistant';
    content: string;
}
/**
 * Abstract base class for creating AI agents.
 * Agents can be equipped with tools (defined by `@tool` decorator) and use an LLM
 * (specified by `@model` decorator) to process input and decide whether to use a tool
 * or respond directly.
 *
 * @template I - The type of the input the agent's `run` method accepts. Defaults to `string`.
 * @template O - The type of the output the agent's `run` method produces. Defaults to `string`.
 */
export declare abstract class Agent<I = string> {
    /** The API key for OpenRouter, loaded from environment variables. */
    private readonly apiKey;
    protected readonly customSystemPrompt?: string;
    protected readonly promptEngine: PromptEngine;
    /** Conversation memory for ReAct loop */
    protected readonly memory: LLMMessage[];
    /** Simple logger with debug() method */
    protected readonly logger: Console;
    /**
     * Initializes a new instance of the Agent.
     * It requires the `OPENROUTER_API_KEY` environment variable to be set.
     * @throws Error if `OPENROUTER_API_KEY` is not found in the environment variables.
     */
    constructor(options?: {
        systemPrompt?: string;
        systemPromptFile?: string;
    });
    /**
     * Retrieves the LLM model name associated with this agent class.
     * The model name is specified using the `@model` decorator.
     * @returns The model name string.
     * @throws Error if the `@model` decorator is missing on the agent class.
     * @internal
     */
    protected getModelName(): string;
    /**
     * Builds a registry of tools available to this agent.
     * Tools are defined using the `@tool` decorator on methods of the agent class.
     * @returns A record mapping tool names to their `ToolHandle` (metadata and call function).
     * @internal
     */
    protected buildToolRegistry(): Record<string, ToolHandle>;
    /**
     * Makes a request to the OpenRouter API.
     * @param messages - An array of message objects to send to the LLM.
     * @param model - The name of the LLM model to use.
     * @returns A promise that resolves with the API response.
     * @throws Error if the API request fails or returns an error status.
     * @internal
     */
    protected makeOpenRouterRequest(messages: LLMMessage[], model: string): Promise<OpenRouterResponse>;
    /**
     * Main entry point for running the agent.
     * It processes the input, interacts with the LLM, and potentially uses tools
     * to generate a final output.
     * @param input - The input to be processed by the agent.
     * @returns A promise that resolves with the agent's final output.
     */
    run(input: I): Promise<FinalAnswerArgs>;
    /**
     * Helper to build the initial LLM messages (system + user).
     */
    private buildInitialMessages;
    /**
     * Helper to retry LLM output with a fix request if schema validation fails.
     * Prompts the LLM to correct its output to match the AssistantReplySchema.
     */
    private retryWithFixRequest;
}
export {};