@inkeep/agents-sdk 0.39.4 → 0.40.0

package/dist/agentFullClient.d.ts

@@ -0,0 +1,22 @@
+import { FullAgentDefinition } from "@inkeep/agents-core";
+
+//#region src/agentFullClient.d.ts
+
+/**
+ * Create a full agent via HTTP API
+ */
+declare function createFullAgentViaAPI(tenantId: string, projectId: string, apiUrl: string, agentData: FullAgentDefinition): Promise<FullAgentDefinition>;
+/**
+ * Update a full agent via HTTP API (upsert behavior)
+ */
+declare function updateFullAgentViaAPI(tenantId: string, projectId: string, apiUrl: string, agentId: string, agentData: FullAgentDefinition): Promise<FullAgentDefinition>;
+/**
+ * Get a full agent via HTTP API
+ */
+declare function getFullAgentViaAPI(tenantId: string, projectId: string, apiUrl: string, agentId: string): Promise<FullAgentDefinition | null>;
+/**
+ * Delete a full agent via HTTP API
+ */
+declare function deleteFullAgentViaAPI(tenantId: string, projectId: string, apiUrl: string, agentId: string): Promise<void>;
+//#endregion
+export { createFullAgentViaAPI, deleteFullAgentViaAPI, getFullAgentViaAPI, updateFullAgentViaAPI };

package/dist/agentFullClient.js

@@ -0,0 +1,120 @@
+import { parseError } from "./projectFullClient.js";
+import { getLogger } from "@inkeep/agents-core";
+
+//#region src/agentFullClient.ts
+const logger = getLogger("agentFullClient");
+/**
+* Create a full agent via HTTP API
+*/
+async function createFullAgentViaAPI(tenantId, projectId, apiUrl, agentData) {
+	logger.info({
+		tenantId,
+		projectId,
+		agentId: agentData.id,
+		apiUrl
+	}, "Creating full agent via API");
+	const url = `${apiUrl}/tenants/${tenantId}/projects/${projectId}/agent`;
+	const response = await fetch(url, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(agentData)
+	});
+	if (!response.ok) {
+		const errorMessage = parseError(await response.text()) ?? `Failed to create agent: ${response.status} ${response.statusText}`;
+		logger.error({
+			status: response.status,
+			error: errorMessage
+		}, "Failed to create agent via API");
+		throw new Error(errorMessage);
+	}
+	const result = await response.json();
+	logger.info({ agentId: agentData.id }, "Successfully created agent via API");
+	return result.data;
+}
+/**
+* Update a full agent via HTTP API (upsert behavior)
+*/
+async function updateFullAgentViaAPI(tenantId, projectId, apiUrl, agentId, agentData) {
+	logger.info({
+		tenantId,
+		projectId,
+		agentId,
+		apiUrl
+	}, "Updating full agent via API");
+	const url = `${apiUrl}/tenants/${tenantId}/projects/${projectId}/agent/${agentId}`;
+	const response = await fetch(url, {
+		method: "PUT",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(agentData)
+	});
+	if (!response.ok) {
+		const errorMessage = parseError(await response.text()) ?? `Failed to update agent: ${response.status} ${response.statusText}`;
+		logger.error({
+			status: response.status,
+			error: errorMessage
+		}, "Failed to update agent via API");
+		throw new Error(errorMessage);
+	}
+	const result = await response.json();
+	logger.info({ agentId }, "Successfully updated agent via API");
+	return result.data;
+}
+/**
+* Get a full agent via HTTP API
+*/
+async function getFullAgentViaAPI(tenantId, projectId, apiUrl, agentId) {
+	logger.info({
+		tenantId,
+		projectId,
+		agentId,
+		apiUrl
+	}, "Getting full agent via API");
+	const url = `${apiUrl}/tenants/${tenantId}/projects/${projectId}/agent/${agentId}`;
+	const response = await fetch(url, {
+		method: "GET",
+		headers: { "Content-Type": "application/json" }
+	});
+	if (!response.ok) {
+		if (response.status === 404) {
+			logger.info({ agentId }, "Agent not found");
+			return null;
+		}
+		const errorMessage = parseError(await response.text()) ?? `Failed to get agent: ${response.status} ${response.statusText}`;
+		logger.error({
+			status: response.status,
+			error: errorMessage
+		}, "Failed to get agent via API");
+		throw new Error(errorMessage);
+	}
+	const result = await response.json();
+	logger.info({ agentId }, "Successfully retrieved agent via API");
+	return result.data;
+}
+/**
+* Delete a full agent via HTTP API
+*/
+async function deleteFullAgentViaAPI(tenantId, projectId, apiUrl, agentId) {
+	logger.info({
+		tenantId,
+		projectId,
+		agentId,
+		apiUrl
+	}, "Deleting full agent via API");
+	const url = `${apiUrl}/tenants/${tenantId}/projects/${projectId}/agent/${agentId}`;
+	const response = await fetch(url, {
+		method: "DELETE",
+		headers: { "Content-Type": "application/json" }
+	});
+	if (!response.ok) {
+		const errorMessage = parseError(await response.text()) ?? `Failed to delete agent: ${response.status} ${response.statusText}`;
+		logger.error({
+			status: response.status,
+			error: errorMessage
+		}, "Failed to delete agent via API");
+		throw new Error(errorMessage);
+	}
+	logger.info({ agentId }, "Successfully deleted agent via API");
+}
+
+//#endregion
+export { createFullAgentViaAPI, deleteFullAgentViaAPI, getFullAgentViaAPI, updateFullAgentViaAPI };

