@inkeep/agents-run-api 0.39.4 → 0.40.0

package/dist/agents/relationTools.js

@@ -0,0 +1,262 @@
+import { getLogger } from "../logger.js";
+import dbClient_default from "../data/db/dbClient.js";
+import { DELEGATION_TOOL_BACKOFF_EXPONENT, DELEGATION_TOOL_BACKOFF_INITIAL_INTERVAL_MS, DELEGATION_TOOL_BACKOFF_MAX_ELAPSED_TIME_MS, DELEGATION_TOOL_BACKOFF_MAX_INTERVAL_MS } from "../constants/execution-limits/index.js";
+import { toolSessionManager } from "./ToolSessionManager.js";
+import { saveA2AMessageResponse } from "../data/conversations.js";
+import { agentSessionManager } from "../services/AgentSession.js";
+import { A2AClient } from "../a2a/client.js";
+import { z } from "@hono/zod-openapi";
+import { ContextResolver, CredentialStuffer, SPAN_KEYS, TemplateEngine, createMessage, generateId, generateServiceToken, getCredentialReference, headers } from "@inkeep/agents-core";
+import { trace } from "@opentelemetry/api";
+import { tool } from "ai";
+
+//#region src/agents/relationTools.ts
+const logger = getLogger("relationships Tools");
+const A2A_RETRY_STATUS_CODES = [
+	"429",
+	"500",
+	"502",
+	"503",
+	"504"
+];
+const generateTransferToolDescription = (config) => {
+	let toolsSection = "";
+	let transferSection = "";
+	if (config.transferRelations && config.transferRelations.length > 0) transferSection = `
+
+Can Transfer To:
+${config.transferRelations.map((transfer) => `  - ${transfer.name || transfer.id}: ${transfer.description || "No description available"}`).join("\n")}`;
+	let delegateSection = "";
+	if (config.delegateRelations && config.delegateRelations.length > 0) delegateSection = `
+
+Can Delegate To:
+${config.delegateRelations.map((delegate) => `  - ${delegate.config.name || delegate.config.id}: ${delegate.config.description || "No description available"} (${delegate.type})`).join("\n")}`;
+	if (config.tools && config.tools.length > 0) toolsSection = `
+
+Available Tools & Capabilities:
+${config.tools.map((tool$1) => {
+		const toolsList = tool$1.availableTools?.map((t) => `  - ${t.name}: ${t.description || "No description available"}`).join("\n") || "";
+		return `MCP Server: ${tool$1.name}\n${toolsList}`;
+	}).join("\n\n")}`;
+	return `Hand off the conversation to agent ${config.id}.
+
+Agent Information:
+- ID: ${config.id}
+- Name: ${config.name ?? "No name provided"}
+- Description: ${config.description ?? "No description provided"}${toolsSection}${transferSection}${delegateSection}
+
+Hand off the conversation to agent ${config.id} when the user's request would be better handled by this specialized agent.`;
+};
+const generateDelegateToolDescription = (delegateRelation) => {
+	const config = delegateRelation.config;
+	let toolsSection = "";
+	let transferSection = "";
+	let delegateSection = "";
+	if (delegateRelation.type === "internal" && "tools" in config) {
+		const agentConfig = config;
+		if (agentConfig.tools && agentConfig.tools.length > 0) toolsSection = `
+
+Available Tools & Capabilities:
+${agentConfig.tools.map((tool$1) => {
+			const toolsList = tool$1.availableTools?.map((t) => `  - ${t.name}: ${t.description || "No description available"}`).join("\n") || "";
+			return `MCP Server: ${tool$1.name}\n${toolsList}`;
+		}).join("\n\n")}`;
+		if (agentConfig.transferRelations && agentConfig.transferRelations.length > 0) transferSection = `
+
+Can Transfer To:
+${agentConfig.transferRelations.map((transfer) => `  - ${transfer.name || transfer.id}: ${transfer.description || "No description available"}`).join("\n")}`;
+		if (agentConfig.delegateRelations && agentConfig.delegateRelations.length > 0) delegateSection = `
+
+Can Delegate To:
+${agentConfig.delegateRelations.map((delegate) => `  - ${delegate.config.name || delegate.config.id}: ${delegate.config.description || "No description available"} (${delegate.type})`).join("\n")}`;
+	}
+	return `Delegate a specific task to another agent.
+
+Agent Information:
+- ID: ${config.id}
+- Name: ${config.name}
+- Description: ${config.description || "No description provided"}
+- Type: ${delegateRelation.type}${toolsSection}${transferSection}${delegateSection}
+
+Delegate a specific task to agent ${config.id} when it seems like the agent can do relevant work.`;
+};
+const createTransferToAgentTool = ({ transferConfig, callingAgentId, subAgent, streamRequestId }) => {
+	return tool({
+		description: generateTransferToolDescription(transferConfig),
+		inputSchema: z.object({}),
+		execute: async () => {
+			const activeSpan = trace.getActiveSpan();
+			if (activeSpan) activeSpan.setAttributes({
+				[SPAN_KEYS.TRANSFER_FROM_SUB_AGENT_ID]: callingAgentId,
+				[SPAN_KEYS.TRANSFER_TO_SUB_AGENT_ID]: transferConfig.id ?? "unknown"
+			});
+			logger.info({
+				transferTo: transferConfig.id ?? "unknown",
+				fromSubAgent: callingAgentId
+			}, "invoked transferToAgentTool");
+			if (streamRequestId) agentSessionManager.recordEvent(streamRequestId, "transfer", callingAgentId, {
+				fromSubAgent: callingAgentId,
+				targetSubAgent: transferConfig.id ?? "unknown",
+				reason: `Transfer to ${transferConfig.name || transferConfig.id}`
+			});
+			const transferResult = {
+				type: "transfer",
+				targetSubAgentId: transferConfig.id ?? "unknown",
+				fromSubAgentId: callingAgentId
+			};
+			logger.info({
+				transferResult,
+				transferResultKeys: Object.keys(transferResult)
+			}, "[DEBUG] Transfer tool returning");
+			return transferResult;
+		}
+	});
+};
+function createDelegateToAgentTool({ delegateConfig, callingAgentId, tenantId, projectId, agentId, contextId, metadata, sessionId, subAgent, credentialStoreRegistry }) {
+	return tool({
+		description: generateDelegateToolDescription(delegateConfig),
+		inputSchema: z.object({ message: z.string() }),
+		execute: async (input, context$1) => {
+			const delegationId = `del_${generateId()}`;
+			const activeSpan = trace.getActiveSpan();
+			if (activeSpan) activeSpan.setAttributes({
+				[SPAN_KEYS.DELEGATION_FROM_SUB_AGENT_ID]: callingAgentId,
+				[SPAN_KEYS.DELEGATION_TO_SUB_AGENT_ID]: delegateConfig.config.id ?? "unknown",
+				[SPAN_KEYS.DELEGATION_ID]: delegationId
+			});
+			if (metadata.streamRequestId) agentSessionManager.recordEvent(metadata.streamRequestId, "delegation_sent", callingAgentId, {
+				delegationId,
+				fromSubAgent: callingAgentId,
+				targetSubAgent: delegateConfig.config.id,
+				taskDescription: input.message
+			});
+			const isInternal = delegateConfig.type === "internal";
+			const isExternal = delegateConfig.type === "external";
+			const isTeam = delegateConfig.type === "team";
+			let resolvedHeaders = {};
+			if (isExternal) {
+				if ((delegateConfig.config.credentialReferenceId || delegateConfig.config.headers) && credentialStoreRegistry) {
+					const credentialStuffer = new CredentialStuffer(credentialStoreRegistry, new ContextResolver(tenantId, projectId, dbClient_default, credentialStoreRegistry));
+					const credentialContext = {
+						tenantId,
+						projectId,
+						conversationId: metadata.conversationId,
+						contextConfigId: contextId,
+						metadata
+					};
+					let storeReference;
+					if (delegateConfig.config.credentialReferenceId) {
+						const credentialReference = await getCredentialReference(dbClient_default)({
+							scopes: {
+								tenantId,
+								projectId
+							},
+							id: delegateConfig.config.credentialReferenceId
+						});
+						if (credentialReference) storeReference = {
+							credentialStoreId: credentialReference.credentialStoreId,
+							retrievalParams: credentialReference.retrievalParams || {}
+						};
+					}
+					resolvedHeaders = await credentialStuffer.getCredentialHeaders({
+						context: credentialContext,
+						storeReference,
+						headers: delegateConfig.config.headers || void 0
+					});
+				}
+			} else if (isTeam) {
+				const context$2 = await new ContextResolver(tenantId, projectId, dbClient_default, credentialStoreRegistry).resolveHeaders(metadata.conversationId, contextId);
+				for (const [key, value] of Object.entries(headers)) resolvedHeaders[key] = TemplateEngine.render(value, context$2, { strict: true });
+				resolvedHeaders.Authorization = `Bearer ${await generateServiceToken({
+					tenantId,
+					projectId,
+					originAgentId: agentId,
+					targetAgentId: delegateConfig.config.id
+				})}`;
+			} else resolvedHeaders = {
+				Authorization: `Bearer ${metadata.apiKey}`,
+				"x-inkeep-tenant-id": tenantId,
+				"x-inkeep-project-id": projectId,
+				"x-inkeep-agent-id": agentId,
+				"x-inkeep-sub-agent-id": delegateConfig.config.id
+			};
+			const a2aClient = new A2AClient(delegateConfig.config.baseUrl, {
+				headers: resolvedHeaders,
+				retryConfig: {
+					strategy: "backoff",
+					retryConnectionErrors: true,
+					statusCodes: [...A2A_RETRY_STATUS_CODES],
+					backoff: {
+						initialInterval: DELEGATION_TOOL_BACKOFF_INITIAL_INTERVAL_MS,
+						maxInterval: DELEGATION_TOOL_BACKOFF_MAX_INTERVAL_MS,
+						exponent: DELEGATION_TOOL_BACKOFF_EXPONENT,
+						maxElapsedTime: DELEGATION_TOOL_BACKOFF_MAX_ELAPSED_TIME_MS
+					}
+				}
+			});
+			const messageToSend = {
+				role: "agent",
+				parts: [{
+					text: input.message,
+					kind: "text"
+				}],
+				messageId: generateId(),
+				kind: "message",
+				contextId,
+				metadata: {
+					...metadata,
+					isDelegation: true,
+					delegationId,
+					...isInternal ? { fromSubAgentId: callingAgentId } : { fromExternalAgentId: callingAgentId }
+				}
+			};
+			logger.info({ messageToSend }, "messageToSend");
+			await createMessage(dbClient_default)({
+				id: generateId(),
+				tenantId,
+				projectId,
+				conversationId: contextId,
+				role: "agent",
+				content: { text: input.message },
+				visibility: isInternal ? "internal" : "external",
+				messageType: "a2a-request",
+				fromSubAgentId: callingAgentId,
+				...isInternal ? { toSubAgentId: delegateConfig.config.id } : { toExternalAgentId: delegateConfig.config.id }
+			});
+			const response = await a2aClient.sendMessage({ message: messageToSend });
+			if (response.error) throw new Error(response.error.message);
+			await saveA2AMessageResponse(response, {
+				tenantId,
+				projectId,
+				conversationId: contextId,
+				messageType: "a2a-response",
+				visibility: isInternal ? "internal" : "external",
+				toSubAgentId: callingAgentId,
+				...isInternal ? { fromSubAgentId: delegateConfig.config.id } : { fromExternalAgentId: delegateConfig.config.id }
+			});
+			if (sessionId && context$1?.toolCallId) {
+				const toolResult = {
+					toolCallId: context$1.toolCallId,
+					toolName: `delegate_to_${delegateConfig.config.id}`,
+					args: input,
+					result: response.result,
+					timestamp: Date.now()
+				};
+				toolSessionManager.recordToolResult(sessionId, toolResult);
+			}
+			if (metadata.streamRequestId) agentSessionManager.recordEvent(metadata.streamRequestId, "delegation_returned", callingAgentId, {
+				delegationId,
+				fromSubAgent: delegateConfig.config.id,
+				targetSubAgent: callingAgentId,
+				result: response.result
+			});
+			return {
+				toolCallId: context$1?.toolCallId,
+				result: response.result
+			};
+		}
+	});
+}
+
+//#endregion
+export { createDelegateToAgentTool, createTransferToAgentTool };

