@inkeep/agents-sdk 0.39.5 → 0.40.0

package/dist/builderFunctions.js

@@ -0,0 +1,327 @@
+import { generateIdFromName } from "./utils/generateIdFromName.js";
+import { FunctionTool } from "./function-tool.js";
+import { Agent } from "./agent.js";
+import { ArtifactComponent } from "./artifact-component.js";
+import { DataComponent } from "./data-component.js";
+import { Project } from "./project.js";
+import { StatusComponent as StatusComponent$1 } from "./status-component.js";
+import { Tool } from "./tool.js";
+import { SubAgent } from "./subAgent.js";
+import { CredentialReferenceApiInsertSchema, MCPToolConfigSchema } from "@inkeep/agents-core";
+
+//#region src/builderFunctions.ts
+/**
+* Helper function to create agent - OpenAI style
+*/
+function agent(config) {
+	return new Agent(config);
+}
+/**
+* Helper function to create projects - OpenAI style
+*
+* Projects are the top-level organizational unit that contains Agents, Sub Agents, and shared configurations.
+* They provide model inheritance and execution limits that cascade down to Agents and Sub Agents.
+*
+* @param config - Project configuration
+* @returns A new Project instance
+*
+* @example
+* ```typescript
+* const customerSupport = project({
+*   id: 'customer-support-project',
+*   name: 'Customer Support System',
+*   description: 'Multi-agent customer support system',
+*   models: {
+*     base: { model: 'gpt-4.1-mini' },
+*     structuredOutput: { model: 'gpt-4.1' }
+*   },
+*   stopWhen: {
+*     transferCountIs: 10,
+*     stepCountIs: 50
+*   },
+*   agent: () => [
+*     agent({
+*       id: 'support-agent',
+*       name: 'Support Agent',
+*       // ... agent config
+*     })
+*   ]
+* });
+* ```
+*/
+function project(config) {
+	return new Project(config);
+}
+/**
+* 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 SubAgent 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'
+* });
+* ```
+*/
+function subAgent(config) {
+	if (!config.id) throw new Error("Sub-Agent ID is required. Sub-Agents must have stable IDs for consistency across deployments.");
+	return new SubAgent(config);
+}
+/**
+* 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',
+*   name: 'GitHub Token',
+*   type: 'bearer',
+*   value: process.env.GITHUB_TOKEN
+* });
+* ```
+*/
+function credential(config) {
+	try {
+		return CredentialReferenceApiInsertSchema.parse(config);
+	} catch (error) {
+		if (error instanceof Error) {
+			const credId = config.id || "unknown";
+			throw new Error(`Invalid credential '${credId}': ${error.message}`);
+		}
+		throw error;
+	}
+}
+/**
+* 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',
+*     name: 'API Key',
+*     type: 'bearer',
+*     value: process.env.API_KEY
+*   })
+* });
+* ```
+*/
+function mcpServer(config) {
+	if (!config.serverUrl) throw new Error("MCP server requires a serverUrl");
+	return new Tool({
+		id: config.id || generateIdFromName(config.name),
+		name: config.name,
+		description: config.description,
+		serverUrl: config.serverUrl,
+		credential: config.credential,
+		activeTools: config.activeTools,
+		headers: config.headers,
+		imageUrl: config.imageUrl,
+		transport: config.transport ? { type: config.transport } : void 0
+	});
+}
+/**
+* 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' }
+* });
+* ```
+*/
+function mcpTool(config) {
+	const configWithId = {
+		...config,
+		id: config.id || generateIdFromName(config.name)
+	};
+	return new Tool(MCPToolConfigSchema.parse(configWithId));
+}
+/**
+* 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',
+*   props: {
+*     type: 'object',
+*     properties: {
+*       title: { type: 'string', inPreview: true },
+*       price: { type: 'string', inPreview: true },
+*       description: { type: 'string' },
+*       image: { type: 'string' }
+*     }
+*   }
+* });
+* ```
+*/
+function artifactComponent(config) {
+	return new ArtifactComponent({
+		...config,
+		id: config.id || generateIdFromName(config.name)
+	});
+}
+/**
+* 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'
+*   }
+* });
+* ```
+*/
+function dataComponent(config) {
+	return new DataComponent({
+		...config,
+		id: config.id || generateIdFromName(config.name)
+	});
+}
+/**
+* Creates a status component for structured status updates.
+*
+* Status components define the structure of status updates
+* that agents can generate during long-running operations.
+*
+* @param config - Status component configuration
+* @returns A StatusComponent instance
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+*
+* const toolCallStatus = statusComponent({
+*   type: 'tool_call_summary',
+*   description: 'Summary of a tool execution',
+*   detailsSchema: z.object({
+*     tool_name: z.string(),
+*     summary: z.string(),
+*     status: z.enum(['success', 'error', 'in_progress'])
+*   })
+* });
+* ```
+*/
+function statusComponent(config) {
+	return new StatusComponent$1(config);
+}
+/**
+* (deprecated in favor of mcpTool.with()) Creates an agent MCP configuration.
+*
+* Agent MCP configurations are used to configure the MCP server for an agent.
+*
+* @param config - Agent MCP configuration
+* @returns An AgentMcpConfig instance
+*/
+function agentMcp(config) {
+	return {
+		server: config.server,
+		selectedTools: config.selectedTools,
+		headers: config.headers
+	};
+}
+/**
+* Creates a function tool that executes user-defined code in a sandboxed environment.
+*
+* Function tools allow users to define custom logic that runs securely in isolated
+* environments. Dependencies are installed automatically in the sandbox.
+*
+* @param config - Function tool configuration
+* @returns A FunctionTool instance
+*
+* @example
+* ```typescript
+* const calculatorTool = functionTool({
+*   name: 'calculator',
+*   description: 'Performs basic math operations',
+*   inputSchema: {
+*     type: 'object',
+*     properties: {
+*       operation: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
+*       a: { type: 'number' },
+*       b: { type: 'number' }
+*     },
+*     required: ['operation', 'a', 'b']
+*   },
+*   dependencies: {
+*     'lodash': '^4.17.21'
+*   },
+*   execute: async (params) => {
+*     const { operation, a, b } = params;
+*     switch (operation) {
+*       case 'add': return { result: a + b };
+*       case 'subtract': return { result: a - b };
+*       case 'multiply': return { result: a * b };
+*       case 'divide': return { result: a / b };
+*       default: throw new Error(`Unknown operation: ${operation}`);
+*     }
+*   }
+* });
+* ```
+*/
+function functionTool(config) {
+	return new FunctionTool(config);
+}
+
+//#endregion
+export { agent, agentMcp, artifactComponent, credential, dataComponent, functionTool, mcpServer, mcpTool, project, statusComponent, subAgent };

