@inkeep/agents-sdk 0.0.0-dev-20250911210702 → 0.0.0-dev-20250911221549

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { MCPToolConfig as MCPToolConfig$1, ArtifactComponentInsert, DataComponentInsert, CredentialReferenceApiInsert, CredentialReferenceSelect, AgentApiInsert, DataComponentApiInsert, ArtifactComponentApiInsert, AgentConversationHistoryConfig, ToolInsert, McpTransportConfig } from '@inkeep/agents-core';
+import { MCPToolConfig as MCPToolConfig$1, CredentialReferenceApiInsert, MCPTransportType, CredentialReferenceSelect, AgentApiInsert, DataComponentApiInsert, ArtifactComponentApiInsert, AgentConversationHistoryConfig, ToolInsert, McpTransportConfig, ArtifactComponentInsert, DataComponentInsert } from '@inkeep/agents-core';
 import { z } from 'zod';
 
 interface ToolInterface {
@@ -30,60 +30,26 @@ declare class Tool implements ToolInterface {
     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 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
  */
@@ -100,74 +66,10 @@ interface ArtifactComponentConfig extends ComponentConfig {
 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.
  *
@@ -193,57 +95,6 @@ declare function credential(config: CredentialReferenceApiInsert): {
  * ```
  */
 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";
@@ -617,21 +468,55 @@ declare class Agent implements AgentInterface {
     private createAgentToolRelation;
 }
 
-interface EnvironmentSettingsConfig {
-    credentials?: {
-        [settingId: string]: CredentialReferenceApiInsert;
-    };
+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;
 }
-/**
- * Create a setting helper with TypeScript autocomplete
- */
-declare function createEnvironmentSettings<T extends Record<string, EnvironmentSettingsConfig>>(environments: T): {
-    getEnvironmentSetting: (key: keyof NonNullable<T[keyof T]["credentials"]>) => Promise<CredentialReferenceApiInsert>;
-};
-/**
- * Create type-safe environment configurations
- */
-declare function registerEnvironmentSettings<T extends EnvironmentSettingsConfig>(config: T): T;
 
 declare class AgentGraph implements GraphInterface {
     private agents;
@@ -823,14 +708,176 @@ declare class AgentGraph implements GraphInterface {
      */
     private createExternalAgents;
 }
+
 /**
  * Helper function to create graphs - OpenAI style
  */
 declare function agentGraph(config: GraphConfig): AgentGraph;
 /**
- * Factory function to create graph from configuration file
+ * 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 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 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 generateGraph(configPath: string): Promise<AgentGraph>;
+declare function mcpTool(config: MCPToolConfig$1): Tool;
+/**
+ * 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;
+declare function agentMcp(config: AgentMcpConfig): AgentMcpConfig;
+
+interface EnvironmentSettingsConfig {
+    credentials?: {
+        [settingId: string]: CredentialReferenceApiInsert;
+    };
+}
+/**
+ * Create a setting helper with TypeScript autocomplete
+ */
+declare function createEnvironmentSettings<T extends Record<string, EnvironmentSettingsConfig>>(environments: T): {
+    getEnvironmentSetting: (key: keyof NonNullable<T[keyof T]["credentials"]>) => Promise<CredentialReferenceApiInsert>;
+};
+/**
+ * Create type-safe environment configurations
+ */
+declare function registerEnvironmentSettings<T extends EnvironmentSettingsConfig>(config: T): T;
 
 declare class Runner {
     /**
@@ -869,4 +916,4 @@ declare const run: typeof Runner.run;
 declare const stream: typeof Runner.stream;
 declare const raceGraphs: typeof Runner.raceGraphs;
 
-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 };
+export { Agent, type AgentCanUseType, type AgentConfig, AgentError, 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, agentMcp, artifactComponent, createEnvironmentSettings, credential, dataComponent, externalAgent, externalAgents, mcpServer, mcpTool, raceGraphs, registerEnvironmentSettings, run, stream, transfer };