package/dist/agents/types.d.ts

@@ -0,0 +1,28 @@
+import { AssembleResult } from "../utils/token-estimator.js";
+import { Artifact, ArtifactComponentApiInsert, DataComponentApiInsert } from "@inkeep/agents-core";
+
+//#region src/agents/types.d.ts
+interface VersionConfig<TConfig> {
+  loadTemplates(): Map<string, string>;
+  assemble(templates: Map<string, string>, config: TConfig): AssembleResult;
+}
+interface SystemPromptV1 {
+  corePrompt: string;
+  prompt?: string;
+  artifacts: Artifact[];
+  tools: ToolData[];
+  dataComponents: DataComponentApiInsert[];
+  artifactComponents?: ArtifactComponentApiInsert[];
+  hasAgentArtifactComponents?: boolean;
+  isThinkingPreparation?: boolean;
+  hasTransferRelations?: boolean;
+  hasDelegateRelations?: boolean;
+}
+interface ToolData {
+  name: string;
+  description?: string | null;
+  inputSchema?: Record<string, unknown>;
+  usageGuidelines?: string;
+}
+//#endregion
+export { SystemPromptV1, ToolData, VersionConfig };

package/dist/agents/types.js

@@ -0,0 +1 @@
+export {  };

package/dist/agents/versions/v1/Phase1Config.d.ts

@@ -0,0 +1,27 @@
+import { AssembleResult } from "../../../utils/token-estimator.js";
+import { SystemPromptV1, ToolData, VersionConfig } from "../../types.js";
+import { McpTool } from "@inkeep/agents-core";
+
+//#region src/agents/versions/v1/Phase1Config.d.ts
+declare class Phase1Config implements VersionConfig<SystemPromptV1> {
+  loadTemplates(): Map<string, string>;
+  static convertMcpToolsToToolData(mcpTools: McpTool[] | undefined): ToolData[];
+  private isToolDataArray;
+  private normalizeSchema;
+  assemble(templates: Map<string, string>, config: SystemPromptV1): AssembleResult;
+  private generateAgentContextSection;
+  private generateThinkingPreparationSection;
+  private generateTransferInstructions;
+  private generateDelegationInstructions;
+  private getArtifactInstructionsTokens;
+  private getArtifactCreationGuidance;
+  private getArtifactReferencingRules;
+  private getArtifactCreationInstructions;
+  private generateArtifactsSection;
+  private generateArtifactXml;
+  private generateToolsSection;
+  private generateToolXml;
+  private generateParametersXml;
+}
+//#endregion
+export { Phase1Config };