@dexwox-labs/a2a-client/dist/agent-card-resolver.d.ts

TypeScript client implementation for Google's Agent-to-Agent (A2A) protocol - includes HTTP/WebSocket communication, circuit breakers and error handling

/**
 * @module AgentCardResolver
 * @description Provides functionality to resolve and cache agent cards from agent servers
 */
import type { AgentCard } from '@dexwox-labs/a2a-core';
/**
 * Configuration options for the agent card resolver
 *
 * These options control how agent cards are fetched, cached, and timed out.
 *
 * @example
 * ```typescript
 * const options: AgentCardResolverOptions = {
 *   agentCardPath: '/.well-known/custom-agent.json',
 *   cacheTtl: 600000, // 10 minutes
 *   timeout: 3000     // 3 seconds
 * };
 * ```
 */
export interface AgentCardResolverOptions {
    /**
     * Path to agent card (default: '/.well-known/agent.json')
     *
     * This is the endpoint path where the agent card is hosted on the agent server.
     * By default, it follows the well-known URI pattern for agent discovery.
     */
    agentCardPath?: string;
    /**
     * Cache TTL in milliseconds (default: 300000 - 5 minutes)
     *
     * Controls how long a fetched agent card remains valid in the cache
     * before a new fetch is required.
     */
    cacheTtl?: number;
    /**
     * Request timeout in milliseconds (default: 5000)
     *
     * Maximum time to wait for an agent card fetch operation before timing out.
     */
    timeout?: number;
}
/**
 * Resolves and caches agent cards from agent servers
 *
 * This class handles fetching agent cards from agent servers with built-in
 * caching and timeout handling. It follows the A2A protocol for agent discovery.
 *
 * @example
 * ```typescript
 * const resolver = new AgentCardResolver('https://agent.example.com');
 *
 * // Resolve the agent card
 * const agentCard = await resolver.resolve();
 * console.log('Agent name:', agentCard.name);
 * console.log('Agent capabilities:', agentCard.capabilities);
 * ```
 */
export declare class AgentCardResolver {
    /** @private Base URL of the agent server */
    private readonly baseUrl;
    /** @private Path to the agent card endpoint */
    private readonly agentCardPath;
    /** @private Cache time-to-live in milliseconds */
    private readonly cacheTtl;
    /** @private Request timeout in milliseconds */
    private readonly timeout;
    /** @private Circuit breaker for handling failures */
    private readonly circuitBreaker;
    /** @private Currently cached agent card, if any */
    private cache;
    /**
     * Creates a new agent card resolver
     *
     * @param baseUrl - Base URL of the agent server
     * @param options - Configuration options
     */
    constructor(baseUrl: string, options?: AgentCardResolverOptions);
    /**
     * Resolves agent card, using cache if available and not expired
     *
     * This method first checks if there is a valid cached agent card.
     * If the cache is valid, it returns the cached card immediately.
     * Otherwise, it fetches a fresh agent card from the server and
     * updates the cache.
     *
     * @returns Promise resolving to the agent card
     * @throws Error if fetching the agent card fails
     *
     * @example
     * ```typescript
     * const agentCard = await resolver.resolve();
     * console.log('Agent name:', agentCard.name);
     * ```
     */
    resolve(): Promise<AgentCard>;
    /**
     * Force fresh fetch of agent card, bypassing cache
     *
     * This method always fetches a fresh agent card from the server,
     * regardless of whether there is a valid cached card. It then
     * updates the cache with the new card.
     *
     * @returns Promise resolving to the fresh agent card
     * @throws Error if fetching the agent card fails
     *
     * @example
     * ```typescript
     * // Force a refresh of the agent card
     * const freshCard = await resolver.refresh();
     * console.log('Updated capabilities:', freshCard.capabilities);
     * ```
     */
    refresh(): Promise<AgentCard>;
    /**
     * Fetches an agent card from the server
     *
     * This private method handles the actual HTTP request to fetch the agent card.
     * It uses the circuit breaker pattern to prevent cascading failures and
     * implements timeout handling for reliability.
     *
     * @returns Promise resolving to the fetched agent card
     * @throws Error if the HTTP request fails or times out
     * @private
     */
    private fetchAgentCard;
}
//# sourceMappingURL=agent-card-resolver.d.ts.map