@inkeep/agents-run-api 0.39.5 → 0.41.0

package/dist/a2a/types.d.ts

@@ -0,0 +1,79 @@
+import { AgentCard, Artifact, Message, Task, TaskState } from "@inkeep/agents-core";
+
+//#region src/a2a/types.d.ts
+interface RegisteredAgent {
+  subAgentId: string;
+  tenantId: string;
+  projectId: string;
+  agentId: string;
+  agentCard: AgentCard;
+  taskHandler: (task: A2ATask) => Promise<A2ATaskResult>;
+}
+interface A2ATask {
+  id: string;
+  input: {
+    parts: Array<{
+      kind: string;
+      text?: string;
+      data?: any;
+    }>;
+  };
+  context?: {
+    conversationId?: string;
+    userId?: string;
+    metadata?: Record<string, any>;
+  };
+}
+type A2ATaskErrorType = 'connection_refused' | 'unknown';
+interface A2ATaskResult {
+  status: {
+    state: TaskState;
+    message?: string;
+    type?: A2ATaskErrorType;
+  };
+  artifacts?: Artifact[];
+}
+/**
+ * Transfer data structure - what the transfer tool returns
+ * This gets wrapped into a DataPart by the AI SDK
+ */
+interface TransferData {
+  type: 'transfer';
+  targetSubAgentId: string;
+  fromSubAgentId?: string;
+}
+/**
+ * Full transfer response following A2A protocol
+ * The TransferData is wrapped in artifacts[0].parts[0].data
+ */
+interface TransferTask extends Task {
+  artifacts: Artifact[];
+}
+/**
+ * Type guard to check if a Task contains transfer data
+ */
+declare function isTransferTask(result: Task | Message): result is TransferTask;
+/**
+ * Helper to safely extract transfer data from a TransferTask
+ * Returns null if no transfer data found
+ */
+declare function extractTransferData(task: TransferTask): TransferData | null;
+interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  method: string;
+  params?: any;
+  id?: string | number | null;
+}
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  result?: any;
+  error?: {
+    code: number;
+    message: string;
+    data?: any;
+  };
+  id?: string | number | null;
+}
+type A2AMethod = 'agent.invoke' | 'agent.getCapabilities' | 'agent.getStatus';
+//#endregion
+export { A2AMethod, A2ATask, A2ATaskErrorType, A2ATaskResult, type AgentCard, JsonRpcRequest, JsonRpcResponse, RegisteredAgent, TransferData, TransferTask, extractTransferData, isTransferTask };

package/dist/a2a/types.js

@@ -0,0 +1,22 @@
+//#region src/a2a/types.ts
+/**
+* Type guard to check if a Task contains transfer data
+*/
+function isTransferTask(result) {
+	if (!("artifacts" in result) || !result.artifacts) return false;
+	return result.artifacts.some((artifact) => artifact.parts.some((part) => {
+		if (part.kind !== "data" || !part.data) return false;
+		return typeof part.data === "object" && "type" in part.data && part.data.type === "transfer";
+	}));
+}
+/**
+* Helper to safely extract transfer data from a TransferTask
+* Returns null if no transfer data found
+*/
+function extractTransferData(task) {
+	for (const artifact of task.artifacts) for (const part of artifact.parts) if (part.kind === "data" && part.data?.type === "transfer") return part.data;
+	return null;
+}
+
+//#endregion
+export { extractTransferData, isTransferTask };

package/dist/agents/Agent.d.ts

