@inkeep/agents-run-api 0.39.5 → 0.41.0

package/dist/create-app.js

@@ -0,0 +1,195 @@
+import { getLogger } from "./logger.js";
+import { flushBatchProcessor } from "./instrumentation.js";
+import { apiKeyAuth } from "./middleware/api-key-auth.js";
+import { setupOpenAPIRoutes } from "./openapi.js";
+import agents_default from "./routes/agents.js";
+import chat_default from "./routes/chat.js";
+import chatDataStream_default from "./routes/chatDataStream.js";
+import mcp_default from "./routes/mcp.js";
+import { otel } from "@hono/otel";
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { handleApiError } from "@inkeep/agents-core";
+import { context, propagation } from "@opentelemetry/api";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { HTTPException } from "hono/http-exception";
+import { requestId } from "hono/request-id";
+
+//#region src/create-app.ts
+const logger = getLogger("agents-run-api");
+function createExecutionHono(serverConfig, credentialStores, sandboxConfig) {
+	const app = new OpenAPIHono();
+	app.use("*", otel());
+	app.use("*", requestId());
+	app.use("*", async (c, next) => {
+		c.set("serverConfig", serverConfig);
+		c.set("credentialStores", credentialStores);
+		if (sandboxConfig) c.set("sandboxConfig", sandboxConfig);
+		return next();
+	});
+	app.use("*", async (c, next) => {
+		if (c.req.header("content-type")?.includes("application/json")) try {
+			const body = await c.req.json();
+			c.set("requestBody", body);
+		} catch (error) {
+			logger.debug({ error }, "Failed to parse JSON body, continuing without parsed body");
+		}
+		return next();
+	});
+	app.use("*", async (c, next) => {
+		const reqId = c.get("requestId");
+		let bag = propagation.getBaggage(context.active());
+		if (!bag) bag = propagation.createBaggage();
+		if (bag && typeof bag.setEntry === "function") {
+			bag = bag.setEntry("request.id", { value: String(reqId ?? "unknown") });
+			const ctxWithBag = propagation.setBaggage(context.active(), bag);
+			return await context.with(ctxWithBag, async () => await next());
+		}
+		return next();
+	});
+	app.onError(async (err, c) => {
+		const isExpectedError = err instanceof HTTPException;
+		const status = isExpectedError ? err.status : 500;
+		const requestId$1 = c.get("requestId") || "unknown";
+		let zodIssues;
+		if (err && typeof err === "object") {
+			if (err.cause && Array.isArray(err.cause.issues)) zodIssues = err.cause.issues;
+			else if (Array.isArray(err.issues)) zodIssues = err.issues;
+		}
+		if (status === 400 && Array.isArray(zodIssues)) {
+			c.status(400);
+			c.header("Content-Type", "application/problem+json");
+			c.header("X-Content-Type-Options", "nosniff");
+			return c.json({
+				type: "https://docs.inkeep.com/agents-api/errors#bad_request",
+				title: "Validation Failed",
+				status: 400,
+				detail: "Request validation failed",
+				errors: zodIssues.map((issue) => ({
+					detail: issue.message,
+					pointer: issue.path ? `/${issue.path.join("/")}` : void 0,
+					name: issue.path ? issue.path.join(".") : void 0,
+					reason: issue.message
+				}))
+			});
+		}
+		if (status >= 500) {
+			if (!isExpectedError) {
+				const errorMessage = err instanceof Error ? err.message : String(err);
+				const errorStack = err instanceof Error ? err.stack : void 0;
+				if (logger) logger.error({
+					error: err,
+					message: errorMessage,
+					stack: errorStack,
+					path: c.req.path,
+					requestId: requestId$1
+				}, "Unexpected server error occurred");
+			} else if (logger) logger.error({
+				error: err,
+				path: c.req.path,
+				requestId: requestId$1,
+				status
+			}, "Server error occurred");
+		}
+		if (isExpectedError) try {
+			return err.getResponse();
+		} catch (responseError) {
+			if (logger) logger.error({ error: responseError }, "Error while handling HTTPException response");
+		}
+		const { status: respStatus, title, detail, instance } = await handleApiError(err, requestId$1);
+		c.status(respStatus);
+		c.header("Content-Type", "application/problem+json");
+		c.header("X-Content-Type-Options", "nosniff");
+		return c.json({
+			type: "https://docs.inkeep.com/agents-api/errors#internal_server_error",
+			title,
+			status: respStatus,
+			detail,
+			...instance && { instance }
+		});
+	});
+	app.use("*", cors({
+		origin: "*",
+		allowMethods: [
+			"GET",
+			"POST",
+			"PUT",
+			"DELETE",
+			"OPTIONS"
+		],
+		allowHeaders: ["*"],
+		exposeHeaders: ["Content-Length"],
+		maxAge: 86400
+	}));
+	app.use("/tenants/*", apiKeyAuth());
+	app.use("/agents/*", apiKeyAuth());
+	app.use("/v1/*", apiKeyAuth());
+	app.use("/api/*", apiKeyAuth());
+	app.use("*", async (c, next) => {
+		const executionContext = c.get("executionContext");
+		if (!executionContext) {
+			logger.debug({}, "Empty execution context");
+			return next();
+		}
+		const { tenantId, projectId, agentId } = executionContext;
+		let conversationId;
+		const requestBody = c.get("requestBody") || {};
+		if (requestBody) {
+			conversationId = requestBody.conversationId;
+			if (!conversationId) logger.debug({ requestBody }, "No conversation ID found in request body");
+		}
+		const entries = Object.fromEntries(Object.entries({
+			"agent.id": agentId,
+			"tenant.id": tenantId,
+			"project.id": projectId,
+			"conversation.id": conversationId
+		}).filter((entry) => {
+			const [, v] = entry;
+			return typeof v === "string" && v.length > 0;
+		}));
+		if (!Object.keys(entries).length) {
+			logger.debug({}, "Empty entries for baggage");
+			return next();
+		}
+		const bag = Object.entries(entries).reduce((b, [key, value]) => b.setEntry(key, { value: value || "" }), propagation.getBaggage(context.active()) ?? propagation.createBaggage());
+		const ctxWithBag = propagation.setBaggage(context.active(), bag);
+		return await context.with(ctxWithBag, async () => await next());
+	});
+	app.openapi(createRoute({
+		method: "get",
+		path: "/health",
+		tags: ["health"],
+		summary: "Health check",
+		description: "Check if the execution service is healthy",
+		responses: { 204: { description: "Service is healthy" } }
+	}), (c) => {
+		return c.body(null, 204);
+	});
+	app.route("/v1/chat", chat_default);
+	app.route("/api", chatDataStream_default);
+	app.route("/v1/mcp", mcp_default);
+	app.route("/agents", agents_default);
+	setupOpenAPIRoutes(app);
+	app.use("/tenants/*", async (_c, next) => {
+		await next();
+		await flushBatchProcessor();
+	});
+	app.use("/agents/*", async (_c, next) => {
+		await next();
+		await flushBatchProcessor();
+	});
+	app.use("/v1/*", async (_c, next) => {
+		await next();
+		await flushBatchProcessor();
+	});
+	app.use("/api/*", async (_c, next) => {
+		await next();
+		await flushBatchProcessor();
+	});
+	const baseApp = new Hono();
+	baseApp.route("/", app);
+	return baseApp;
+}
+
+//#endregion
+export { createExecutionHono };