package/dist/artifact-component.d.ts

@@ -0,0 +1,34 @@
+import { ArtifactComponentInsert } from "@inkeep/agents-core";
+import { z } from "zod";
+
+//#region src/artifact-component.d.ts
+type ArtifactComponentConfigWithZod = Omit<ArtifactComponentInsert, 'tenantId' | 'projectId' | 'props'> & {
+  props?: Record<string, unknown> | z.ZodObject<any> | null;
+};
+interface ArtifactComponentInterface {
+  config: Omit<ArtifactComponentInsert, 'tenantId' | 'projectId'>;
+  init(): Promise<void>;
+  getId(): ArtifactComponentInsert['id'];
+  getName(): ArtifactComponentInsert['name'];
+  getDescription(): ArtifactComponentInsert['description'];
+  getProps(): ArtifactComponentInsert['props'];
+  setContext(tenantId: string, projectId: string, baseURL?: string): void;
+}
+declare class ArtifactComponent implements ArtifactComponentInterface {
+  config: Omit<ArtifactComponentInsert, 'tenantId' | 'projectId'>;
+  private baseURL;
+  private tenantId;
+  private projectId;
+  private initialized;
+  private id;
+  constructor(config: ArtifactComponentConfigWithZod);
+  setContext(tenantId: string, projectId: string, baseURL?: string): void;
+  getId(): string;
+  getName(): string;
+  getDescription(): string;
+  getProps(): ArtifactComponentInsert['props'];
+  init(): Promise<void>;
+  private upsertArtifactComponent;
+}
+//#endregion
+export { ArtifactComponent, ArtifactComponentInterface };

package/dist/artifact-component.js