@@ -0,0 +1,268 @@
+import { SandboxConfig } from "../types/execution-context.js";
+import { StreamHelper } from "../utils/stream-helpers.js";
+import { AgentConversationHistoryConfig, Artifact, ArtifactComponentApiInsert, CredentialStoreRegistry, DataComponentApiInsert, McpTool, Models, SubAgentStopWhen } from "@inkeep/agents-core";
+import { ToolSet } from "ai";
+
+//#region src/agents/Agent.d.ts
+
+/**
+ * Creates a stopWhen condition that stops when any tool call name starts with the given prefix
+ * @param prefix - The prefix to check for in tool call names
+ * @returns A function that can be used as a stopWhen condition
+ */
+declare function hasToolCallWithPrefix(prefix: string): ({
+  steps
+}: {
+  steps: Array<any>;
+}) => any;
+type AgentConfig = {
+  id: string;
+  tenantId: string;
+  projectId: string;
+  agentId: string;
+  relationId?: string;
+  baseUrl: string;
+  apiKey?: string;
+  apiKeyId?: string;
+  name: string;
+  description?: string;
+  prompt?: string;
+  subAgentRelations: AgentConfig[];
+  transferRelations: AgentConfig[];
+  delegateRelations: DelegateRelation[];
+  tools?: McpTool[];
+  artifacts?: Record<string, Artifact>;
+  functionTools?: Array<{
+    name: string;
+    description: string;
+    execute: (params: any) => Promise<any>;
+    parameters?: Record<string, any>;
+    schema?: any;
+  }>;
+  contextConfigId?: string;
+  dataComponents?: DataComponentApiInsert[];
+  artifactComponents?: ArtifactComponentApiInsert[];
+  conversationHistoryConfig?: AgentConversationHistoryConfig;
+  models?: Models;
+  stopWhen?: SubAgentStopWhen;
+  sandboxConfig?: SandboxConfig;
+  /** User ID for user-scoped credential lookup (from temp JWT) */
+  userId?: string;
+  /** Headers to forward to MCP servers (e.g., x-forwarded-cookie for user session auth) */
+  forwardedHeaders?: Record<string, string>;
+};
+type ExternalAgentRelationConfig = {
+  relationId: string;
+  id: string;
+  name: string;
+  description: string;
+  baseUrl: string;
+  credentialReferenceId?: string | null;
+  headers?: Record<string, string> | null;
+  relationType: string;
+};
+type TeamAgentRelationConfig = {
+  relationId: string;
+  id: string;
+  name: string;
+  description: string;
+  baseUrl: string;
+  headers?: Record<string, string> | null;
+};
+type DelegateRelation = {
+  type: 'internal';
+  config: AgentConfig;
+} | {
+  type: 'external';
+  config: ExternalAgentRelationConfig;
+} | {
+  type: 'team';
+  config: TeamAgentRelationConfig;
+};
+type ToolType = 'transfer' | 'delegation' | 'mcp' | 'tool';
+declare class Agent {
+  #private;
+  private config;
+  private systemPromptBuilder;
+  private credentialStuffer?;
+  private streamHelper?;
+  private streamRequestId?;
+  private conversationId?;
+  private delegationId?;
+  private artifactComponents;
+  private isDelegatedAgent;
+  private contextResolver?;
+  private credentialStoreRegistry?;
+  private mcpClientCache;
+  private mcpConnectionLocks;
+  private currentCompressor;
+  constructor(config: AgentConfig, credentialStoreRegistry?: CredentialStoreRegistry);
+  /**
+   * Get the maximum number of generation steps for this agent
+   * Uses agent's stopWhen.stepCountIs config or defaults to AGENT_EXECUTION_MAX_GENERATION_STEPS
+   */
+  private getMaxGenerationSteps;
+  /**
+   * Sanitizes tool names at runtime for AI SDK compatibility.
+   * The AI SDK requires tool names to match pattern ^[a-zA-Z0-9_-]{1,128}$
+   */
+  private sanitizeToolsForAISDK;
+  /**
+   * Get the primary model settings for text generation and thinking
+   * Requires model to be configured at project level
+   */
+  private getPrimaryModel;
+  /**
+   * Get the model settings for structured output generation
+   * Falls back to base model if structured output not configured
+   */
+  private getStructuredOutputModel;
+  /**
+   * Get the model settings for summarization/distillation
+   * Falls back to base model if summarizer not configured
+   */
+  private getSummarizerModel;
+  setConversationId(conversationId: string): void;
+  /**
+   * Simple compression fallback: drop oldest messages to fit under token limit
+   */
+  /**
+   * Set delegation status for this agent instance
+   */
+  setDelegationStatus(isDelegated: boolean): void;
+  /**
+   * Set delegation ID for this agent instance
+   */
+  setDelegationId(delegationId: string | undefined): void;
+  /**
+   * Get streaming helper if this agent should stream to user
+   * Returns undefined for delegated agents to prevent streaming data operations to user
+   */
+  getStreamingHelper(): StreamHelper | undefined;
+  /**
+   * Wraps a tool with streaming lifecycle tracking (start, complete, error) and AgentSession recording
+   */
+  private wrapToolWithStreaming;
+  getRelationTools(runtimeContext?: {
+    contextId: string;
+    metadata: {
+      conversationId: string;
+      threadId: string;
+      streamRequestId?: string;
+      streamBaseUrl?: string;
+      apiKey?: string;
+      baseUrl?: string;
+    };
+  }, sessionId?: string): any;
+  getMcpTools(sessionId?: string, streamRequestId?: string): Promise<ToolSet>;
+  /**
+   * Convert database McpTool to builder MCPToolConfig format
+   */
+  private convertToMCPToolConfig;
+  getMcpTool(tool: McpTool): Promise<{
+    tools: Record<string, any>;
+    toolPolicies: Record<string, {
+      needsApproval?: boolean;
+    }>;
+    mcpServerId: string;
+    mcpServerName: string;
+  }>;
+  private createMcpConnection;
+  getFunctionTools(sessionId?: string, streamRequestId?: string): Promise<ToolSet>;
+  /**
+   * Get resolved context using ContextResolver - will return cached data or fetch fresh data as needed
+   */
+  getResolvedContext(conversationId: string, headers?: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+  /**
+   * Get the agent prompt for this agent's agent
+   */
+  private getPrompt;
+  /**
+   * Check if any agent in the agent has artifact components configured
+   */
+  private hasAgentArtifactComponents;
+  /**
+   * Build adaptive system prompt for Phase 2 structured output generation
+   * based on configured data components and artifact components across the agent
+   */
+  private buildPhase2SystemPrompt;
+  private buildSystemPrompt;
+  private getArtifactTools;
+  private createThinkingCompleteTool;
+  private getDefaultTools;
+  private getStreamRequestId;
+  /**
+   * Format tool result for storage in conversation history
+   */
+  private formatToolResult;
+  /**
+   * Get the conversation ID for storing tool results
+   * Always uses the real conversation ID - delegation filtering happens at query time
+   */
+  private getToolResultConversationId;
+  /**
+   * Analyze tool result structure and add helpful path hints for artifact creation
+   * Only adds hints when artifact components are available
+   */
+  private enhanceToolResultWithStructureHints;
+  private agentHasArtifactComponents;
+  generate(userMessage: string, runtimeContext?: {
+    contextId: string;
+    metadata: {
+      conversationId: string;
+      threadId: string;
+      taskId: string;
+      streamRequestId: string;
+      apiKey?: string;
+    };
+  }): Promise<any>;
+  /**
+   * Setup generation context and initialize streaming helper
+   */
+  private setupGenerationContext;
+  /**
+   * Load all tools and system prompts in parallel, then combine and sanitize them
+   */
+  private loadToolsAndPrompts;
+  /**
+   * Build conversation history based on configuration mode and filters
+   */
+  private buildConversationHistory;
+  /**
+   * Configure model settings, timeouts, and streaming behavior
+   */
+  private configureModelSettings;
+  /**
+   * Build initial messages array with system prompt and user content
+   */
+  private buildInitialMessages;
+  /**
+   * Setup compression for the current generation
+   */
+  private setupCompression;
+  /**
+   * Prepare step function for streaming with compression logic
+   */
+  private handlePrepareStepCompression;
+  private handleStopWhenConditions;
+  private setupStreamParser;
+  private buildTelemetryConfig;
+  private buildBaseGenerationConfig;
+  private buildReasoningFlow;
+  private buildDataComponentsSchema;
+  private calculatePhase2Timeout;
+  private buildPhase2Messages;
+  private executeStreamingPhase2;
+  private executeNonStreamingPhase2;
+  private formatFinalResponse;
+  private handleGenerationError;
+  /**
+   * Public cleanup method for external lifecycle management (e.g., session cleanup)
+   * Performs full cleanup of compression state when agent/session is ending
+   */
+  cleanupCompression(): void;
+  private processStreamEvents;
+  private formatStreamingResponse;
+}
+//#endregion
+export { Agent, AgentConfig, DelegateRelation, ExternalAgentRelationConfig, TeamAgentRelationConfig, ToolType, hasToolCallWithPrefix };