package/dist/data/agent.d.ts

@@ -0,0 +1,7 @@
+import { RegisteredAgent } from "../a2a/types.js";
+import { ExecutionContext } from "@inkeep/agents-core";
+
+//#region src/data/agent.d.ts
+declare function getRegisteredAgent(executionContext: ExecutionContext): Promise<RegisteredAgent | null>;
+//#endregion
+export { getRegisteredAgent };

package/dist/data/agent.js

@@ -0,0 +1,72 @@
+import dbClient_default from "./db/dbClient.js";
+import { createTaskHandler, createTaskHandlerConfig } from "../agents/generateTaskHandler.js";
+import { getAgentById, getSubAgentById } from "@inkeep/agents-core";
+
+//#region src/data/agent.ts
+async function hydrateAgent({ dbAgent, baseUrl, apiKey }) {
+	try {
+		if (!dbAgent.defaultSubAgentId) throw new Error(`Agent ${dbAgent.id} does not have a default agent configured`);
+		if (!await getSubAgentById(dbClient_default)({
+			scopes: {
+				tenantId: dbAgent.tenantId,
+				projectId: dbAgent.projectId,
+				agentId: dbAgent.id
+			},
+			subAgentId: dbAgent.defaultSubAgentId
+		})) throw new Error(`Default agent ${dbAgent.defaultSubAgentId} not found for agent ${dbAgent.id}`);
+		const taskHandler = createTaskHandler(await createTaskHandlerConfig({
+			tenantId: dbAgent.tenantId,
+			projectId: dbAgent.projectId,
+			agentId: dbAgent.id,
+			subAgentId: dbAgent.defaultSubAgentId,
+			baseUrl,
+			apiKey
+		}));
+		const agentCard = {
+			name: dbAgent.name,
+			description: dbAgent.description || `Agent: ${dbAgent.name}`,
+			url: baseUrl ? `${baseUrl}/a2a` : "",
+			version: "1.0.0",
+			capabilities: {
+				streaming: true,
+				pushNotifications: false,
+				stateTransitionHistory: false
+			},
+			defaultInputModes: ["text", "text/plain"],
+			defaultOutputModes: ["text", "text/plain"],
+			skills: [],
+			...baseUrl && { provider: {
+				organization: "Inkeep",
+				url: baseUrl
+			} }
+		};
+		return {
+			subAgentId: dbAgent.id,
+			tenantId: dbAgent.tenantId,
+			projectId: dbAgent.projectId,
+			agentId: dbAgent.id,
+			agentCard,
+			taskHandler
+		};
+	} catch (error) {
+		console.error(`❌ Failed to hydrate agent ${dbAgent.id}:`, error);
+		throw error;
+	}
+}
+async function getRegisteredAgent(executionContext) {
+	const { tenantId, projectId, agentId, baseUrl, apiKey } = executionContext;
+	const dbAgent = await getAgentById(dbClient_default)({ scopes: {
+		tenantId,
+		projectId,
+		agentId
+	} });
+	if (!dbAgent) return null;
+	return hydrateAgent({
+		dbAgent,
+		baseUrl: `${baseUrl}/agents`,
+		apiKey
+	});
+}
+
+//#endregion
+export { getRegisteredAgent };

