@iqai/adk 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -3355,10 +3355,282 @@ declare class LangGraphAgent extends BaseAgent {
     setMaxSteps(maxSteps: number): void;
 }
 
+/**
+ * The Runner class is used to run agents.
+ * It manages the execution of an agent within a session, handling message
+ * processing, event generation, and interaction with various services like
+ * artifact storage, session management, and memory.
+ */
+declare class Runner {
+    /**
+     * The app name of the runner.
+     */
+    appName: string;
+    /**
+     * The root agent to run.
+     */
+    agent: BaseAgent;
+    /**
+     * The artifact service for the runner.
+     */
+    artifactService?: BaseArtifactService;
+    /**
+     * The session service for the runner.
+     */
+    sessionService: BaseSessionService;
+    /**
+     * The memory service for the runner.
+     */
+    memoryService?: BaseMemoryService;
+    /**
+     * Initializes the Runner.
+     */
+    constructor({ appName, agent, artifactService, sessionService, memoryService, }: {
+        appName: string;
+        agent: BaseAgent;
+        artifactService?: BaseArtifactService;
+        sessionService: BaseSessionService;
+        memoryService?: BaseMemoryService;
+    });
+    /**
+     * Runs the agent synchronously.
+     * NOTE: This sync interface is only for local testing and convenience purpose.
+     * Consider using `runAsync` for production usage.
+     */
+    run({ userId, sessionId, newMessage, runConfig, }: {
+        userId: string;
+        sessionId: string;
+        newMessage: Content$1;
+        runConfig?: RunConfig;
+    }): Generator<Event, void, unknown>;
+    /**
+     * Main entry method to run the agent in this runner.
+     */
+    runAsync({ userId, sessionId, newMessage, runConfig, }: {
+        userId: string;
+        sessionId: string;
+        newMessage: Content$1;
+        runConfig?: RunConfig;
+    }): AsyncGenerator<Event, void, unknown>;
+    /**
+     * Appends a new message to the session.
+     */
+    private _appendNewMessageToSession;
+    /**
+     * Finds the agent to run to continue the session.
+     */
+    private _findAgentToRun;
+    /**
+     * Whether the agent to run can transfer to any other agent in the agent tree.
+     */
+    private _isTransferableAcrossAgentTree;
+    /**
+     * Creates a new invocation context.
+     */
+    private _newInvocationContext;
+}
+/**
+ * An in-memory Runner for testing and development.
+ */
+declare class InMemoryRunner extends Runner {
+    /**
+     * Deprecated. Please don't use. The in-memory session service for the runner.
+     */
+    private _inMemorySessionService;
+    /**
+     * Initializes the InMemoryRunner.
+     */
+    constructor(agent: BaseAgent, { appName }?: {
+        appName?: string;
+    });
+}
+
+/**
+ * Configuration options for the AgentBuilder
+ */
+interface AgentBuilderConfig {
+    name: string;
+    model?: string;
+    description?: string;
+    instruction?: string;
+    tools?: BaseTool[];
+    planner?: BasePlanner;
+    subAgents?: BaseAgent[];
+    maxIterations?: number;
+    nodes?: LangGraphNode[];
+    rootNode?: string;
+}
+/**
+ * Session configuration for the AgentBuilder
+ */
+interface SessionConfig {
+    service: BaseSessionService;
+    userId: string;
+    appName: string;
+    memoryService?: BaseMemoryService;
+    artifactService?: BaseArtifactService;
+}
+/**
+ * Built agent result containing the agent and optional runner/session
+ */
+interface BuiltAgent {
+    agent: BaseAgent;
+    runner?: Runner;
+    session?: Session;
+}
+/**
+ * Agent types that can be built
+ */
+type AgentType = "llm" | "sequential" | "parallel" | "loop" | "langgraph";
+/**
+ * AgentBuilder - A fluent interface for building agents with optional session management
+ *
+ * This builder provides a convenient way to create agents, manage sessions, and
+ * automatically set up runners without the boilerplate code. It supports all
+ * agent types and maintains backward compatibility with existing interfaces.
+ *
+ * Examples:
+ * ```typescript
+ * // Simplest possible usage
+ * const response = await AgentBuilder
+ *   .withModel("gemini-2.5-flash")
+ *   .ask("What is the capital of Australia?");
+ *
+ * // Simple agent with name
+ * const { agent } = AgentBuilder
+ *   .create("my-agent")
+ *   .withModel("gemini-2.5-flash")
+ *   .withInstruction("You are helpful")
+ *   .build();
+ *
+ * // Agent with session and runner
+ * const { agent, runner, session } = await AgentBuilder
+ *   .create("my-agent")
+ *   .withModel("gemini-2.5-flash")
+ *   .withSession(sessionService, "user123", "myApp")
+ *   .build();
+ * ```
+ */
+declare class AgentBuilder {
+    private config;
+    private sessionConfig?;
+    private agentType;
+    /**
+     * Private constructor - use static create() method
+     */
+    private constructor();
+    /**
+     * Create a new AgentBuilder instance
+     * @param name The name of the agent (defaults to "default_agent")
+     * @returns New AgentBuilder instance
+     */
+    static create(name?: string): AgentBuilder;
+    /**
+     * Convenience method to start building with a model directly
+     * @param model The model identifier (e.g., "gemini-2.5-flash")
+     * @returns New AgentBuilder instance with model set
+     */
+    static withModel(model: string): AgentBuilder;
+    /**
+     * Set the model for the agent
+     * @param model The model identifier (e.g., "gemini-2.5-flash")
+     * @returns This builder instance for chaining
+     */
+    withModel(model: string): this;
+    /**
+     * Set the description for the agent
+     * @param description Agent description
+     * @returns This builder instance for chaining
+     */
+    withDescription(description: string): this;
+    /**
+     * Set the instruction for the agent
+     * @param instruction System instruction for the agent
+     * @returns This builder instance for chaining
+     */
+    withInstruction(instruction: string): this;
+    /**
+     * Add tools to the agent
+     * @param tools Tools to add to the agent
+     * @returns This builder instance for chaining
+     */
+    withTools(...tools: BaseTool[]): this;
+    /**
+     * Set the planner for the agent
+     * @param planner The planner to use
+     * @returns This builder instance for chaining
+     */
+    withPlanner(planner: BasePlanner): this;
+    /**
+     * Configure as a sequential agent
+     * @param subAgents Sub-agents to execute in sequence
+     * @returns This builder instance for chaining
+     */
+    asSequential(subAgents: BaseAgent[]): this;
+    /**
+     * Configure as a parallel agent
+     * @param subAgents Sub-agents to execute in parallel
+     * @returns This builder instance for chaining
+     */
+    asParallel(subAgents: BaseAgent[]): this;
+    /**
+     * Configure as a loop agent
+     * @param subAgents Sub-agents to execute iteratively
+     * @param maxIterations Maximum number of iterations
+     * @returns This builder instance for chaining
+     */
+    asLoop(subAgents: BaseAgent[], maxIterations?: number): this;
+    /**
+     * Configure as a LangGraph agent
+     * @param nodes Graph nodes defining the workflow
+     * @param rootNode The starting node name
+     * @returns This builder instance for chaining
+     */
+    asLangGraph(nodes: LangGraphNode[], rootNode: string): this;
+    /**
+     * Configure session management
+     * @param service Session service to use
+     * @param userId User identifier
+     * @param appName Application name
+     * @param memoryService Optional memory service
+     * @param artifactService Optional artifact service
+     * @returns This builder instance for chaining
+     */
+    withSession(service: BaseSessionService, userId: string, appName: string, memoryService?: BaseMemoryService, artifactService?: BaseArtifactService): this;
+    /**
+     * Configure with an in-memory session (for quick setup)
+     * @param appName Application name
+     * @param userId User identifier
+     * @returns This builder instance for chaining
+     */
+    withQuickSession(appName: string, userId: string): this;
+    /**
+     * Build the agent and optionally create runner and session
+     * @returns Built agent with optional runner and session
+     */
+    build(): Promise<BuiltAgent>;
+    /**
+     * Quick execution helper - build and run a message
+     * @param message Message to send to the agent
+     * @returns Agent response
+     */
+    ask(message: string): Promise<string>;
+    /**
+     * Create the appropriate agent type based on configuration
+     * @returns Created agent instance
+     */
+    private createAgent;
+}
+
 type index$4_AfterAgentCallback = AfterAgentCallback;
