@inkeep/agents-sdk 0.0.0-dev-20250911052037 → 0.0.0-dev-20250911071658

package/dist/index.cjs

@@ -490,11 +490,11 @@ var Agent = class {
       throw new Error("tools getter must return an array");
     }
     const toolRecord = {};
-    for (const tool2 of tools) {
-      if (tool2 && typeof tool2 === "object") {
-        const id = tool2.id || tool2.getId?.() || tool2.name;
+    for (const tool of tools) {
+      if (tool && typeof tool === "object") {
+        const id = tool.id || tool.getId?.() || tool.name;
         if (id) {
-          toolRecord[id] = tool2;
+          toolRecord[id] = tool;
         }
       }
     }
@@ -518,9 +518,9 @@ var Agent = class {
   getArtifactComponents() {
     return resolveGetter(this.config.artifactComponents) || [];
   }
-  addTool(_name, tool2) {
+  addTool(_name, tool) {
     const existingTools = this.config.tools ? this.config.tools() : [];
-    this.config.tools = () => [...existingTools, tool2];
+    this.config.tools = () => [...existingTools, tool];
   }
   addTransfer(...agents) {
     if (typeof this.config.canTransferTo === "function") {
@@ -775,7 +775,7 @@ var Agent = class {
         return;
       }
       const { Tool: Tool2 } = await Promise.resolve().then(() => (init_tool(), tool_exports));
-      let tool2;
+      let tool;
       if (toolConfig instanceof Tool2) {
         logger4.info(
           {
@@ -785,8 +785,8 @@ var Agent = class {
           },
           "Initializing Tool instance"
         );
-        tool2 = toolConfig;
-        await tool2.init();
+        tool = toolConfig;
+        await tool.init();
       } else {
         logger4.info(
           {
@@ -796,7 +796,7 @@ var Agent = class {
           },
           "Creating Tool from config"
         );
-        tool2 = new Tool2({
+        tool = new Tool2({
           id: toolId,
           tenantId: this.tenantId,
           name: toolConfig.name || toolId,
@@ -805,13 +805,13 @@ var Agent = class {
           activeTools: toolConfig.config?.mcp?.activeTools,
           credential: toolConfig.credential
         });
-        await tool2.init();
+        await tool.init();
       }
-      await this.createAgentToolRelation(tool2.getId());
+      await this.createAgentToolRelation(tool.getId());
       logger4.info(
         {
           agentId: this.getId(),
-          toolId: tool2.getId()
+          toolId: tool.getId()
         },
         "Tool created and linked to agent"
       );
@@ -970,89 +970,65 @@ var Agent = class {
   }
 };
 init_tool();
-function agent(config) {
-  return new Agent(config);
-}
-function credential(config) {
-  return agentsCore.CredentialReferenceApiInsertSchema.parse(config);
-}
-var ToolConfigSchema = zod.z.object({
-  id: zod.z.string().optional(),
-  name: zod.z.string(),
-  description: zod.z.string(),
-  parameters: zod.z.record(zod.z.string(), zod.z.any()).optional(),
-  schema: zod.z.unknown().optional()
-});
-ToolConfigSchema.extend({
-  execute: zod.z.any()
-  // Function - validated separately at runtime
+var TransferConfigSchema = zod.z.object({
+  agent: zod.z.instanceof(Agent),
+  description: zod.z.string().optional()
 });
-function tool(config) {
-  if (typeof config.execute !== "function") {
-    throw new Error("execute must be a function");
-  }
-  const { execute, ...configWithoutFunction } = config;
-  const validatedConfig = ToolConfigSchema.parse(configWithoutFunction);
-  const fullConfig = { ...validatedConfig, execute };
-  const computedId = fullConfig.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return {
-    id: computedId,
-    name: fullConfig.name,
-    description: fullConfig.description,
-    execute: fullConfig.execute,
-    parameters: fullConfig.parameters,
-    schema: fullConfig.schema,
-    type: "function"
-  };
+function generateIdFromName3(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function mcpServer(config) {
-  const deployment = config.deployment || (config.execute ? "local" : "remote");
-  const id = config.id || config.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  if (deployment === "local") {
-    if (!config.execute) {
-      throw new Error("Local MCP server requires an execute function");
-    }
+function validateFunction(value, name) {
+  if (typeof value !== "function") {
+    throw new Error(`${name} must be a function`);
+  }
+}
+function agent(config) {
+  if (!config.id) {
     throw new Error(
-      "Local MCP servers are no longer supported. Please use remote MCP servers instead."
+      "Agent ID is required. Agents must have stable IDs for consistency across deployments."
     );
-  } else {
-    if (!config.serverUrl) {
-      throw new Error("Remote MCP server requires a serverUrl");
-    }
-    return new exports.Tool({
-      id,
-      name: config.name,
-      description: config.description,
-      serverUrl: config.serverUrl,
-      tenantId: config.tenantId,
-      credential: config.credential,
-      activeTools: config.activeTools,
-      headers: config.headers
-    });
   }
+  return new Agent(config);
+}
+function mcpServer(config) {
+  if (!config.serverUrl) {
+    throw new Error("MCP server requires a serverUrl");
+  }
+  const id = config.id || generateIdFromName3(config.name);
+  return new exports.Tool({
+    id,
+    name: config.name,
+    description: config.description,
+    serverUrl: config.serverUrl,
+    tenantId: config.tenantId,
+    credential: config.credential,
+    activeTools: config.activeTools,
+    headers: config.headers,
+    imageUrl: config.imageUrl,
+    transport: config.transport ? { type: config.transport } : void 0
+  });
 }
 function mcpTool(config) {
   const validatedConfig = agentsCore.MCPToolConfigSchema.parse(config);
   return new exports.Tool(validatedConfig);
 }
-var TransferConfigSchema = zod.z.object({
-  agent: zod.z.instanceof(Agent),
-  description: zod.z.string().optional()
-});
-var TransferSchema = TransferConfigSchema.extend({
-  condition: zod.z.any().optional()
-  // Function - validated separately at runtime when present
-});
+function credential(config) {
+  return agentsCore.CredentialReferenceApiInsertSchema.parse(config);
+}
 function transfer(targetAgent, description, condition) {
-  if (condition !== void 0 && typeof condition !== "function") {
-    throw new Error("condition must be a function when provided");
+  if (condition !== void 0) {
+    validateFunction(condition, "condition");
   }
   const config = {
     agent: targetAgent,
     description: description || `Hand off to ${targetAgent.getName()}`,
     condition
   };
-  return TransferSchema.parse(config);
+  TransferConfigSchema.parse({
+    agent: config.agent,
+    description: config.description
+  });
+  return config;
 }
 function artifactComponent(config) {
   return new ArtifactComponent({
@@ -2876,5 +2852,4 @@ exports.raceGraphs = raceGraphs;
 exports.registerEnvironmentSettings = registerEnvironmentSettings;
 exports.run = run;
 exports.stream = stream;
-exports.tool = tool;
 exports.transfer = transfer;

package/dist/index.d.cts

@@ -451,12 +451,51 @@ declare class Tool implements ToolInterface {
     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 (stable IDs are required)
+ * @throws {Error} If config.id is not provided
  *
  * @example
  * ```typescript
@@ -468,138 +507,159 @@ declare class Tool implements ToolInterface {
  * ```
  */
 declare function agent(config: AgentConfig): Agent;
-declare function credential(config: CredentialReferenceApiInsert): {
-    id: string;
-    credentialStoreId: string;
-    type: "nango" | "memory" | "keychain";
-    retrievalParams?: Record<string, unknown> | null | undefined;
-};
 /**
- * Creates a tool with automatic ID generation (unlike agents which require explicit IDs).
+ * Creates an MCP (Model Context Protocol) server for tool functionality.
  *
- * Tools automatically generate IDs from their name, whereas agents require stable IDs
- * to be explicitly provided for consistency across deployments.
+ * MCP servers provide tool functionality through a standardized protocol.
+ * They can be remote services accessed via HTTP/WebSocket.
  *
- * @param config - Tool configuration with auto-generated ID
- * @returns A Tool instance with auto-generated ID based on name
+ * @param config - MCP server configuration
+ * @returns A Tool instance configured as an MCP server
+ * @throws {Error} If serverUrl is not provided
  *
  * @example
  * ```typescript
- * const searchTool = tool({
- *   name: 'Search Database',
- *   description: 'Search the product database',
- *   execute: async (params) => { ... }
+ * // 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
+ *   })
  * });
- * // ID will be auto-generated as 'search-database'
  * ```
  */
-declare function tool(config: {
-    name: string;
-    description: string;
-    execute: (params: any) => Promise<any>;
-    parameters?: Record<string, any>;
-    schema?: z.ZodJSONSchema;
-}): {
-    id: string;
-    name: string;
-    description: string;
-    execute: (params: any) => Promise<any>;
-    parameters: Record<string, any> | undefined;
-    schema: unknown;
-    type: "function";
-};
+declare function mcpServer(config: MCPServerConfig): Tool;
 /**
- * Creates an MCP (Model Context Protocol) server for tool functionality.
+ * Creates an MCP tool from a raw configuration object.
  *
- * This unified builder replaces tool(), mcpTool(), ipcTool(), and hostedTool().
- * All tools are MCP servers - either local (with execute function) or remote (with URL).
+ * 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 - MCP server configuration
- * @returns An MCP server instance that can be used as a tool in agents
+ * @param config - Complete MCP tool configuration
+ * @returns A Tool instance
  *
  * @example
  * ```typescript
- * // Local MCP server with execute function (auto-wrapped via IPC)
- * const searchServer = mcpServer({
- *   name: 'search',
- *   description: 'Search the database',
- *   execute: async (params) => {
- *     // Implementation
- *     return results;
- *   }
+ * 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.
  *
- * // Remote MCP server
- * const apiServer = mcpServer({
- *   name: 'external_api',
- *   description: 'External API service',
- *   serverUrl: 'https://api.example.com/mcp'
+ * 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 mcpServer(config: {
-    name: string;
-    description: string;
-    deployment?: "local" | "remote";
-    execute?: (params: any) => Promise<any>;
-    port?: number;
-    serverUrl?: string;
-    id?: string;
-    parameters?: Record<string, z.ZodJSONSchema>;
-    credential?: CredentialReferenceApiInsert;
-    tenantId?: string;
-    transport?: keyof typeof MCPTransportType;
-    activeTools?: string[];
-    headers?: Record<string, string>;
-}): Tool;
-declare function mcpTool(config: MCPToolConfig$1): Tool;
-declare function transfer(targetAgent: Agent, description?: string, condition?: (context: unknown) => boolean): TransferConfig;
+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 with auto-generated ID
+ * @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: '...' }
+ *   summaryProps: {
+ *     title: 'Product',
+ *     price: '$0'
+ *   },
+ *   fullProps: {
+ *     title: 'Product',
+ *     price: '$0',
+ *     description: 'Product description',
+ *     image: 'product.jpg'
+ *   }
  * });
  * ```
  */
-declare function artifactComponent(config: {
-    name: string;
-    description: string;
-    summaryProps: Record<string, any>;
-    fullProps: Record<string, any>;
-    tenantId?: string;
-    projectId?: string;
-}): ArtifactComponent;
+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 with auto-generated ID
+ * @returns A DataComponent instance
  *
  * @example
  * ```typescript
  * const userProfile = dataComponent({
  *   name: 'User Profile',
  *   description: 'User profile data',
- *   props: { userId: '123', name: 'John Doe' }
+ *   props: {
+ *     userId: '123',
+ *     name: 'John Doe',
+ *     email: 'john@example.com'
+ *   }
  * });
  * ```
  */
-declare function dataComponent(config: {
-    name: string;
-    description: string;
-    props: Record<string, any>;
-    tenantId?: string;
-    projectId?: string;
-}): DataComponent;
+declare function dataComponent(config: DataComponentConfig): DataComponent;
 
 interface EnvironmentSettingsConfig {
     credentials?: {
@@ -853,4 +913,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, tool, transfer };
+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 };

package/dist/index.d.ts

@@ -451,12 +451,51 @@ declare class Tool implements ToolInterface {
     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 (stable IDs are required)
+ * @throws {Error} If config.id is not provided
  *
  * @example
  * ```typescript
@@ -468,138 +507,159 @@ declare class Tool implements ToolInterface {
  * ```
  */
 declare function agent(config: AgentConfig): Agent;
-declare function credential(config: CredentialReferenceApiInsert): {
-    id: string;
-    credentialStoreId: string;
-    type: "nango" | "memory" | "keychain";
-    retrievalParams?: Record<string, unknown> | null | undefined;
-};
 /**
- * Creates a tool with automatic ID generation (unlike agents which require explicit IDs).
+ * Creates an MCP (Model Context Protocol) server for tool functionality.
  *
- * Tools automatically generate IDs from their name, whereas agents require stable IDs
- * to be explicitly provided for consistency across deployments.
+ * MCP servers provide tool functionality through a standardized protocol.
+ * They can be remote services accessed via HTTP/WebSocket.
  *
- * @param config - Tool configuration with auto-generated ID
- * @returns A Tool instance with auto-generated ID based on name
+ * @param config - MCP server configuration
+ * @returns A Tool instance configured as an MCP server
+ * @throws {Error} If serverUrl is not provided
  *
  * @example
  * ```typescript
- * const searchTool = tool({
- *   name: 'Search Database',
- *   description: 'Search the product database',
- *   execute: async (params) => { ... }
+ * // 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
+ *   })
  * });
- * // ID will be auto-generated as 'search-database'
  * ```
  */
-declare function tool(config: {
-    name: string;
-    description: string;
-    execute: (params: any) => Promise<any>;
-    parameters?: Record<string, any>;
-    schema?: z.ZodJSONSchema;
-}): {
-    id: string;
-    name: string;
-    description: string;
-    execute: (params: any) => Promise<any>;
-    parameters: Record<string, any> | undefined;
-    schema: unknown;
-    type: "function";
-};
+declare function mcpServer(config: MCPServerConfig): Tool;
 /**
- * Creates an MCP (Model Context Protocol) server for tool functionality.
+ * Creates an MCP tool from a raw configuration object.
  *
- * This unified builder replaces tool(), mcpTool(), ipcTool(), and hostedTool().
- * All tools are MCP servers - either local (with execute function) or remote (with URL).
+ * 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 - MCP server configuration
- * @returns An MCP server instance that can be used as a tool in agents
+ * @param config - Complete MCP tool configuration
+ * @returns A Tool instance
  *
  * @example
  * ```typescript
- * // Local MCP server with execute function (auto-wrapped via IPC)
- * const searchServer = mcpServer({
- *   name: 'search',
- *   description: 'Search the database',
- *   execute: async (params) => {
- *     // Implementation
- *     return results;
- *   }
+ * 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.
  *
- * // Remote MCP server
- * const apiServer = mcpServer({
- *   name: 'external_api',
- *   description: 'External API service',
- *   serverUrl: 'https://api.example.com/mcp'
+ * 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 mcpServer(config: {
-    name: string;
-    description: string;
-    deployment?: "local" | "remote";
-    execute?: (params: any) => Promise<any>;
-    port?: number;
-    serverUrl?: string;
-    id?: string;
-    parameters?: Record<string, z.ZodJSONSchema>;
-    credential?: CredentialReferenceApiInsert;
-    tenantId?: string;
-    transport?: keyof typeof MCPTransportType;
-    activeTools?: string[];
-    headers?: Record<string, string>;
-}): Tool;
-declare function mcpTool(config: MCPToolConfig$1): Tool;
-declare function transfer(targetAgent: Agent, description?: string, condition?: (context: unknown) => boolean): TransferConfig;
+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 with auto-generated ID
+ * @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: '...' }
+ *   summaryProps: {
+ *     title: 'Product',
+ *     price: '$0'
+ *   },
+ *   fullProps: {
+ *     title: 'Product',
+ *     price: '$0',
+ *     description: 'Product description',
+ *     image: 'product.jpg'
+ *   }
  * });
  * ```
  */
-declare function artifactComponent(config: {
-    name: string;
-    description: string;
-    summaryProps: Record<string, any>;
-    fullProps: Record<string, any>;
-    tenantId?: string;
-    projectId?: string;
-}): ArtifactComponent;
+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 with auto-generated ID
+ * @returns A DataComponent instance
  *
  * @example
  * ```typescript
  * const userProfile = dataComponent({
  *   name: 'User Profile',
  *   description: 'User profile data',
- *   props: { userId: '123', name: 'John Doe' }
+ *   props: {
+ *     userId: '123',
+ *     name: 'John Doe',
+ *     email: 'john@example.com'
+ *   }
  * });
  * ```
  */
-declare function dataComponent(config: {
-    name: string;
-    description: string;
-    props: Record<string, any>;
-    tenantId?: string;
-    projectId?: string;
-}): DataComponent;
+declare function dataComponent(config: DataComponentConfig): DataComponent;
 
 interface EnvironmentSettingsConfig {
     credentials?: {
@@ -853,4 +913,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, tool, transfer };
+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 };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { __publicField, Tool } from './chunk-BCJFVUMJ.js';
 export { Tool } from './chunk-BCJFVUMJ.js';
-import { getLogger, generateIdFromName, CredentialReferenceApiInsertSchema, MCPToolConfigSchema, createDatabaseClient, getProject } from '@inkeep/agents-core';
+import { getLogger, generateIdFromName, MCPToolConfigSchema, CredentialReferenceApiInsertSchema, createDatabaseClient, getProject } from '@inkeep/agents-core';
 import { z } from 'zod';
 
 var logger = getLogger("artifactComponent");
@@ -330,11 +330,11 @@ var Agent = class {
       throw new Error("tools getter must return an array");
     }
     const toolRecord = {};
-    for (const tool2 of tools) {
-      if (tool2 && typeof tool2 === "object") {
-        const id = tool2.id || tool2.getId?.() || tool2.name;
+    for (const tool of tools) {
+      if (tool && typeof tool === "object") {
+        const id = tool.id || tool.getId?.() || tool.name;
         if (id) {
-          toolRecord[id] = tool2;
+          toolRecord[id] = tool;
         }
       }
     }
@@ -358,9 +358,9 @@ var Agent = class {
   getArtifactComponents() {
     return resolveGetter(this.config.artifactComponents) || [];
   }
-  addTool(_name, tool2) {
+  addTool(_name, tool) {
     const existingTools = this.config.tools ? this.config.tools() : [];
-    this.config.tools = () => [...existingTools, tool2];
+    this.config.tools = () => [...existingTools, tool];
   }
   addTransfer(...agents) {
     if (typeof this.config.canTransferTo === "function") {
@@ -615,7 +615,7 @@ var Agent = class {
         return;
       }
       const { Tool: Tool2 } = await import('./tool-6K5MVNKA.js');
-      let tool2;
+      let tool;
       if (toolConfig instanceof Tool2) {
         logger3.info(
           {
@@ -625,8 +625,8 @@ var Agent = class {
           },
           "Initializing Tool instance"
         );
-        tool2 = toolConfig;
-        await tool2.init();
+        tool = toolConfig;
+        await tool.init();
       } else {
         logger3.info(
           {
@@ -636,7 +636,7 @@ var Agent = class {
           },
           "Creating Tool from config"
         );
-        tool2 = new Tool2({
+        tool = new Tool2({
           id: toolId,
           tenantId: this.tenantId,
           name: toolConfig.name || toolId,
@@ -645,13 +645,13 @@ var Agent = class {
           activeTools: toolConfig.config?.mcp?.activeTools,
           credential: toolConfig.credential
         });
-        await tool2.init();
+        await tool.init();
       }
-      await this.createAgentToolRelation(tool2.getId());
+      await this.createAgentToolRelation(tool.getId());
       logger3.info(
         {
           agentId: this.getId(),
-          toolId: tool2.getId()
+          toolId: tool.getId()
         },
         "Tool created and linked to agent"
       );
@@ -809,89 +809,65 @@ var Agent = class {
     }
   }
 };
-function agent(config) {
-  return new Agent(config);
-}
-function credential(config) {
-  return CredentialReferenceApiInsertSchema.parse(config);
-}
-var ToolConfigSchema = z.object({
-  id: z.string().optional(),
-  name: z.string(),
-  description: z.string(),
-  parameters: z.record(z.string(), z.any()).optional(),
-  schema: z.unknown().optional()
-});
-ToolConfigSchema.extend({
-  execute: z.any()
-  // Function - validated separately at runtime
+var TransferConfigSchema = z.object({
+  agent: z.instanceof(Agent),
+  description: z.string().optional()
 });
-function tool(config) {
-  if (typeof config.execute !== "function") {
-    throw new Error("execute must be a function");
-  }
-  const { execute, ...configWithoutFunction } = config;
-  const validatedConfig = ToolConfigSchema.parse(configWithoutFunction);
-  const fullConfig = { ...validatedConfig, execute };
-  const computedId = fullConfig.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return {
-    id: computedId,
-    name: fullConfig.name,
-    description: fullConfig.description,
-    execute: fullConfig.execute,
-    parameters: fullConfig.parameters,
-    schema: fullConfig.schema,
-    type: "function"
-  };
+function generateIdFromName3(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function mcpServer(config) {
-  const deployment = config.deployment || (config.execute ? "local" : "remote");
-  const id = config.id || config.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  if (deployment === "local") {
-    if (!config.execute) {
-      throw new Error("Local MCP server requires an execute function");
-    }
+function validateFunction(value, name) {
+  if (typeof value !== "function") {
+    throw new Error(`${name} must be a function`);
+  }
+}
+function agent(config) {
+  if (!config.id) {
     throw new Error(
-      "Local MCP servers are no longer supported. Please use remote MCP servers instead."
+      "Agent ID is required. Agents must have stable IDs for consistency across deployments."
     );
-  } else {
-    if (!config.serverUrl) {
-      throw new Error("Remote MCP server requires a serverUrl");
-    }
-    return new Tool({
-      id,
-      name: config.name,
-      description: config.description,
-      serverUrl: config.serverUrl,
-      tenantId: config.tenantId,
-      credential: config.credential,
-      activeTools: config.activeTools,
-      headers: config.headers
-    });
   }
+  return new Agent(config);
+}
+function mcpServer(config) {
+  if (!config.serverUrl) {
+    throw new Error("MCP server requires a serverUrl");
+  }
+  const id = config.id || generateIdFromName3(config.name);
+  return new Tool({
+    id,
+    name: config.name,
+    description: config.description,
+    serverUrl: config.serverUrl,
+    tenantId: config.tenantId,
+    credential: config.credential,
+    activeTools: config.activeTools,
+    headers: config.headers,
+    imageUrl: config.imageUrl,
+    transport: config.transport ? { type: config.transport } : void 0
+  });
 }
 function mcpTool(config) {
   const validatedConfig = MCPToolConfigSchema.parse(config);
   return new Tool(validatedConfig);
 }
-var TransferConfigSchema = z.object({
-  agent: z.instanceof(Agent),
-  description: z.string().optional()
-});
-var TransferSchema = TransferConfigSchema.extend({
-  condition: z.any().optional()
-  // Function - validated separately at runtime when present
-});
+function credential(config) {
+  return CredentialReferenceApiInsertSchema.parse(config);
+}
 function transfer(targetAgent, description, condition) {
-  if (condition !== void 0 && typeof condition !== "function") {
-    throw new Error("condition must be a function when provided");
+  if (condition !== void 0) {
+    validateFunction(condition, "condition");
   }
   const config = {
     agent: targetAgent,
     description: description || `Hand off to ${targetAgent.getName()}`,
     condition
   };
-  return TransferSchema.parse(config);
+  TransferConfigSchema.parse({
+    agent: config.agent,
+    description: config.description
+  });
+  return config;
 }
 function artifactComponent(config) {
   return new ArtifactComponent({
@@ -2691,4 +2667,4 @@ var run = Runner.run.bind(Runner);
 var stream = Runner.stream.bind(Runner);
 var raceGraphs = Runner.raceGraphs.bind(Runner);
 
-export { Agent, AgentGraph, ArtifactComponent, DataComponent, ExternalAgent, Runner, agent, agentGraph, artifactComponent, createEnvironmentSettings, credential, dataComponent, externalAgent, externalAgents, generateGraph, mcpServer, mcpTool, raceGraphs, registerEnvironmentSettings, run, stream, tool, transfer };
+export { Agent, AgentGraph, ArtifactComponent, DataComponent, ExternalAgent, Runner, agent, agentGraph, artifactComponent, createEnvironmentSettings, credential, dataComponent, externalAgent, externalAgents, generateGraph, mcpServer, mcpTool, raceGraphs, registerEnvironmentSettings, run, stream, transfer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkeep/agents-sdk",
-  "version": "0.0.0-dev-20250911052037",
+  "version": "0.0.0-dev-20250911071658",
   "description": "SDK for building and managing agents in the Inkeep Agent Framework",
   "main": "dist/index.js",
   "type": "module",
@@ -8,10 +8,9 @@
   "dependencies": {
     "nanoid": "^5.1.5",
     "zod": "^4.1.5",
-    "@inkeep/agents-core": "^0.0.0-dev-20250911052037"
+    "@inkeep/agents-core": "^0.0.0-dev-20250911071658"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.1.4",
     "@types/node": "^20.11.24",
     "@vitest/coverage-v8": "^2.0.0",
     "clean-package": "^2.2.0",
@@ -56,7 +55,8 @@
     "test:watch": "ENVIRONMENT=test vitest",
     "test:coverage": "ENVIRONMENT=test vitest --run --coverage",
     "typecheck": "tsc --noEmit",
-    "lint": "biome check --apply .",
+    "lint": "biome lint .",
+    "lint:fix": "biome check --write .",
     "format": "biome format --write ."
   }
 }