package/dist/data/agents.d.ts

@@ -0,0 +1,34 @@
+import { AgentCard as AgentCard$1, RegisteredAgent } from "../a2a/types.js";
+import { SandboxConfig } from "../types/execution-context.js";
+import { CredentialStoreRegistry, ExecutionContext, SubAgentSelect } from "@inkeep/agents-core";
+
+//#region src/data/agents.d.ts
+
+/**
+ * Create an AgentCard from database agent data
+ * Reusable function that standardizes agent card creation across the codebase
+ * Used for external discovery via /.well-known/agent.json endpoint
+ */
+declare function createAgentCard({
+  dbAgent,
+  baseUrl
+}: {
+  dbAgent: SubAgentSelect;
+  baseUrl: string;
+}): AgentCard$1;
+/**
+ * Generate an enhanced description that includes transfer and delegation information
+ * Used in generateTaskHandler to help agents understand what other agents can do
+ *
+ * @param baseDescription - The base description of the agent
+ * @param internalRelations - Pre-computed internal relations
+ * @param externalRelations - Pre-computed external relations
+ */
+declare function generateDescriptionWithRelationData(baseDescription: string, internalRelations: any[], externalRelations: any[], teamRelations: any[]): string;
+declare function getRegisteredAgent(params: {
+  executionContext: ExecutionContext;
+  credentialStoreRegistry?: CredentialStoreRegistry;
+  sandboxConfig?: SandboxConfig;
+}): Promise<RegisteredAgent | null>;
+//#endregion
+export { createAgentCard, generateDescriptionWithRelationData, getRegisteredAgent };

package/dist/data/agents.js