package/dist/builderFunctionsExperimental.d.ts

@@ -0,0 +1,24 @@
+//#region src/builderFunctionsExperimental.d.ts
+/**
+ * Creates an agent relation configuration.
+ *
+ * Relations define how agents can interact with each other.
+ * Transfer relations allow transfers, while delegate relations
+ * allow temporary task delegation.
+ *
+ * @param targetAgent - The ID of the target agent
+ * @param relationType - The type of relation (transfer or delegate)
+ * @returns An agent relation configuration
+ *
+ * @example
+ * ```typescript
+ * const transferRelation = agentRelation('support-agent', 'transfer');
+ * const delegateRelation = agentRelation('specialist-agent', 'delegate');
+ * ```
+ */
+declare function agentRelation(targetAgent: string, relationType?: 'transfer' | 'delegate'): {
+  targetAgent: string;
+  relationType: "transfer" | "delegate";
+};
+//#endregion
+export { agentRelation };

package/dist/builderFunctionsExperimental.js

@@ -0,0 +1,27 @@
+//#region src/builderFunctionsExperimental.ts
+/**
+* Creates an agent relation configuration.
+*
+* Relations define how agents can interact with each other.
+* Transfer relations allow transfers, while delegate relations
+* allow temporary task delegation.
+*
+* @param targetAgent - The ID of the target agent
+* @param relationType - The type of relation (transfer or delegate)
+* @returns An agent relation configuration
+*
+* @example
+* ```typescript
+* const transferRelation = agentRelation('support-agent', 'transfer');
+* const delegateRelation = agentRelation('specialist-agent', 'delegate');
+* ```
+*/
+function agentRelation(targetAgent, relationType = "transfer") {
+	return {
+		targetAgent,
+		relationType
+	};
+}
+
+//#endregion
+export { agentRelation };

