agent-contracts-runtime/dist/adapters/adk-sdk.d.ts

Runtime bridge for executing agent-contracts workflows on Agent SDKs

import { S as SdkAdapter, C as CacheConfig, A as AdapterSendOptions, a as AgentExecutionRequest, M as MemoryRef } from '../task-runner-Bo37lS9q.js';
import { G as GuardrailHooks } from '../guardrail-hooks-C8G5NGsj.js';
import 'zod';

/**
 * Google ADK Adapter — implements SdkAdapter for @google/adk (ADK-TS / adk-js)
 *
 * Replaces the raw @google/genai adapter. ADK provides a native subagent
 * mechanism (`LlmAgent.subAgents` + description-based agent transfer), which is
 * required for model B (LLM-internal routing): the entry agent's LLM delegates
 * to candidate sub-agents registered in the agent tree.
 *
 * Supports:
 * - send()          — build a root LlmAgent (+ candidate subAgents), run once,
 *                     return the final response text
 * - sendExecution() — rich path using full contract context
 *
 * No followUp(): ADK's InMemoryRunner uses ephemeral sessions, so the runtime's
 * recovery loop falls back to a fresh send() with reconstructed context.
 *
 * API used (verified against the installed package's type definitions under
 * node_modules/@google/adk/dist/types):
 *   - class LlmAgent (agents/llm_agent.d.ts): constructor(config) where config
 *     extends BaseAgentConfig { name; description?; subAgents?: BaseAgent[] }
 *     and adds { model?: string | BaseLlm; instruction?: string; tools? }.
 *   - class InMemoryRunner (runner/in_memory_runner.d.ts): constructor({ agent,
 *     appName? }); inherits runEphemeral({ userId, newMessage: Content })
 *     returning AsyncGenerator<Event> (runner/runner.d.ts).
 *   - isFinalResponse(event) / stringifyContent(event) (events/event.d.ts).
 *   - class Gemini (models/google_llm.d.ts): constructor({ model, apiKey })
 *     — used to inject an explicit API key; otherwise ADK reads
 *     GOOGLE_GENAI_API_KEY / GEMINI_API_KEY from the environment.
 */

type AdkContentPart = {
    text?: string;
    functionCall?: {
        name?: string;
        args?: Record<string, unknown>;
    };
    functionResponse?: {
        name?: string;
        response?: unknown;
    };
};
type AdkContent = {
    role?: string;
    parts?: AdkContentPart[];
};
type AdkEvent = {
    author?: string;
    content?: AdkContent;
    [key: string]: unknown;
};
type LlmAgentConfig = {
    name: string;
    description?: string;
    model?: string | object;
    instruction?: string;
    tools?: unknown[];
    subAgents?: unknown[];
};
type LlmAgentInstance = object;
type LlmAgentConstructor = new (config: LlmAgentConfig) => LlmAgentInstance;
type RunnerInstance = {
    runEphemeral(params: {
        userId: string;
        newMessage: AdkContent;
        stateDelta?: Record<string, unknown>;
    }): AsyncGenerator<AdkEvent, void, unknown>;
};
type InMemoryRunnerConstructor = new (params: {
    agent: LlmAgentInstance;
    appName?: string;
}) => RunnerInstance;
type GeminiConstructor = new (params: {
    model?: string;
    apiKey?: string;
}) => object;
interface AdkSdk {
    LlmAgent: LlmAgentConstructor;
    InMemoryRunner: InMemoryRunnerConstructor;
    isFinalResponse: (event: AdkEvent) => boolean;
    stringifyContent: (event: AdkEvent) => string;
    Gemini: GeminiConstructor;
}
interface AdkSdkAdapterConfig {
    /** API key for the Gemini API. Falls back to GOOGLE_GENAI_API_KEY / GEMINI_API_KEY env. */
    apiKey?: string;
    /** Gemini model identifier (e.g. "gemini-2.5-flash", "gemini-2.5-pro"). */
    model?: string;
    /** Root agent name (must be a JS identifier). Defaults to "root_agent". */
    rootAgentName?: string;
    /** Runtime guardrail hooks. Applied as input-level checks before agent execution. */
    guardrailHooks?: GuardrailHooks;
    /** Prompt caching configuration. Enabled by default. */
    cacheConfig?: CacheConfig;
}
declare class AdkSdkAdapter implements SdkAdapter {
    private apiKey;
    private model;
    private rootAgentName;
    private guardrailHooks;
    private cacheConfig;
    private lastMemoryRef;
    private runCounter;
    private sdk;
    constructor(config?: AdkSdkAdapterConfig);
    private resolveSdk;
    /** Resolve the `model` field for LlmAgent — a Gemini instance when an explicit
     *  API key is supplied, otherwise the bare model id (ADK reads env keys). */
    private resolveModel;
    /** Build the root LlmAgent with candidate sub-agents registered for transfer. */
    private buildRootAgent;
    private runAgent;
    private nextMemoryRef;
    send(prompt: string, options: AdapterSendOptions): Promise<string>;
    sendExecution(request: AgentExecutionRequest): Promise<string>;
    getLastMemoryRef(): MemoryRef | null;
    isCompatible(compat: string): boolean;
    /**
     * Inject the resolved ADK SDK surface for testing.
     * Bypasses the dynamic import of @google/adk and the API key requirement.
     */
    static withSdk(sdk: AdkSdk, config?: AdkSdkAdapterConfig): AdkSdkAdapter;
}

export { AdkSdkAdapter, type AdkSdkAdapterConfig };