@@ -0,0 +1,139 @@
+import { getLogger } from "../logger.js";
+import dbClient_default from "./db/dbClient.js";
+import { getUserIdFromContext } from "../types/execution-context.js";
+import { createTaskHandler, createTaskHandlerConfig } from "../agents/generateTaskHandler.js";
+import { getAgentWithDefaultSubAgent, getSubAgentById } from "@inkeep/agents-core";
+
+//#region src/data/agents.ts
+const logger = getLogger("agents");
+/**
+* Create an AgentCard from database agent data
+* Reusable function that standardizes agent card creation across the codebase
+* Used for external discovery via /.well-known/agent.json endpoint
+*/
+function createAgentCard({ dbAgent, baseUrl }) {
+	const description = dbAgent.description || "AI Agent";
+	return {
+		name: dbAgent.name,
+		description,
+		url: baseUrl ? `${baseUrl}/a2a` : "",
+		version: "1.0.0",
+		capabilities: {
+			streaming: true,
+			pushNotifications: false,
+			stateTransitionHistory: false
+		},
+		defaultInputModes: ["text", "text/plain"],
+		defaultOutputModes: ["text", "text/plain"],
+		skills: [],
+		...baseUrl && { provider: {
+			organization: "Inkeep",
+			url: baseUrl
+		} }
+	};
+}
+/**
+* Generate an enhanced description that includes transfer and delegation information
+* Used in generateTaskHandler to help agents understand what other agents can do
+*
+* @param baseDescription - The base description of the agent
+* @param internalRelations - Pre-computed internal relations
+* @param externalRelations - Pre-computed external relations
+*/
+function generateDescriptionWithRelationData(baseDescription, internalRelations, externalRelations, teamRelations) {
+	const transfers = [...internalRelations.filter((rel) => rel.relationType === "transfer")];
+	const delegates = [
+		...internalRelations.filter((rel) => rel.relationType === "delegate"),
+		...externalRelations.map((data) => data.externalAgent),
+		...teamRelations.map((data) => data.targetAgent)
+	];
+	if (transfers.length === 0 && delegates.length === 0) return baseDescription;
+	let enhancedDescription = baseDescription;
+	if (transfers.length > 0) {
+		const transferList = transfers.map((rel) => {
+			return `- ${rel.externalAgent?.name || rel.name}: ${rel.externalAgent?.description || rel.description || ""}`;
+		}).join("\n");
+		enhancedDescription += `\n\nCan transfer to:\n${transferList}`;
+	}
+	if (delegates.length > 0) {
+		const delegateList = delegates.map((rel) => {
+			return `- ${rel.name}: ${rel.description || ""}`;
+		}).join("\n");
+		enhancedDescription += `\n\nCan delegate to:\n${delegateList}`;
+	}
+	return enhancedDescription;
+}
+/**
+* Create a RegisteredAgent from database agent data
+* Hydrates agent directly from database schema using types from schema.ts
+*/
+async function hydrateAgent({ dbAgent, agentId, baseUrl, apiKey, credentialStoreRegistry, sandboxConfig, userId }) {
+	try {
+		const taskHandler = createTaskHandler(await createTaskHandlerConfig({
+			tenantId: dbAgent.tenantId,
+			projectId: dbAgent.projectId,
+			agentId,
+			subAgentId: dbAgent.id,
+			baseUrl,
+			apiKey,
+			sandboxConfig,
+			userId
+		}), credentialStoreRegistry);
+		const agentCard = createAgentCard({
+			dbAgent,
+			baseUrl
+		});
+		return {
+			subAgentId: dbAgent.id,
+			tenantId: dbAgent.tenantId,
+			projectId: dbAgent.projectId,
+			agentId,
+			agentCard,
+			taskHandler
+		};
+	} catch (error) {
+		console.error(`❌ Failed to hydrate agent ${dbAgent.id}:`, error);
+		throw error;
+	}
+}
+async function getRegisteredAgent(params) {
+	const { executionContext, credentialStoreRegistry, sandboxConfig } = params;
+	const { tenantId, projectId, agentId, subAgentId, baseUrl, apiKey } = executionContext;
+	const userId = getUserIdFromContext(executionContext);
+	let dbAgent;
+	if (!subAgentId) {
+		const agent = await getAgentWithDefaultSubAgent(dbClient_default)({ scopes: {
+			tenantId,
+			projectId,
+			agentId
+		} });
+		logger.info({ agent }, "agent with default sub agent");
+		if (!agent || !agent.defaultSubAgent) return null;
+		dbAgent = agent.defaultSubAgent;
+	} else {
+		const response = await getSubAgentById(dbClient_default)({
+			scopes: {
+				tenantId,
+				projectId,
+				agentId
+			},
+			subAgentId
+		});
+		if (!response) return null;
+		dbAgent = response;
+	}
+	if (!dbAgent) return null;
+	const agentFrameworkBaseUrl = `${baseUrl}/agents`;
+	return hydrateAgent({
+		dbAgent,
+		agentId,
+		baseUrl: agentFrameworkBaseUrl,
+		credentialStoreRegistry,
+		apiKey,
+		sandboxConfig,
+		userId
+	});
+}
+
+//#endregion
+export { createAgentCard, generateDescriptionWithRelationData, getRegisteredAgent };

package/dist/data/conversations.d.ts

