@inkeep/agents-sdk 0.0.0-dev-20250911175803 → 0.0.0-dev-20250911195722

package/dist/index.d.ts

@@ -1,6 +1,250 @@
-import { CredentialReferenceSelect, AgentApiInsert, DataComponentApiInsert, ArtifactComponentApiInsert, AgentConversationHistoryConfig, CredentialReferenceApiInsert, ToolInsert, McpTransportConfig, ArtifactComponentInsert, DataComponentInsert, MCPToolConfig as MCPToolConfig$1, MCPTransportType } from '@inkeep/agents-core';
+import { MCPToolConfig as MCPToolConfig$1, ArtifactComponentInsert, DataComponentInsert, CredentialReferenceApiInsert, CredentialReferenceSelect, AgentApiInsert, DataComponentApiInsert, ArtifactComponentApiInsert, AgentConversationHistoryConfig, ToolInsert, McpTransportConfig } from '@inkeep/agents-core';
 import { z } from 'zod';
 
+interface ToolInterface {
+    config: MCPToolConfig$1;
+    init(): Promise<void>;
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getServerUrl(): string;
+    getActiveTools(): string[] | undefined;
+    getCredentialReferenceId(): string | null | undefined;
+}
+declare class Tool implements ToolInterface {
+    config: MCPToolConfig$1;
+    private baseURL;
+    private tenantId;
+    private initialized;
+    private projectId;
+    constructor(config: MCPToolConfig$1);
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getServerUrl(): string;
+    getActiveTools(): string[] | undefined;
+    getCredentialReferenceId(): string | null | undefined;
+    init(options?: {
+        skipDatabaseRegistration?: boolean;
+    }): Promise<void>;
+    private upsertTool;
+}
+
+interface ArtifactComponentInterface {
+    config: Omit<ArtifactComponentInsert, "id">;
+    init(): Promise<void>;
+    getId(): ArtifactComponentInsert["id"];
+    getName(): ArtifactComponentInsert["name"];
+    getDescription(): ArtifactComponentInsert["description"];
+    getSummaryProps(): ArtifactComponentInsert["summaryProps"];
+    getFullProps(): ArtifactComponentInsert["fullProps"];
+}
+declare class ArtifactComponent implements ArtifactComponentInterface {
+    config: ArtifactComponentInsert;
+    private baseURL;
+    private tenantId;
+    private projectId;
+    private initialized;
+    private id;
+    constructor(config: Omit<ArtifactComponentInsert, "id">);
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getSummaryProps(): ArtifactComponentInsert["summaryProps"];
+    getFullProps(): ArtifactComponentInsert["fullProps"];
+    init(): Promise<void>;
+    private upsertArtifactComponent;
+}
+
+interface DataComponentInterface {
+    config: Omit<DataComponentInsert, "id">;
+    init(): Promise<void>;
+    getId(): DataComponentInsert["id"];
+    getName(): DataComponentInsert["name"];
+    getDescription(): DataComponentInsert["description"];
+    getProps(): DataComponentInsert["props"];
+}
+declare class DataComponent implements DataComponentInterface {
+    config: DataComponentInsert;
+    private baseURL;
+    private tenantId;
+    private projectId;
+    private initialized;
+    private id;
+    constructor(config: Omit<DataComponentInsert, "id">);
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getProps(): DataComponentInsert["props"];
+    init(): Promise<void>;
+    private upsertDataComponent;
+}
+
+/**
+ * Function signature for transfer conditions
+ */
+type TransferConditionFunction = (context: unknown) => boolean;
+/**
+ * Configuration for component builders
+ */
+interface ComponentConfig {
+    name: string;
+    description: string;
+    tenantId?: string;
+    projectId?: string;
+}
+interface ArtifactComponentConfig extends ComponentConfig {
+    summaryProps: Record<string, unknown>;
+    fullProps: Record<string, unknown>;
+}
+interface DataComponentConfig extends ComponentConfig {
+    props: Record<string, unknown>;
+}
+/**
+ * Creates a new agent with stable ID enforcement.
+ *
+ * Agents require explicit stable IDs to ensure consistency across deployments.
+ * This is different from tools which auto-generate IDs from their names.
+ *
+ * @param config - Agent configuration including required stable ID
+ * @returns A new Agent instance
+ * @throws {Error} If config.id is not provided
+ *
+ * @example
+ * ```typescript
+ * const myAgent = agent({
+ *   id: 'customer-support-agent',
+ *   name: 'Customer Support',
+ *   prompt: 'Help customers with their questions'
+ * });
+ * ```
+ */
+declare function agent(config: AgentConfig): Agent;
+/**
+ * Creates an MCP tool from a raw configuration object.
+ *
+ * This is a low-level builder for advanced use cases where you need
+ * full control over the MCPToolConfig. For most cases, use `mcpServer()`.
+ *
+ * @param config - Complete MCP tool configuration
+ * @returns A Tool instance
+ *
+ * @example
+ * ```typescript
+ * const customTool = mcpTool({
+ *   id: 'custom-tool',
+ *   name: 'Custom Tool',
+ *   serverUrl: 'https://example.com/mcp',
+ *   transport: { type: 'stdio' }
+ * });
+ * ```
+ */
+declare function mcpTool(config: MCPToolConfig$1): Tool;
+type AgentMcpConfig = {
+    server: Tool;
+    selectedTools: string[];
+};
+/**
+ * Creates a credential reference for authentication.
+ *
+ * Credentials are used to authenticate with external services.
+ * They should be stored securely and referenced by ID.
+ *
+ * @param config - Credential configuration
+ * @returns A validated credential reference
+ *
+ * @example
+ * ```typescript
+ * const apiCredential = credential({
+ *   id: 'github-token',
+ *   type: 'bearer',
+ *   value: process.env.GITHUB_TOKEN
+ * });
+ * ```
+ */
+declare function credential(config: CredentialReferenceApiInsert): {
+    id: string;
+    credentialStoreId: string;
+    type: "nango" | "memory" | "keychain";
+    retrievalParams?: Record<string, unknown> | null | undefined;
+};
+/**
+ * Creates a transfer configuration for agent handoffs.
+ *
+ * Transfers allow one agent to hand off control to another agent
+ * based on optional conditions.
+ *
+ * @param targetAgent - The agent to transfer to
+ * @param description - Optional description of when/why to transfer
+ * @param condition - Optional function to determine if transfer should occur
+ * @returns A validated transfer configuration
+ *
+ * @example
+ * ```typescript
+ * // Simple transfer
+ * const handoff = transfer(supportAgent, 'Transfer to support');
+ *
+ * // Conditional transfer
+ * const conditionalHandoff = transfer(
+ *   specialistAgent,
+ *   'Transfer to specialist for complex issues',
+ *   (context) => context.complexity > 0.8
+ * );
+ * ```
+ */
+declare function transfer(targetAgent: Agent, description?: string, condition?: TransferConditionFunction): TransferConfig;
+/**
+ * Creates an artifact component with automatic ID generation.
+ *
+ * Artifact components represent structured UI components that can
+ * be rendered with different levels of detail (summary vs full).
+ *
+ * @param config - Artifact component configuration
+ * @returns An ArtifactComponent instance
+ *
+ * @example
+ * ```typescript
+ * const productCard = artifactComponent({
+ *   name: 'Product Card',
+ *   description: 'Display product information',
+ *   summaryProps: {
+ *     title: 'Product',
+ *     price: '$0'
+ *   },
+ *   fullProps: {
+ *     title: 'Product',
+ *     price: '$0',
+ *     description: 'Product description',
+ *     image: 'product.jpg'
+ *   }
+ * });
+ * ```
+ */
+declare function artifactComponent(config: ArtifactComponentConfig): ArtifactComponent;
+/**
+ * Creates a data component with automatic ID generation.
+ *
+ * Data components represent structured data that can be
+ * passed between agents or used in processing.
+ *
+ * @param config - Data component configuration
+ * @returns A DataComponent instance
+ *
+ * @example
+ * ```typescript
+ * const userProfile = dataComponent({
+ *   name: 'User Profile',
+ *   description: 'User profile data',
+ *   props: {
+ *     userId: '123',
+ *     name: 'John Doe',
+ *     email: 'john@example.com'
+ *   }
+ * });
+ * ```
+ */
+declare function dataComponent(config: DataComponentConfig): DataComponent;
+
 type ExternalAgentConfig = {
     type?: "external";
     tenantId?: string;
@@ -87,9 +331,10 @@ interface ToolResult {
     error?: string;
 }
 type AllAgentInterface = AgentInterface | ExternalAgentInterface;
+type AgentCanUseType = Tool | AgentMcpConfig;
 interface AgentConfig extends Omit<AgentApiInsert, "projectId"> {
     type?: "internal";
-    tools?: () => any[];
+    canUse?: () => AgentCanUseType[];
     canTransferTo?: () => AgentInterface[];
     canDelegateTo?: () => AllAgentInterface[];
     tenantId?: string;
@@ -354,7 +599,7 @@ declare class Agent implements AgentInterface {
     getDelegates(): AllAgentInterface[];
     getDataComponents(): DataComponentApiInsert[];
     getArtifactComponents(): ArtifactComponentApiInsert[];
-    addTool(_name: string, tool: unknown): void;
+    addTool(_name: string, tool: Tool): void;
     addTransfer(...agents: AgentInterface[]): void;
     addDelegate(...agents: AllAgentInterface[]): void;
     init(): Promise<void>;
@@ -372,295 +617,6 @@ declare class Agent implements AgentInterface {
     private createAgentToolRelation;
 }
 
-interface ArtifactComponentInterface {
-    config: Omit<ArtifactComponentInsert, "id">;
-    init(): Promise<void>;
-    getId(): ArtifactComponentInsert["id"];
-    getName(): ArtifactComponentInsert["name"];
-    getDescription(): ArtifactComponentInsert["description"];
-    getSummaryProps(): ArtifactComponentInsert["summaryProps"];
-    getFullProps(): ArtifactComponentInsert["fullProps"];
-}
-declare class ArtifactComponent implements ArtifactComponentInterface {
-    config: ArtifactComponentInsert;
-    private baseURL;
-    private tenantId;
-    private projectId;
-    private initialized;
-    private id;
-    constructor(config: Omit<ArtifactComponentInsert, "id">);
-    getId(): string;
-    getName(): string;
-    getDescription(): string;
-    getSummaryProps(): ArtifactComponentInsert["summaryProps"];
-    getFullProps(): ArtifactComponentInsert["fullProps"];
-    init(): Promise<void>;
-    private upsertArtifactComponent;
-}
-
-interface DataComponentInterface {
-    config: Omit<DataComponentInsert, "id">;
-    init(): Promise<void>;
-    getId(): DataComponentInsert["id"];
-    getName(): DataComponentInsert["name"];
-    getDescription(): DataComponentInsert["description"];
-    getProps(): DataComponentInsert["props"];
-}
-declare class DataComponent implements DataComponentInterface {
-    config: DataComponentInsert;
-    private baseURL;
-    private tenantId;
-    private projectId;
-    private initialized;
-    private id;
-    constructor(config: Omit<DataComponentInsert, "id">);
-    getId(): string;
-    getName(): string;
-    getDescription(): string;
-    getProps(): DataComponentInsert["props"];
-    init(): Promise<void>;
-    private upsertDataComponent;
-}
-
-interface ToolInterface {
-    config: MCPToolConfig$1;
-    init(): Promise<void>;
-    getId(): string;
-    getName(): string;
-    getDescription(): string;
-    getServerUrl(): string;
-    getActiveTools(): string[] | undefined;
-    getCredentialReferenceId(): string | null | undefined;
-}
-declare class Tool implements ToolInterface {
-    config: MCPToolConfig$1;
-    private baseURL;
-    private tenantId;
-    private initialized;
-    private projectId;
-    constructor(config: MCPToolConfig$1);
-    getId(): string;
-    getName(): string;
-    getDescription(): string;
-    getServerUrl(): string;
-    getActiveTools(): string[] | undefined;
-    getCredentialReferenceId(): string | null | undefined;
-    init(options?: {
-        skipDatabaseRegistration?: boolean;
-    }): Promise<void>;
-    private upsertTool;
-}
-
-/**
- * Function signature for transfer conditions
- */
-type TransferConditionFunction = (context: unknown) => boolean;
-/**
- * Configuration for MCP server builders
- */
-interface MCPServerConfig {
-    name: string;
-    description: string;
-    serverUrl: string;
-    id?: string;
-    parameters?: Record<string, z.ZodJSONSchema>;
-    credential?: CredentialReferenceApiInsert;
-    tenantId?: string;
-    transport?: keyof typeof MCPTransportType;
-    activeTools?: string[];
-    headers?: Record<string, string>;
-    imageUrl?: string;
-}
-/**
- * Configuration for component builders
- */
-interface ComponentConfig {
-    name: string;
-    description: string;
-    tenantId?: string;
-    projectId?: string;
-}
-interface ArtifactComponentConfig extends ComponentConfig {
-    summaryProps: Record<string, unknown>;
-    fullProps: Record<string, unknown>;
-}
-interface DataComponentConfig extends ComponentConfig {
-    props: Record<string, unknown>;
-}
-/**
- * Creates a new agent with stable ID enforcement.
- *
- * Agents require explicit stable IDs to ensure consistency across deployments.
- * This is different from tools which auto-generate IDs from their names.
- *
- * @param config - Agent configuration including required stable ID
- * @returns A new Agent instance
- * @throws {Error} If config.id is not provided
- *
- * @example
- * ```typescript
- * const myAgent = agent({
- *   id: 'customer-support-agent',
- *   name: 'Customer Support',
- *   prompt: 'Help customers with their questions'
- * });
- * ```
- */
-declare function agent(config: AgentConfig): Agent;
-/**
- * Creates an MCP (Model Context Protocol) server for tool functionality.
- *
- * MCP servers provide tool functionality through a standardized protocol.
- * They can be remote services accessed via HTTP/WebSocket.
- *
- * @param config - MCP server configuration
- * @returns A Tool instance configured as an MCP server
- * @throws {Error} If serverUrl is not provided
- *
- * @example
- * ```typescript
- * // Remote MCP server
- * const apiServer = mcpServer({
- *   name: 'external_api',
- *   description: 'External API service',
- *   serverUrl: 'https://api.example.com/mcp'
- * });
- *
- * // With authentication
- * const secureServer = mcpServer({
- *   name: 'secure_api',
- *   description: 'Secure API service',
- *   serverUrl: 'https://secure.example.com/mcp',
- *   credential: credential({
- *     id: 'api-key',
- *     type: 'bearer',
- *     value: process.env.API_KEY
- *   })
- * });
- * ```
- */
-declare function mcpServer(config: MCPServerConfig): Tool;
-/**
- * Creates an MCP tool from a raw configuration object.
- *
- * This is a low-level builder for advanced use cases where you need
- * full control over the MCPToolConfig. For most cases, use `mcpServer()`.
- *
- * @param config - Complete MCP tool configuration
- * @returns A Tool instance
- *
- * @example
- * ```typescript
- * const customTool = mcpTool({
- *   id: 'custom-tool',
- *   name: 'Custom Tool',
- *   serverUrl: 'https://example.com/mcp',
- *   transport: { type: 'stdio' }
- * });
- * ```
- */
-declare function mcpTool(config: MCPToolConfig$1): Tool;
-/**
- * Creates a credential reference for authentication.
- *
- * Credentials are used to authenticate with external services.
- * They should be stored securely and referenced by ID.
- *
- * @param config - Credential configuration
- * @returns A validated credential reference
- *
- * @example
- * ```typescript
- * const apiCredential = credential({
- *   id: 'github-token',
- *   type: 'bearer',
- *   value: process.env.GITHUB_TOKEN
- * });
- * ```
- */
-declare function credential(config: CredentialReferenceApiInsert): {
-    id: string;
-    credentialStoreId: string;
-    type: "nango" | "memory" | "keychain";
-    retrievalParams?: Record<string, unknown> | null | undefined;
-};
-/**
- * Creates a transfer configuration for agent handoffs.
- *
- * Transfers allow one agent to hand off control to another agent
- * based on optional conditions.
- *
- * @param targetAgent - The agent to transfer to
- * @param description - Optional description of when/why to transfer
- * @param condition - Optional function to determine if transfer should occur
- * @returns A validated transfer configuration
- *
- * @example
- * ```typescript
- * // Simple transfer
- * const handoff = transfer(supportAgent, 'Transfer to support');
- *
- * // Conditional transfer
- * const conditionalHandoff = transfer(
- *   specialistAgent,
- *   'Transfer to specialist for complex issues',
- *   (context) => context.complexity > 0.8
- * );
- * ```
- */
-declare function transfer(targetAgent: Agent, description?: string, condition?: TransferConditionFunction): TransferConfig;
-/**
- * Creates an artifact component with automatic ID generation.
- *
- * Artifact components represent structured UI components that can
- * be rendered with different levels of detail (summary vs full).
- *
- * @param config - Artifact component configuration
- * @returns An ArtifactComponent instance
- *
- * @example
- * ```typescript
- * const productCard = artifactComponent({
- *   name: 'Product Card',
- *   description: 'Display product information',
- *   summaryProps: {
- *     title: 'Product',
- *     price: '$0'
- *   },
- *   fullProps: {
- *     title: 'Product',
- *     price: '$0',
- *     description: 'Product description',
- *     image: 'product.jpg'
- *   }
- * });
- * ```
- */
-declare function artifactComponent(config: ArtifactComponentConfig): ArtifactComponent;
-/**
- * Creates a data component with automatic ID generation.
- *
- * Data components represent structured data that can be
- * passed between agents or used in processing.
- *
- * @param config - Data component configuration
- * @returns A DataComponent instance
- *
- * @example
- * ```typescript
- * const userProfile = dataComponent({
- *   name: 'User Profile',
- *   description: 'User profile data',
- *   props: {
- *     userId: '123',
- *     name: 'John Doe',
- *     email: 'john@example.com'
- *   }
- * });
- * ```
- */
-declare function dataComponent(config: DataComponentConfig): DataComponent;
-
 interface EnvironmentSettingsConfig {
     credentials?: {
         [settingId: string]: CredentialReferenceApiInsert;
@@ -913,4 +869,4 @@ declare const run: typeof Runner.run;
 declare const stream: typeof Runner.stream;
 declare const raceGraphs: typeof Runner.raceGraphs;
 
-export { Agent, type AgentConfig, AgentError, AgentGraph, type AgentInterface, type AgentResponse, type AllAgentInterface, ArtifactComponent, type AssistantMessage, type BuilderAgentConfig, type BuilderRelationConfig, type BuilderToolConfig, DataComponent, ExternalAgent, type ExternalAgentInterface, type FetchDefinitionConfig, type GenerateOptions, type GraphConfig, type GraphInterface, type MCPToolConfig, MaxTurnsExceededError, type Message, type MessageInput, type ModelSettings, ModelSettingsSchema, type RequestSchemaConfig, type RequestSchemaDefinition, type RunResult, Runner, type ServerConfig, type StatusComponent, type StatusUpdateSettings, type StreamEvent, type StreamResponse, type SystemMessage, Tool, type ToolCall, type ToolConfig, ToolExecutionError, type ToolMessage, type ToolResult, type TransferConfig, TransferError, type UserMessage, agent, agentGraph, artifactComponent, createEnvironmentSettings, credential, dataComponent, externalAgent, externalAgents, generateGraph, mcpServer, mcpTool, raceGraphs, registerEnvironmentSettings, run, stream, transfer };
+export { Agent, type AgentCanUseType, type AgentConfig, AgentError, AgentGraph, type AgentInterface, type AgentResponse, type AllAgentInterface, ArtifactComponent, type AssistantMessage, type BuilderAgentConfig, type BuilderRelationConfig, type BuilderToolConfig, DataComponent, ExternalAgent, type ExternalAgentInterface, type FetchDefinitionConfig, type GenerateOptions, type GraphConfig, type GraphInterface, type MCPToolConfig, MaxTurnsExceededError, type Message, type MessageInput, type ModelSettings, ModelSettingsSchema, type RequestSchemaConfig, type RequestSchemaDefinition, type RunResult, Runner, type ServerConfig, type StatusComponent, type StatusUpdateSettings, type StreamEvent, type StreamResponse, type SystemMessage, Tool, type ToolCall, type ToolConfig, ToolExecutionError, type ToolMessage, type ToolResult, type TransferConfig, TransferError, type UserMessage, agent, agentGraph, artifactComponent, createEnvironmentSettings, credential, dataComponent, externalAgent, externalAgents, generateGraph, mcpTool, raceGraphs, registerEnvironmentSettings, run, stream, transfer };