@inkeep/agents-sdk 0.39.4 → 0.40.0

package/dist/project.js

@@ -0,0 +1,615 @@
+import { updateFullProjectViaAPI } from "./projectFullClient.js";
+import { FunctionTool } from "./function-tool.js";
+import { getLogger } from "@inkeep/agents-core";
+
+//#region src/project.ts
+const logger = getLogger("project");
+/**
+* Project class for managing agent projects
+*
+* 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.
+*
+* @example
+* ```typescript
+* const myProject = new 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
+*   }
+* });
+*
+* await myProject.init();
+* ```
+*/
+var Project = class {
+	__type = "project";
+	projectId;
+	projectName;
+	projectDescription;
+	tenantId;
+	baseURL;
+	apiKey;
+	initialized = false;
+	models;
+	stopWhen;
+	agents = [];
+	agentMap = /* @__PURE__ */ new Map();
+	credentialReferences = [];
+	projectTools = [];
+	projectDataComponents = [];
+	projectArtifactComponents = [];
+	projectExternalAgents = [];
+	externalAgentMap = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this.projectId = config.id;
+		this.projectName = config.name;
+		this.projectDescription = config.description;
+		this.tenantId = process.env.INKEEP_TENANT_ID || "default";
+		this.baseURL = process.env.INKEEP_API_URL || "http://localhost:3002";
+		this.models = config.models;
+		this.stopWhen = config.stopWhen;
+		if (config.agents) {
+			this.agents = config.agents();
+			this.agentMap = new Map(this.agents.map((agent) => [agent.getId(), agent]));
+			for (const agent of this.agents) agent.setConfig(this.tenantId, this.projectId, this.baseURL);
+		}
+		if (config.tools) this.projectTools = config.tools();
+		if (config.dataComponents) this.projectDataComponents = config.dataComponents();
+		if (config.artifactComponents) this.projectArtifactComponents = config.artifactComponents();
+		if (config.credentialReferences) this.credentialReferences = config.credentialReferences();
+		if (config.externalAgents) {
+			this.projectExternalAgents = config.externalAgents();
+			this.externalAgentMap = new Map(this.projectExternalAgents.map((externalAgent) => [externalAgent.getId(), externalAgent]));
+		}
+		logger.info({
+			projectId: this.projectId,
+			tenantId: this.tenantId,
+			agentCount: this.agents.length
+		}, "Project created");
+	}
+	/**
+	* Set or update the configuration (tenantId and apiUrl)
+	* This is used by the CLI to inject configuration from inkeep.config.ts
+	*/
+	setConfig(tenantId, apiUrl, models, apiKey) {
+		if (this.initialized) throw new Error("Cannot set config after project has been initialized");
+		this.tenantId = tenantId;
+		this.baseURL = apiUrl;
+		this.apiKey = apiKey;
+		if (models) this.models = models;
+		for (const agent of this.agents) agent.setConfig(tenantId, this.projectId, apiUrl);
+		logger.info({
+			projectId: this.projectId,
+			tenantId: this.tenantId,
+			apiUrl: this.baseURL,
+			hasModels: !!this.models,
+			hasApiKey: !!this.apiKey
+		}, "Project configuration updated");
+	}
+	/**
+	* Set credential references for the project
+	* This is used by the CLI to inject environment-specific credentials
+	*/
+	setCredentials(credentials) {
+		this.credentialReferences = Object.values(credentials);
+		logger.info({
+			projectId: this.projectId,
+			credentialCount: this.credentialReferences?.length || 0
+		}, "Project credentials updated");
+	}
+	/**
+	* Initialize the project and create/update it in the backend using full project approach
+	*/
+	async init() {
+		if (this.initialized) {
+			logger.info({ projectId: this.projectId }, "Project already initialized");
+			return;
+		}
+		logger.info({
+			projectId: this.projectId,
+			tenantId: this.tenantId,
+			agentCount: this.agents.length
+		}, "Initializing project using full project endpoint");
+		try {
+			const projectDefinition = await this.toFullProjectDefinition();
+			logger.info({
+				projectId: this.projectId,
+				mode: "api-client",
+				apiUrl: this.baseURL
+			}, "Using API client to create/update full project");
+			const createdProject = await updateFullProjectViaAPI(this.tenantId, this.baseURL, this.projectId, projectDefinition, this.apiKey);
+			this.initialized = true;
+			logger.info({
+				projectId: this.projectId,
+				tenantId: this.tenantId,
+				agentCount: Object.keys(createdProject.agent || {}).length
+			}, "Project initialized successfully using full project endpoint");
+		} catch (error) {
+			logger.error({
+				projectId: this.projectId,
+				error: error instanceof Error ? error.message : "Unknown error"
+			}, "Failed to initialize project using full project endpoint");
+			throw error;
+		}
+	}
+	/**
+	* Get the project ID
+	*/
+	getId() {
+		return this.projectId;
+	}
+	/**
+	* Get the project name
+	*/
+	getName() {
+		return this.projectName;
+	}
+	/**
+	* Get the project description
+	*/
+	getDescription() {
+		return this.projectDescription;
+	}
+	/**
+	* Get the tenant ID
+	*/
+	getTenantId() {
+		return this.tenantId;
+	}
+	/**
+	* Get the project's model configuration
+	*/
+	getModels() {
+		return this.models;
+	}
+	/**
+	* Set the project's model configuration
+	*/
+	setModels(models) {
+		this.models = models;
+	}
+	/**
+	* Get the project's stopWhen configuration
+	*/
+	getStopWhen() {
+		return this.stopWhen;
+	}
+	/**
+	* Set the project's stopWhen configuration
+	*/
+	setStopWhen(stopWhen) {
+		this.stopWhen = stopWhen;
+	}
+	/**
+	* Get credential tracking information
+	*/
+	async getCredentialTracking() {
+		const credentials = (await this.toFullProjectDefinition()).credentialReferences || {};
+		const usage = {};
+		for (const [credId, credData] of Object.entries(credentials)) if (credData.usedBy) usage[credId] = credData.usedBy;
+		return {
+			credentials,
+			usage
+		};
+	}
+	async getFullDefinition() {
+		return await this.toFullProjectDefinition();
+	}
+	/**
+	* Get all agent in the project
+	*/
+	getAgents() {
+		return this.agents;
+	}
+	/**
+	* Get all external agents in the project
+	*/
+	getExternalAgents() {
+		return this.projectExternalAgents;
+	}
+	/**
+	* Get an external agent by ID
+	*/
+	getExternalAgent(id) {
+		return this.externalAgentMap.get(id);
+	}
+	/**
+	* Add an external agent to the project
+	*/
+	addExternalAgent(externalAgent) {
+		this.projectExternalAgents.push(externalAgent);
+		this.externalAgentMap.set(externalAgent.getId(), externalAgent);
+	}
+	/**
+	* Remove an external agent from the project
+	*/
+	removeExternalAgent(id) {
+		if (this.externalAgentMap.get(id)) {
+			this.externalAgentMap.delete(id);
+			this.projectExternalAgents = this.projectExternalAgents.filter((externalAgent) => externalAgent.getId() !== id);
+			logger.info({
+				projectId: this.projectId,
+				externalAgentId: id
+			}, "External agent removed from project");
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Get an agent by ID
+	*/
+	getAgent(id) {
+		return this.agentMap.get(id);
+	}
+	/**
+	* Add an agent to the project
+	*/
+	addAgent(agent) {
+		this.agents.push(agent);
+		this.agentMap.set(agent.getId(), agent);
+		agent.setConfig(this.tenantId, this.projectId, this.baseURL);
+		logger.info({
+			projectId: this.projectId,
+			agentId: agent.getId()
+		}, "Agent added to project");
+	}
+	/**
+	* Remove an agent from the project
+	*/
+	removeAgent(id) {
+		if (this.agentMap.get(id)) {
+			this.agentMap.delete(id);
+			this.agents = this.agents.filter((agent) => agent.getId() !== id);
+			logger.info({
+				projectId: this.projectId,
+				agentId: id
+			}, "Agent removed from project");
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Get project statistics
+	*/
+	getStats() {
+		return {
+			projectId: this.projectId,
+			tenantId: this.tenantId,
+			agentCount: this.agents.length,
+			initialized: this.initialized
+		};
+	}
+	/**
+	* Validate the project configuration
+	*/
+	validate() {
+		const errors = [];
+		if (!this.projectId) errors.push("Project must have an ID");
+		if (!this.projectName) errors.push("Project must have a name");
+		const agentIds = /* @__PURE__ */ new Set();
+		for (const agent of this.agents) {
+			const id = agent.getId();
+			if (agentIds.has(id)) errors.push(`Duplicate agent ID: ${id}`);
+			agentIds.add(id);
+		}
+		for (const agent of this.agents) {
+			const agentValidation = agent.validate();
+			if (!agentValidation.valid) errors.push(...agentValidation.errors.map((error) => `Agent '${agent.getId()}': ${error}`));
+		}
+		return {
+			valid: errors.length === 0,
+			errors
+		};
+	}
+	/**
+	* Convert the Project to FullProjectDefinition format
+	*/
+	async toFullProjectDefinition() {
+		const agentsObject = {};
+		const toolsObject = {};
+		const functionToolsObject = {};
+		const functionsObject = {};
+		const dataComponentsObject = {};
+		const artifactComponentsObject = {};
+		const credentialReferencesObject = {};
+		const externalAgentsObject = {};
+		const credentialUsageMap = {};
+		for (const agent of this.agents) {
+			logger.info({ agentId: agent.getId() }, "Agent id");
+			const agentDefinition = await agent.toFullAgentDefinition();
+			agentsObject[agent.getId()] = agentDefinition;
+			const agentCredentials = agent.credentials;
+			if (agentCredentials && Array.isArray(agentCredentials)) for (const credential of agentCredentials) {
+				if (credential?.__type === "credential-ref") continue;
+				if (credential?.id) {
+					if (!credentialReferencesObject[credential.id]) {
+						credentialReferencesObject[credential.id] = {
+							id: credential.id,
+							name: credential.name,
+							type: credential.type,
+							credentialStoreId: credential.credentialStoreId,
+							retrievalParams: credential.retrievalParams
+						};
+						credentialUsageMap[credential.id] = [];
+					}
+					credentialUsageMap[credential.id].push({
+						type: "agent",
+						id: agent.getId()
+					});
+				}
+			}
+			const agentContextConfig = agent.contextConfig;
+			if (agentContextConfig) {
+				const contextVariables = agentContextConfig.getContextVariables?.() || agentContextConfig.contextVariables;
+				if (contextVariables) {
+					for (const [key, variable] of Object.entries(contextVariables)) if (variable?.credential) {
+						const credential = variable.credential;
+						let credId;
+						if (credential.__type === "credential-ref") {
+							credId = credential.id;
+							if (credId && this.credentialReferences) {
+								const resolvedCred = this.credentialReferences.find((c) => c.id === credId);
+								if (resolvedCred && !credentialReferencesObject[credId]) {
+									credentialReferencesObject[credId] = resolvedCred;
+									credentialUsageMap[credId] = [];
+								}
+							}
+						} else if (credential.id) {
+							credId = credential.id;
+							if (credId && !credentialReferencesObject[credId]) {
+								credentialReferencesObject[credId] = credential;
+								credentialUsageMap[credId] = [];
+							}
+						}
+						if (credId) {
+							if (!credentialUsageMap[credId]) credentialUsageMap[credId] = [];
+							credentialUsageMap[credId].push({
+								type: "contextVariable",
+								id: key,
+								agentId: agent.getId()
+							});
+						}
+					} else if (variable?.credentialReferenceId) {
+						const credId = variable.credentialReferenceId;
+						if (!credentialUsageMap[credId]) credentialUsageMap[credId] = [];
+						credentialUsageMap[credId].push({
+							type: "contextVariable",
+							id: key,
+							agentId: agent.getId()
+						});
+					}
+				}
+			}
+			for (const subAgent of agent.getSubAgents()) {
+				const agentTools = subAgent.getTools();
+				for (const [, toolInstance] of Object.entries(agentTools)) {
+					const actualTool = toolInstance;
+					const toolId = actualTool.getId();
+					if (actualTool.constructor.name === "FunctionTool" && actualTool instanceof FunctionTool) {
+						if (!functionsObject[toolId]) functionsObject[toolId] = actualTool.serializeFunction();
+						if (!functionToolsObject[toolId]) {
+							const toolData = actualTool.serializeTool();
+							functionToolsObject[toolId] = {
+								id: toolData.id,
+								name: toolData.name,
+								description: toolData.description,
+								functionId: toolData.functionId
+							};
+						}
+					} else if (!toolsObject[toolId]) {
+						if ("config" in actualTool && "serverUrl" in actualTool.config) {
+							const mcpTool = actualTool;
+							const toolConfig = {
+								type: "mcp",
+								mcp: {
+									server: { url: mcpTool.config.serverUrl },
+									transport: mcpTool.config.transport,
+									activeTools: mcpTool.config.activeTools
+								}
+							};
+							const toolData = {
+								id: toolId,
+								name: actualTool.getName(),
+								config: toolConfig
+							};
+							if (mcpTool.config?.imageUrl) toolData.imageUrl = mcpTool.config.imageUrl;
+							if (mcpTool.config?.headers) toolData.headers = mcpTool.config.headers;
+							if ("getCredentialReferenceId" in actualTool) {
+								const credentialId = actualTool.getCredentialReferenceId();
+								if (credentialId) toolData.credentialReferenceId = credentialId;
+							}
+							if ("credential" in mcpTool.config && mcpTool.config.credential) {
+								const credential = mcpTool.config.credential;
+								if (credential?.id && credential.__type !== "credential-ref") {
+									if (!credentialReferencesObject[credential.id]) {
+										credentialReferencesObject[credential.id] = {
+											id: credential.id,
+											name: credential.name,
+											type: credential.type,
+											credentialStoreId: credential.credentialStoreId,
+											retrievalParams: credential.retrievalParams
+										};
+										credentialUsageMap[credential.id] = [];
+									}
+									credentialUsageMap[credential.id].push({
+										type: "tool",
+										id: toolId
+									});
+								}
+							}
+							toolsObject[toolId] = toolData;
+						}
+					}
+				}
+				const subAgentDataComponents = subAgent.getDataComponents?.();
+				if (subAgentDataComponents) for (const dataComponent of subAgentDataComponents) {
+					let dataComponentId;
+					let dataComponentName;
+					let dataComponentDescription;
+					let dataComponentProps;
+					let dataComponentRender;
+					if (dataComponent.getId) {
+						dataComponentId = dataComponent.getId();
+						dataComponentName = dataComponent.getName();
+						dataComponentDescription = dataComponent.getDescription() || "";
+						dataComponentProps = dataComponent.getProps() || {};
+						dataComponentRender = dataComponent.getRender?.() || null;
+					} else {
+						dataComponentId = dataComponent.id || (dataComponent.name ? dataComponent.name.toLowerCase().replace(/\s+/g, "-") : "");
+						dataComponentName = dataComponent.name || "";
+						dataComponentDescription = dataComponent.description || "";
+						dataComponentProps = dataComponent.props || {};
+						dataComponentRender = dataComponent.render || null;
+					}
+					if (!dataComponentsObject[dataComponentId] && dataComponentName) dataComponentsObject[dataComponentId] = {
+						id: dataComponentId,
+						name: dataComponentName,
+						description: dataComponentDescription,
+						props: dataComponentProps,
+						render: dataComponentRender
+					};
+				}
+				const subAgentArtifactComponents = subAgent.getArtifactComponents();
+				if (subAgentArtifactComponents) for (const artifactComponent of subAgentArtifactComponents) {
+					let artifactComponentId;
+					let artifactComponentName;
+					let artifactComponentDescription;
+					let artifactComponentProps;
+					if ("getId" in artifactComponent && typeof artifactComponent.getId === "function") {
+						const component = artifactComponent;
+						artifactComponentId = component.getId();
+						artifactComponentName = component.getName();
+						artifactComponentDescription = component.getDescription() || "";
+						artifactComponentProps = component.getProps() || {};
+					} else {
+						artifactComponentId = artifactComponent.id || (artifactComponent.name ? artifactComponent.name.toLowerCase().replace(/\s+/g, "-") : "");
+						artifactComponentName = artifactComponent.name || "";
+						artifactComponentDescription = artifactComponent.description || "";
+						artifactComponentProps = artifactComponent.props || {};
+					}
+					if (!artifactComponentsObject[artifactComponentId] && artifactComponentName) artifactComponentsObject[artifactComponentId] = {
+						id: artifactComponentId,
+						name: artifactComponentName,
+						description: artifactComponentDescription,
+						props: artifactComponentProps
+					};
+				}
+				const subAgentExternalAgents = subAgent.getExternalAgentDelegates();
+				if (subAgentExternalAgents) for (const externalAgentDelegate of subAgentExternalAgents) {
+					const externalAgent = externalAgentDelegate.externalAgent;
+					const credential = externalAgent.getCredentialReference();
+					if (credential) {
+						if (!credentialReferencesObject[credential.id]) {
+							credentialReferencesObject[credential.id] = {
+								id: credential.id,
+								name: credential.name,
+								type: credential.type,
+								credentialStoreId: credential.credentialStoreId,
+								retrievalParams: credential.retrievalParams
+							};
+							credentialUsageMap[credential.id] = [];
+						}
+						logger.info({ credentialId: credential.id }, "Credential id in external agent");
+						credentialUsageMap[credential.id].push({
+							type: "externalAgent",
+							id: externalAgent.getId()
+						});
+					}
+					logger.info({ externalAgentId: externalAgent.getId() }, "External agent id");
+					externalAgentsObject[externalAgent.getId()] = {
+						id: externalAgent.getId(),
+						name: externalAgent.getName(),
+						description: externalAgent.getDescription(),
+						baseUrl: externalAgent.getBaseUrl(),
+						credentialReferenceId: externalAgent.getCredentialReferenceId()
+					};
+				}
+			}
+		}
+		logger.info({ externalAgentsObject }, "External agents object");
+		for (const tool of this.projectTools) {
+			const toolId = tool.getId();
+			if (!toolsObject[toolId]) {
+				const toolConfig = {
+					type: "mcp",
+					mcp: {
+						server: { url: tool.config.serverUrl },
+						transport: tool.config.transport,
+						activeTools: tool.config.activeTools
+					}
+				};
+				const toolData = {
+					id: toolId,
+					name: tool.getName(),
+					config: toolConfig
+				};
+				if (tool.config?.imageUrl) toolData.imageUrl = tool.config.imageUrl;
+				if (tool.config?.headers) toolData.headers = tool.config.headers;
+				const credentialId = tool.getCredentialReferenceId();
+				if (credentialId) toolData.credentialReferenceId = credentialId;
+				toolsObject[toolId] = toolData;
+			}
+		}
+		for (const dataComponent of this.projectDataComponents) {
+			const dataComponentId = dataComponent.getId();
+			const dataComponentName = dataComponent.getName();
+			const dataComponentDescription = dataComponent.getDescription() || "";
+			const dataComponentProps = dataComponent.getProps() || {};
+			if (!dataComponentsObject[dataComponentId] && dataComponentName) dataComponentsObject[dataComponentId] = {
+				id: dataComponentId,
+				name: dataComponentName,
+				description: dataComponentDescription,
+				props: dataComponentProps
+			};
+		}
+		for (const artifactComponent of this.projectArtifactComponents) {
+			const artifactComponentId = artifactComponent.getId();
+			const artifactComponentName = artifactComponent.getName();
+			const artifactComponentDescription = artifactComponent.getDescription() || "";
+			const artifactComponentProps = artifactComponent.getProps() || {};
+			if (!artifactComponentsObject[artifactComponentId] && artifactComponentName) artifactComponentsObject[artifactComponentId] = {
+				id: artifactComponentId,
+				name: artifactComponentName,
+				description: artifactComponentDescription,
+				props: artifactComponentProps
+			};
+		}
+		if (this.credentialReferences && this.credentialReferences.length > 0) {
+			for (const credential of this.credentialReferences) if (credential.id) {
+				if (!credentialReferencesObject[credential.id]) {
+					credentialReferencesObject[credential.id] = credential;
+					credentialUsageMap[credential.id] = [];
+				}
+			}
+		}
+		for (const [credId, usages] of Object.entries(credentialUsageMap)) if (credentialReferencesObject[credId]) credentialReferencesObject[credId].usedBy = usages;
+		return {
+			id: this.projectId,
+			name: this.projectName,
+			description: this.projectDescription || "",
+			models: this.models,
+			stopWhen: this.stopWhen,
+			agents: agentsObject,
+			tools: toolsObject,
+			functionTools: Object.keys(functionToolsObject).length > 0 ? functionToolsObject : void 0,
+			functions: Object.keys(functionsObject).length > 0 ? functionsObject : void 0,
+			dataComponents: Object.keys(dataComponentsObject).length > 0 ? dataComponentsObject : void 0,
+			artifactComponents: Object.keys(artifactComponentsObject).length > 0 ? artifactComponentsObject : void 0,
+			externalAgents: Object.keys(externalAgentsObject).length > 0 ? externalAgentsObject : void 0,
+			credentialReferences: Object.keys(credentialReferencesObject).length > 0 ? credentialReferencesObject : void 0,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+	}
+};
+
+//#endregion
+export { Project };

package/dist/projectFullClient.d.ts

@@ -0,0 +1,23 @@
+import { FullProjectDefinition } from "@inkeep/agents-core";
+
+//#region src/projectFullClient.d.ts
+
+/**
+ * Create a full project via HTTP API
+ */
+declare function createFullProjectViaAPI(tenantId: string, apiUrl: string, projectData: FullProjectDefinition, apiKey?: string): Promise<FullProjectDefinition>;
+/**
+ * Update a full project via HTTP API (upsert behavior)
+ */
+declare function updateFullProjectViaAPI(tenantId: string, apiUrl: string, projectId: string, projectData: FullProjectDefinition, apiKey?: string): Promise<FullProjectDefinition>;
+/**
+ * Get a full project via HTTP API
+ */
+declare function getFullProjectViaAPI(tenantId: string, apiUrl: string, projectId: string, apiKey?: string): Promise<FullProjectDefinition | null>;
+/**
+ * Delete a full project via HTTP API
+ */
+declare function deleteFullProjectViaAPI(tenantId: string, apiUrl: string, projectId: string, apiKey?: string): Promise<void>;
+declare function parseError(errorText: string): string | undefined;
+//#endregion
+export { createFullProjectViaAPI, deleteFullProjectViaAPI, getFullProjectViaAPI, parseError, updateFullProjectViaAPI };