@@ -0,0 +1,128 @@
+import { AgentConversationHistoryConfig, Artifact, ConversationHistoryConfig, ConversationScopeOptions } from "@inkeep/agents-core";
+
+//#region src/data/conversations.d.ts
+declare const compressionLocks: Map<string, Promise<any>>;
+/**
+ * Creates default conversation history configuration
+ * @param mode - The conversation history mode ('full' | 'scoped' | 'none')
+ * @returns Default AgentConversationHistoryConfig
+ */
+declare function createDefaultConversationHistoryConfig(mode?: 'full' | 'scoped' | 'none'): AgentConversationHistoryConfig;
+/**
+ * Saves the result of an A2A client sendMessage call as a conversation message
+ * @param response - The response from a2aClient.sendMessage()
+ * @param params - Parameters for saving the message
+ * @returns The saved message or null if no text content was found
+ */
+declare function saveA2AMessageResponse(response: any,
+// SendMessageResponse type
+params: {
+  tenantId: string;
+  projectId: string;
+  conversationId: string;
+  messageType: 'a2a-response' | 'a2a-request';
+  visibility: 'internal' | 'external' | 'user-facing';
+  fromSubAgentId?: string;
+  toSubAgentId?: string;
+  fromExternalAgentId?: string;
+  toExternalAgentId?: string;
+  a2aTaskId?: string;
+  a2aSessionId?: string;
+  metadata?: Record<string, unknown>;
+}): Promise<any | null>;
+/**
+ * Applies filtering based on agent, task, or both criteria
+ * Returns the filtered messages array
+ */
+declare function getScopedHistory({
+  tenantId,
+  projectId,
+  conversationId,
+  filters,
+  options
+}: {
+  tenantId: string;
+  projectId: string;
+  conversationId: string;
+  filters?: ConversationScopeOptions;
+  options?: ConversationHistoryConfig;
+}): Promise<any[]>;
+/**
+ * Get user-facing conversation history (for client display)
+ */
+declare function getUserFacingHistory(tenantId: string, projectId: string, conversationId: string, limit?: 50): Promise<any[]>;
+/**
+ * Get full conversation context (for agent processing)
+ */
+declare function getFullConversationContext(tenantId: string, projectId: string, conversationId: string, maxTokens?: number): Promise<any[]>;
+/**
+ * Get formatted conversation history for a2a
+ */
+declare function getFormattedConversationHistory({
+  tenantId,
+  projectId,
+  conversationId,
+  currentMessage,
+  options,
+  filters,
+  sessionId,
+  summarizerModel
+}: {
+  tenantId: string;
+  projectId: string;
+  conversationId: string;
+  currentMessage?: string;
+  options?: ConversationHistoryConfig;
+  filters?: ConversationScopeOptions;
+  sessionId?: string;
+  summarizerModel?: any;
+}): Promise<string>;
+/**
+ * Modern conversation history retrieval with compression support
+ * Replaces getFormattedConversationHistory with built-in compression when needed
+ */
+declare function getConversationHistoryWithCompression({
+  tenantId,
+  projectId,
+  conversationId,
+  currentMessage,
+  options,
+  filters,
+  summarizerModel,
+  streamRequestId,
+  fullContextSize
+}: {
+  tenantId: string;
+  projectId: string;
+  conversationId: string;
+  currentMessage?: string;
+  options?: ConversationHistoryConfig;
+  filters?: ConversationScopeOptions;
+  summarizerModel?: any;
+  streamRequestId?: string;
+  fullContextSize?: number;
+}): Promise<string>;
+/**
+ * Apply conversation compression using the BaseCompressor infrastructure
+ */
+declare function compressConversationIfNeeded(messages: any[], params: {
+  conversationId: string;
+  tenantId: string;
+  projectId: string;
+  summarizerModel: any;
+  streamRequestId?: string;
+  fullContextSize?: number;
+}): Promise<any[]>;
+/**
+ * Get artifacts that are within the scope of the conversation history
+ * Only returns artifacts from messages that are actually visible to the LLM
+ * Uses the same scoping logic as getFormattedConversationHistory
+ */
+declare function getConversationScopedArtifacts(params: {
+  tenantId: string;
+  projectId: string;
+  conversationId: string;
+  historyConfig: AgentConversationHistoryConfig;
+}): Promise<Artifact[]>;
+//#endregion
+export { compressConversationIfNeeded, compressionLocks, createDefaultConversationHistoryConfig, getConversationHistoryWithCompression, getConversationScopedArtifacts, getFormattedConversationHistory, getFullConversationContext, getScopedHistory, getUserFacingHistory, saveA2AMessageResponse };