@@ -0,0 +1,104 @@
+import { generateIdFromName } from "./utils/generateIdFromName.js";
+import { getLogger } from "@inkeep/agents-core";
+import { convertZodToJsonSchemaWithPreview, isZodSchema } from "@inkeep/agents-core/utils/schema-conversion";
+
+//#region src/artifact-component.ts
+const logger = getLogger("artifactComponent");
+var ArtifactComponent = class {
+	config;
+	baseURL;
+	tenantId;
+	projectId;
+	initialized = false;
+	id;
+	constructor(config) {
+		this.id = config.id || generateIdFromName(config.name);
+		let processedProps;
+		if (config.props && isZodSchema(config.props)) processedProps = convertZodToJsonSchemaWithPreview(config.props);
+		else processedProps = config.props;
+		this.config = {
+			...config,
+			id: this.id,
+			props: processedProps
+		};
+		this.baseURL = process.env.INKEEP_API_URL || "http://localhost:3002";
+		this.tenantId = "default";
+		this.projectId = "default";
+		logger.info({
+			artifactComponentId: this.getId(),
+			artifactComponentName: config.name
+		}, "ArtifactComponent constructor initialized");
+	}
+	setContext(tenantId, projectId, baseURL) {
+		this.tenantId = tenantId;
+		this.projectId = projectId;
+		if (baseURL) this.baseURL = baseURL;
+	}
+	getId() {
+		return this.id;
+	}
+	getName() {
+		return this.config.name;
+	}
+	getDescription() {
+		return this.config.description || "";
+	}
+	getProps() {
+		return this.config.props;
+	}
+	async init() {
+		if (this.initialized) return;
+		try {
+			await this.upsertArtifactComponent();
+			logger.info({ artifactComponentId: this.getId() }, "ArtifactComponent initialized successfully");
+			this.initialized = true;
+		} catch (error) {
+			logger.error({
+				artifactComponentId: this.getId(),
+				error: error instanceof Error ? error.message : "Unknown error"
+			}, "Failed to initialize artifact component");
+			throw error;
+		}
+	}
+	async upsertArtifactComponent() {
+		const artifactComponentData = {
+			id: this.getId(),
+			name: this.config.name,
+			description: this.config.description,
+			props: this.config.props
+		};
+		logger.info({ artifactComponentData }, "artifactComponentData for create/update");
+		const updateResponse = await fetch(`${this.baseURL}/tenants/${this.tenantId}/projects/${this.projectId}/artifact-components/${this.getId()}`, {
+			method: "PUT",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(artifactComponentData)
+		});
+		logger.info({
+			status: updateResponse.status,
+			artifactComponentId: this.getId()
+		}, "artifact component updateResponse");
+		if (updateResponse.ok) {
+			logger.info({ artifactComponentId: this.getId() }, "ArtifactComponent updated successfully");
+			return;
+		}
+		if (updateResponse.status === 404) {
+			logger.info({ artifactComponentId: this.getId() }, "ArtifactComponent not found, creating new artifact component");
+			const createResponse = await fetch(`${this.baseURL}/tenants/${this.tenantId}/projects/${this.projectId}/artifact-components`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(artifactComponentData)
+			});
+			if (!createResponse.ok) {
+				const errorText$1 = await createResponse.text().catch(() => "Unknown error");
+				throw new Error(`Failed to create artifact component: ${createResponse.status} ${createResponse.statusText} - ${errorText$1}`);
+			}
+			logger.info({ artifactComponentId: this.getId() }, "ArtifactComponent created successfully");
+			return;
+		}
+		const errorText = await updateResponse.text().catch(() => "Unknown error");
+		throw new Error(`Failed to update artifact component: ${updateResponse.status} ${updateResponse.statusText} - ${errorText}`);
+	}
+};
+
+//#endregion
+export { ArtifactComponent };

package/dist/builderFunctions.d.ts

@@ -0,0 +1,283 @@
+import { ArtifactComponent } from "./artifact-component.js";
+import { Tool } from "./tool.js";
+import { SubAgent } from "./subAgent.js";
+import { AgentMcpConfig, ArtifactComponentConfig, DataComponentConfig, MCPServerConfig, StatusComponentConfig } from "./builders.js";
+import { DataComponent } from "./data-component.js";
+import { FunctionTool } from "./function-tool.js";
+import { AgentConfig, FunctionToolConfig, SubAgentConfig } from "./types.js";
+import { Agent } from "./agent.js";
+import { Project, ProjectConfig } from "./project.js";
+import { StatusComponent as StatusComponent$1 } from "./status-component.js";
+import { CredentialReferenceApiInsert, MCPToolConfig } from "@inkeep/agents-core";
+
+//#region src/builderFunctions.d.ts
+
+/**
+ * Helper function to create agent - OpenAI style
+ */
+declare function agent(config: AgentConfig): Agent;
+/**
+ * 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
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+declare function project(config: ProjectConfig): Project;
+/**
+ * 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'
+ * });
+ * ```
+ */
+declare function subAgent(config: SubAgentConfig): SubAgent;
+/**
+ * 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
+ * });
+ * ```
+ */
+declare function credential(config: CredentialReferenceApiInsert): {
+  id: string;
+  name: string;
+  credentialStoreId: string;
+  type: "memory" | "keychain" | "nango";
+  createdAt?: string | undefined;
+  updatedAt?: string | undefined;
+  retrievalParams?: Record<string, unknown> | null | undefined;
+  userId?: string | null | undefined;
+  toolId?: string | null | undefined;
+  createdBy?: string | 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',
+ *     name: '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): 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',
+ *   props: {
+ *     type: 'object',
+ *     properties: {
+ *       title: { type: 'string', inPreview: true },
+ *       price: { type: 'string', inPreview: true },
+ *       description: { type: 'string' },
+ *       image: { type: 'string' }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+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;
+/**
+ * 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'])
+ *   })
+ * });
+ * ```
+ */
+declare function statusComponent(config: StatusComponentConfig): StatusComponent$1;
+/**
+ * (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
+ */
+declare function agentMcp(config: AgentMcpConfig): AgentMcpConfig;
+/**
+ * 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}`);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function functionTool(config: FunctionToolConfig): FunctionTool;
+//#endregion
+export { agent, agentMcp, artifactComponent, credential, dataComponent, functionTool, mcpServer, mcpTool, project, statusComponent, subAgent };