+type index$4_AgentBuilder = AgentBuilder;
+declare const index$4_AgentBuilder: typeof AgentBuilder;
+type index$4_AgentBuilderConfig = AgentBuilderConfig;
+type index$4_AgentType = AgentType;
 type index$4_BaseAgent = BaseAgent;
 declare const index$4_BaseAgent: typeof BaseAgent;
 type index$4_BeforeAgentCallback = BeforeAgentCallback;
+type index$4_BuiltAgent = BuiltAgent;
 type index$4_CallbackContext = CallbackContext;
 declare const index$4_CallbackContext: typeof CallbackContext;
 type index$4_InstructionProvider = InstructionProvider;
@@ -3386,13 +3658,14 @@ declare const index$4_RunConfig: typeof RunConfig;
 type index$4_SequentialAgent = SequentialAgent;
 declare const index$4_SequentialAgent: typeof SequentialAgent;
 type index$4_SequentialAgentConfig = SequentialAgentConfig;
+type index$4_SessionConfig = SessionConfig;
 type index$4_SingleAgentCallback = SingleAgentCallback;
 type index$4_StreamingMode = StreamingMode;
 declare const index$4_StreamingMode: typeof StreamingMode;
 type index$4_ToolUnion = ToolUnion;
 declare const index$4_newInvocationContextId: typeof newInvocationContextId;
 declare namespace index$4 {
-  export { type index$4_AfterAgentCallback as AfterAgentCallback, LlmAgent as Agent, index$4_BaseAgent as BaseAgent, type index$4_BeforeAgentCallback as BeforeAgentCallback, index$4_CallbackContext as CallbackContext, type index$4_InstructionProvider as InstructionProvider, index$4_InvocationContext as InvocationContext, index$4_LangGraphAgent as LangGraphAgent, type index$4_LangGraphAgentConfig as LangGraphAgentConfig, type index$4_LangGraphNode as LangGraphNode, index$4_LlmAgent as LlmAgent, type index$4_LlmAgentConfig as LlmAgentConfig, index$4_LlmCallsLimitExceededError as LlmCallsLimitExceededError, index$4_LoopAgent as LoopAgent, type index$4_LoopAgentConfig as LoopAgentConfig, index$4_ParallelAgent as ParallelAgent, type index$4_ParallelAgentConfig as ParallelAgentConfig, index$4_ReadonlyContext as ReadonlyContext, index$4_RunConfig as RunConfig, index$4_SequentialAgent as SequentialAgent, type index$4_SequentialAgentConfig as SequentialAgentConfig, type index$4_SingleAgentCallback as SingleAgentCallback, index$4_StreamingMode as StreamingMode, type index$4_ToolUnion as ToolUnion, index$4_newInvocationContextId as newInvocationContextId };
+  export { type index$4_AfterAgentCallback as AfterAgentCallback, LlmAgent as Agent, index$4_AgentBuilder as AgentBuilder, type index$4_AgentBuilderConfig as AgentBuilderConfig, type index$4_AgentType as AgentType, index$4_BaseAgent as BaseAgent, type index$4_BeforeAgentCallback as BeforeAgentCallback, type index$4_BuiltAgent as BuiltAgent, index$4_CallbackContext as CallbackContext, type index$4_InstructionProvider as InstructionProvider, index$4_InvocationContext as InvocationContext, index$4_LangGraphAgent as LangGraphAgent, type index$4_LangGraphAgentConfig as LangGraphAgentConfig, type index$4_LangGraphNode as LangGraphNode, index$4_LlmAgent as LlmAgent, type index$4_LlmAgentConfig as LlmAgentConfig, index$4_LlmCallsLimitExceededError as LlmCallsLimitExceededError, index$4_LoopAgent as LoopAgent, type index$4_LoopAgentConfig as LoopAgentConfig, index$4_ParallelAgent as ParallelAgent, type index$4_ParallelAgentConfig as ParallelAgentConfig, index$4_ReadonlyContext as ReadonlyContext, index$4_RunConfig as RunConfig, index$4_SequentialAgent as SequentialAgent, type index$4_SequentialAgentConfig as SequentialAgentConfig, type index$4_SessionConfig as SessionConfig, type index$4_SingleAgentCallback as SingleAgentCallback, index$4_StreamingMode as StreamingMode, type index$4_ToolUnion as ToolUnion, index$4_newInvocationContextId as newInvocationContextId };
 }
 
 /**
@@ -4108,96 +4381,6 @@ declare class PlanReActPlanner extends BasePlanner {
     private _buildNlPlannerInstruction;
 }
 
-/**
- * The Runner class is used to run agents.
- * It manages the execution of an agent within a session, handling message
- * processing, event generation, and interaction with various services like
- * artifact storage, session management, and memory.
- */
-declare class Runner {
-    /**
-     * The app name of the runner.
-     */
-    appName: string;
-    /**
-     * The root agent to run.
-     */
-    agent: BaseAgent;
-    /**
-     * The artifact service for the runner.
-     */
-    artifactService?: BaseArtifactService;
-    /**
-     * The session service for the runner.
-     */
-    sessionService: BaseSessionService;
-    /**
-     * The memory service for the runner.
-     */
-    memoryService?: BaseMemoryService;
-    /**
-     * Initializes the Runner.
-     */
-    constructor({ appName, agent, artifactService, sessionService, memoryService, }: {
-        appName: string;
-        agent: BaseAgent;
-        artifactService?: BaseArtifactService;
-        sessionService: BaseSessionService;
-        memoryService?: BaseMemoryService;
-    });
-    /**
-     * Runs the agent synchronously.
-     * NOTE: This sync interface is only for local testing and convenience purpose.
-     * Consider using `runAsync` for production usage.
-     */
-    run({ userId, sessionId, newMessage, runConfig, }: {
-        userId: string;
-        sessionId: string;
-        newMessage: Content$1;
-        runConfig?: RunConfig;
-    }): Generator<Event, void, unknown>;
-    /**
-     * Main entry method to run the agent in this runner.
-     */
-    runAsync({ userId, sessionId, newMessage, runConfig, }: {
-        userId: string;
-        sessionId: string;
-        newMessage: Content$1;
-        runConfig?: RunConfig;
-    }): AsyncGenerator<Event, void, unknown>;
-    /**
-     * Appends a new message to the session.
-     */
-    private _appendNewMessageToSession;
-    /**
-     * Finds the agent to run to continue the session.
-     */
-    private _findAgentToRun;
-    /**
-     * Whether the agent to run can transfer to any other agent in the agent tree.
-     */
-    private _isTransferableAcrossAgentTree;
-    /**
-     * Creates a new invocation context.
-     */
-    private _newInvocationContext;
-}
-/**
- * An in-memory Runner for testing and development.
- */
-declare class InMemoryRunner extends Runner {
-    /**
-     * Deprecated. Please don't use. The in-memory session service for the runner.
-     */
-    private _inMemorySessionService;
-    /**
-     * Initializes the InMemoryRunner.
-     */
-    constructor(agent: BaseAgent, { appName }?: {
-        appName?: string;
-    });
-}
-
 interface TelemetryConfig {
     appName: string;
     appVersion?: string;
@@ -4270,4 +4453,4 @@ declare const traceLlmCall: (invocationContext: InvocationContext, eventId: stri
 
 declare const VERSION = "0.1.0";
 
-export { AF_FUNCTION_CALL_ID_PREFIX, type AfterAgentCallback, LlmAgent as Agent, index$4 as Agents, AnthropicLlm, ApiKeyCredential, ApiKeyScheme, AuthConfig, AuthCredential, AuthCredentialType, AuthHandler, AuthScheme, AuthSchemeType, AuthTool, type AuthToolArguments, AutoFlow, BaseAgent, BaseLLMConnection, BaseLlm, BaseLlmFlow, BaseLlmRequestProcessor, BaseLlmResponseProcessor, type BaseMemoryService, BasePlanner, BaseSessionService, BaseTool, BasicAuthCredential, BearerTokenCredential, type BeforeAgentCallback, type BuildFunctionDeclarationOptions, BuiltInPlanner, CallbackContext, DatabaseSessionService, EnhancedAuthConfig, Event, EventActions, index$1 as Events, ExitLoopTool, FileOperationsTool, index as Flows, type FunctionDeclaration, FunctionTool, GcsArtifactService, type GetSessionConfig, GetUserChoiceTool, GoogleLlm, GoogleSearch, HttpRequestTool, HttpScheme, InMemoryArtifactService, InMemoryMemoryService, InMemoryRunner, InMemorySessionService, type InstructionProvider, InvocationContext, type JSONSchema, LLMRegistry, LangGraphAgent, type LangGraphAgentConfig, type LangGraphNode, type ListSessionsResponse, LlmAgent, type LlmAgentConfig, LlmCallsLimitExceededError, LlmRequest, LlmResponse, LoadArtifactsTool, LoadMemoryTool, LoopAgent, type LoopAgentConfig, type McpConfig, McpError, McpErrorType, McpSamplingHandler, type McpSamplingRequest, type McpSamplingResponse, McpToolset, type McpTransportType, index$3 as Memory, index$5 as Models, OAuth2Credential, OAuth2Scheme, type OAuthFlow, type OAuthFlows, OpenAiLlm, OpenIdConnectScheme, ParallelAgent, type ParallelAgentConfig, PlanReActPlanner, REQUEST_EUC_FUNCTION_CALL_NAME, ReadonlyContext, RunConfig, Runner, type SamplingHandler, type SearchMemoryResponse, SequentialAgent, type SequentialAgentConfig, type Session, index$2 as Sessions, type SingleAgentCallback, SingleFlow, State, StreamingMode, type TelemetryConfig, TelemetryService, type ThinkingConfig, type ToolConfig, ToolContext, type ToolUnion, index$6 as Tools, TransferToAgentTool, UserInteractionTool, VERSION, VertexAiSessionService, adkToMcpToolType, requestProcessor$2 as agentTransferRequestProcessor, requestProcessor$6 as basicRequestProcessor, buildFunctionDeclaration, requestProcessor as codeExecutionRequestProcessor, responseProcessor as codeExecutionResponseProcessor, requestProcessor$3 as contentRequestProcessor, createAuthToolArguments, createDatabaseSessionService, createFunctionTool, createMysqlSessionService, createPostgresSessionService, createSamplingHandler, createSqliteSessionService, generateAuthEvent, generateClientFunctionCallId, getLongRunningFunctionCalls, getMcpTools, handleFunctionCallsAsync, handleFunctionCallsLive, requestProcessor$5 as identityRequestProcessor, initializeTelemetry, injectSessionState, requestProcessor$4 as instructionsRequestProcessor, isEnhancedAuthConfig, jsonSchemaToDeclaration, mcpSchemaToParameters, mergeParallelFunctionResponseEvents, newInvocationContextId, requestProcessor$1 as nlPlanningRequestProcessor, responseProcessor$1 as nlPlanningResponseProcessor, normalizeJsonSchema, populateClientFunctionCallId, registerProviders, removeClientFunctionCallId, requestProcessor$7 as requestProcessor, shutdownTelemetry, telemetryService, traceLlmCall, traceToolCall, tracer };
+export { AF_FUNCTION_CALL_ID_PREFIX, type AfterAgentCallback, LlmAgent as Agent, AgentBuilder, type AgentBuilderConfig, type AgentType, index$4 as Agents, AnthropicLlm, ApiKeyCredential, ApiKeyScheme, AuthConfig, AuthCredential, AuthCredentialType, AuthHandler, AuthScheme, AuthSchemeType, AuthTool, type AuthToolArguments, AutoFlow, BaseAgent, BaseLLMConnection, BaseLlm, BaseLlmFlow, BaseLlmRequestProcessor, BaseLlmResponseProcessor, type BaseMemoryService, BasePlanner, BaseSessionService, BaseTool, BasicAuthCredential, BearerTokenCredential, type BeforeAgentCallback, type BuildFunctionDeclarationOptions, type BuiltAgent, BuiltInPlanner, CallbackContext, DatabaseSessionService, EnhancedAuthConfig, Event, EventActions, index$1 as Events, ExitLoopTool, FileOperationsTool, index as Flows, type FunctionDeclaration, FunctionTool, GcsArtifactService, type GetSessionConfig, GetUserChoiceTool, GoogleLlm, GoogleSearch, HttpRequestTool, HttpScheme, InMemoryArtifactService, InMemoryMemoryService, InMemoryRunner, InMemorySessionService, type InstructionProvider, InvocationContext, type JSONSchema, LLMRegistry, LangGraphAgent, type LangGraphAgentConfig, type LangGraphNode, type ListSessionsResponse, LlmAgent, type LlmAgentConfig, LlmCallsLimitExceededError, LlmRequest, LlmResponse, LoadArtifactsTool, LoadMemoryTool, LoopAgent, type LoopAgentConfig, type McpConfig, McpError, McpErrorType, McpSamplingHandler, type McpSamplingRequest, type McpSamplingResponse, McpToolset, type McpTransportType, index$3 as Memory, index$5 as Models, OAuth2Credential, OAuth2Scheme, type OAuthFlow, type OAuthFlows, OpenAiLlm, OpenIdConnectScheme, ParallelAgent, type ParallelAgentConfig, PlanReActPlanner, REQUEST_EUC_FUNCTION_CALL_NAME, ReadonlyContext, RunConfig, Runner, type SamplingHandler, type SearchMemoryResponse, SequentialAgent, type SequentialAgentConfig, type Session, type SessionConfig, index$2 as Sessions, type SingleAgentCallback, SingleFlow, State, StreamingMode, type TelemetryConfig, TelemetryService, type ThinkingConfig, type ToolConfig, ToolContext, type ToolUnion, index$6 as Tools, TransferToAgentTool, UserInteractionTool, VERSION, VertexAiSessionService, adkToMcpToolType, requestProcessor$2 as agentTransferRequestProcessor, requestProcessor$6 as basicRequestProcessor, buildFunctionDeclaration, requestProcessor as codeExecutionRequestProcessor, responseProcessor as codeExecutionResponseProcessor, requestProcessor$3 as contentRequestProcessor, createAuthToolArguments, createDatabaseSessionService, createFunctionTool, createMysqlSessionService, createPostgresSessionService, createSamplingHandler, createSqliteSessionService, generateAuthEvent, generateClientFunctionCallId, getLongRunningFunctionCalls, getMcpTools, handleFunctionCallsAsync, handleFunctionCallsLive, requestProcessor$5 as identityRequestProcessor, initializeTelemetry, injectSessionState, requestProcessor$4 as instructionsRequestProcessor, isEnhancedAuthConfig, jsonSchemaToDeclaration, mcpSchemaToParameters, mergeParallelFunctionResponseEvents, newInvocationContextId, requestProcessor$1 as nlPlanningRequestProcessor, responseProcessor$1 as nlPlanningResponseProcessor, normalizeJsonSchema, populateClientFunctionCallId, registerProviders, removeClientFunctionCallId, requestProcessor$7 as requestProcessor, shutdownTelemetry, telemetryService, traceLlmCall, traceToolCall, tracer };