package/dist/builders.d.ts

@@ -0,0 +1,111 @@
+import { Tool } from "./tool.js";
+import { SubAgent } from "./subAgent.js";
+import { TransferConfig } from "./types.js";
+import { CredentialReferenceApiInsert, McpToolSelection, ToolPolicy } from "@inkeep/agents-core";
+import { z } from "zod";
+
+//#region src/builders.d.ts
+
+/**
+ * Function signature for tool execution
+ * @template TParams - Type of input parameters
+ * @template TResult - Type of return value
+ */
+type ToolExecuteFunction<TParams = unknown, TResult = unknown> = (params: TParams) => Promise<TResult>;
+/**
+ * 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;
+  transport?: 'streamable_http' | 'sse';
+  activeTools?: string[];
+  headers?: Record<string, string>;
+  imageUrl?: string;
+}
+/**
+ * Configuration for component builders
+ */
+interface ComponentConfig {
+  id?: string;
+  name: string;
+  description: string;
+}
+interface ArtifactComponentConfig extends ComponentConfig {
+  props: Record<string, unknown> | z.ZodObject<any>;
+}
+interface DataComponentConfig extends ComponentConfig {
+  props: Record<string, unknown> | z.ZodObject<any>;
+  render?: {
+    component: string;
+    mockData: Record<string, unknown>;
+  };
+}
+interface StatusComponentConfig {
+  type: string;
+  description?: string;
+  detailsSchema?: Record<string, unknown> | z.ZodObject<any>;
+}
+/**
+ * Schema for transfer configuration (excluding function properties)
+ */
+declare const TransferConfigSchema: z.ZodObject<{
+  agent: z.ZodCustom<SubAgent, SubAgent>;
+  description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AgentMcpConfig = {
+  server: Tool;
+  selectedTools?: string[];
+  headers?: Record<string, string>;
+  toolPolicies?: Record<string, ToolPolicy>;
+};
+/**
+ * Input configuration for MCP tool customization
+ * Supports flexible tool selection with per-tool policies
+ */
+type AgentMcpConfigInput = {
+  /**
+   * Tools to enable from the MCP server - can be strings or objects with policies
+   * - undefined or null: all tools enabled (no filtering)
+   * - []: zero tools enabled (explicit empty selection)
+   * - ['tool1', 'tool2']: specific tools enabled
+   */
+  selectedTools?: McpToolSelection[] | null;
+  /** Custom headers for MCP server requests */
+  headers?: Record<string, string>;
+};
+/**
+ * Creates a transfer configuration for agent transfers.
+ *
+ * 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 transfer = 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: SubAgent, description?: string, condition?: TransferConditionFunction): TransferConfig;
+//#endregion
+export { AgentMcpConfig, AgentMcpConfigInput, ArtifactComponentConfig, ComponentConfig, DataComponentConfig, MCPServerConfig, StatusComponentConfig, ToolExecuteFunction, TransferConditionFunction, TransferConfigSchema, transfer };

package/dist/builders.js

@@ -0,0 +1,52 @@
+import { SubAgent } from "./subAgent.js";
+import { validateFunction } from "./utils/validateFunction.js";
+import { z } from "zod";
+
+//#region src/builders.ts
+/**
+* Schema for transfer configuration (excluding function properties)
+*/
+const TransferConfigSchema = z.object({
+	agent: z.instanceof(SubAgent),
+	description: z.string().optional()
+});
+/**
+* Creates a transfer configuration for agent transfers.
+*
+* 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 transfer = transfer(supportAgent, 'Transfer to support');
+*
+* // Conditional transfer
+* const conditionalHandoff = transfer(
+*   specialistAgent,
+*   'Transfer to specialist for complex issues',
+*   (context) => context.complexity > 0.8
+* );
+* ```
+*/
+function transfer(targetAgent, description, condition) {
+	if (condition !== void 0) validateFunction(condition, "condition");
+	const config = {
+		agent: targetAgent,
+		description: description || `Hand off to ${targetAgent.getName()}`,
+		condition
+	};
+	TransferConfigSchema.parse({
+		agent: config.agent,
+		description: config.description
+	});
+	return config;
+}
+
+//#endregion
+export { TransferConfigSchema, transfer };