@inkeep/agents-sdk 0.1.1 → 0.1.7

package/dist/index.d.cts

@@ -0,0 +1,1131 @@
+import { MCPToolConfig as MCPToolConfig$1, CredentialReferenceApiInsert, MCPTransportType, CredentialReferenceSelect, AgentApiInsert, AgentStopWhen, DataComponentApiInsert, ArtifactComponentApiInsert, AgentConversationHistoryConfig, GraphStopWhen, ToolInsert, McpTransportConfig, ArtifactComponentInsert, DataComponentInsert, StopWhen, FullProjectDefinition } from '@inkeep/agents-core';
+import { z } from 'zod';
+
+interface ToolInterface {
+    config: MCPToolConfig$1;
+    init(): Promise<void>;
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getServerUrl(): string;
+    getActiveTools(): string[] | undefined;
+    getCredentialReferenceId(): string | null | undefined;
+}
+declare class Tool implements ToolInterface {
+    config: MCPToolConfig$1;
+    private baseURL;
+    private tenantId;
+    private initialized;
+    private projectId;
+    constructor(config: MCPToolConfig$1);
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getServerUrl(): string;
+    getActiveTools(): string[] | undefined;
+    getCredentialReferenceId(): string | null | undefined;
+    init(options?: {
+        skipDatabaseRegistration?: boolean;
+    }): Promise<void>;
+    private upsertTool;
+}
+
+/**
+ * Function signature for transfer conditions
+ */
+type TransferConditionFunction = (context: unknown) => boolean;
+/**
+ * Configuration for MCP server builders
+ */
+interface MCPServerConfig {
+    name: string;
+    description: string;
+    serverUrl: string;
+    id?: string;
+    parameters?: Record<string, z.ZodJSONSchema>;
+    credential?: CredentialReferenceApiInsert;
+    tenantId?: string;
+    transport?: keyof typeof MCPTransportType;
+    activeTools?: string[];
+    headers?: Record<string, string>;
+    imageUrl?: string;
+}
+/**
+ * Configuration for component builders
+ */
+interface ComponentConfig {
+    name: string;
+    description: string;
+    tenantId?: string;
+    projectId?: string;
+}
+interface ArtifactComponentConfig extends ComponentConfig {
+    summaryProps: Record<string, unknown>;
+    fullProps: Record<string, unknown>;
+}
+interface DataComponentConfig extends ComponentConfig {
+    props: Record<string, unknown>;
+}
+type AgentMcpConfig = {
+    server: Tool;
+    selectedTools: string[];
+};
+/**
+ * Creates a transfer configuration for agent handoffs.
+ *
+ * Transfers allow one agent to hand off control to another agent
+ * based on optional conditions.
+ *
+ * @param targetAgent - The agent to transfer to
+ * @param description - Optional description of when/why to transfer
+ * @param condition - Optional function to determine if transfer should occur
+ * @returns A validated transfer configuration
+ *
+ * @example
+ * ```typescript
+ * // Simple transfer
+ * const handoff = transfer(supportAgent, 'Transfer to support');
+ *
+ * // Conditional transfer
+ * const conditionalHandoff = transfer(
+ *   specialistAgent,
+ *   'Transfer to specialist for complex issues',
+ *   (context) => context.complexity > 0.8
+ * );
+ * ```
+ */
+declare function transfer(targetAgent: Agent, description?: string, condition?: TransferConditionFunction): TransferConfig;
+
+type ExternalAgentConfig = {
+    type?: 'external';
+    tenantId?: string;
+    id: string;
+    name: string;
+    description: string;
+    baseUrl: string;
+    credentialReference?: CredentialReferenceSelect;
+    headers?: Record<string, string>;
+};
+declare class ExternalAgent implements ExternalAgentInterface {
+    config: ExternalAgentConfig;
+    readonly type: "external";
+    private initialized;
+    private tenantId;
+    private baseURL;
+    constructor(config: ExternalAgentConfig);
+    /**
+     * Initialize the external agent by upserting it in the database
+     */
+    init(): Promise<void>;
+    getId(): string;
+    private upsertExternalAgent;
+    /**
+     * Get the external agent configuration
+     */
+    getConfig(): ExternalAgentConfig;
+    /**
+     * Get the external agent name
+     */
+    getName(): string;
+    /**
+     * Get the external agent base URL
+     */
+    getBaseUrl(): string;
+    /**
+     * Get the tenant ID
+     */
+    getTenantId(): string;
+    getDescription(): string;
+    getCredentialReferenceId(): string | undefined;
+    getHeaders(): Record<string, string> | undefined;
+}
+/**
+ * Factory function to create external agents - follows the same pattern as agent()
+ */
+declare function externalAgent(config: ExternalAgentConfig): ExternalAgent;
+/**
+ * Helper function to create multiple external agents
+ */
+declare function externalAgents(configs: Record<string, ExternalAgentConfig>): Record<string, ExternalAgent>;
+
+interface UserMessage {
+    role: 'user';
+    content: string;
+}
+interface AssistantMessage {
+    role: 'assistant';
+    content: string;
+    toolCalls?: ToolCall[];
+}
+interface ToolMessage {
+    role: 'tool';
+    content: string;
+    toolCallId: string;
+}
+interface SystemMessage {
+    role: 'system';
+    content: string;
+}
+type Message = UserMessage | AssistantMessage | ToolMessage | SystemMessage;
+type MessageInput = string | string[] | Message | Message[];
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolResult {
+    id: string;
+    result: any;
+    error?: string;
+}
+type AllAgentInterface = AgentInterface | ExternalAgentInterface;
+type AgentCanUseType = Tool | AgentMcpConfig;
+interface AgentConfig extends Omit<AgentApiInsert, 'projectId'> {
+    type?: 'internal';
+    canUse?: () => AgentCanUseType[];
+    canTransferTo?: () => AgentInterface[];
+    canDelegateTo?: () => AllAgentInterface[];
+    tenantId?: string;
+    projectId?: string;
+    models?: {
+        base?: ModelSettings;
+        structuredOutput?: ModelSettings;
+        summarizer?: ModelSettings;
+    };
+    stopWhen?: AgentStopWhen;
+    memory?: {
+        type: 'conversation' | 'episodic' | 'short_term';
+        capacity?: number;
+    };
+    dataComponents?: () => DataComponentApiInsert[];
+    artifactComponents?: () => ArtifactComponentApiInsert[];
+    conversationHistoryConfig?: AgentConversationHistoryConfig;
+}
+interface ModelSettings {
+    model?: string;
+    providerOptions?: Record<string, Record<string, unknown>>;
+}
+declare const ModelSettingsSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+interface ToolConfig extends ToolInsert {
+    execute: (params: any) => Promise<any>;
+    parameters?: Record<string, any>;
+    schema?: z.ZodJSONSchema;
+}
+interface ServerConfig {
+    type: string;
+    version?: string;
+}
+interface MCPToolConfig {
+    id: string;
+    name: string;
+    tenantId?: string;
+    description?: string;
+    credential?: CredentialReferenceApiInsert;
+    server?: ServerConfig;
+    serverUrl: string;
+    toolName?: string;
+    activeTools?: string[];
+    headers?: Record<string, string>;
+    mcpType?: 'nango' | 'generic';
+    transport?: McpTransportConfig;
+    imageUrl?: string;
+}
+interface FetchDefinitionConfig {
+    id: string;
+    name?: string;
+    trigger: 'initialization' | 'invocation';
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: Record<string, unknown>;
+    transform?: string;
+    responseSchema?: z.ZodSchema<any>;
+    defaultValue?: unknown;
+    timeout?: number;
+    credential?: CredentialReferenceApiInsert;
+}
+interface RequestSchemaDefinition {
+    body?: z.ZodSchema<any>;
+    headers?: z.ZodSchema<any>;
+    query?: z.ZodSchema<any>;
+    params?: z.ZodSchema<any>;
+}
+interface RequestSchemaConfig {
+    schemas: RequestSchemaDefinition;
+    optional?: ('body' | 'headers' | 'query' | 'params')[];
+}
+interface TransferConfig {
+    agent: AgentInterface;
+    description?: string;
+    condition?: (context: any) => boolean;
+}
+interface GenerateOptions {
+    maxTurns?: number;
+    maxSteps?: number;
+    temperature?: number;
+    toolChoice?: 'auto' | 'none' | string;
+    resourceId?: string;
+    conversationId?: string;
+    stream?: boolean;
+    customBodyParams?: Record<string, unknown>;
+}
+interface AgentResponse {
+    id?: string;
+    text: string;
+    toolCalls?: ToolCall[];
+    transfer?: TransferConfig;
+    finishReason: 'completed' | 'tool_calls' | 'transfer' | 'max_turns' | 'error';
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens?: number;
+    };
+    metadata?: Record<string, any>;
+}
+interface StreamResponse {
+    textStream?: AsyncGenerator<string>;
+    eventStream?: AsyncGenerator<StreamEvent>;
+}
+interface StreamEvent {
+    type: 'text' | 'tool_call' | 'transfer' | 'error' | 'done';
+    data: any;
+    timestamp: Date;
+}
+interface RunResult {
+    finalOutput: string;
+    agent: AgentInterface;
+    turnCount: number;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens?: number;
+    };
+    metadata?: {
+        toolCalls: ToolCall[];
+        transfers: TransferConfig[];
+    };
+}
+interface StatusComponent {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    schema: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+interface StatusUpdateSettings {
+    enabled?: boolean;
+    numEvents?: number;
+    timeInSeconds?: number;
+    model?: string;
+    statusComponents?: StatusComponent[];
+    prompt?: string;
+}
+interface GraphConfig {
+    id: string;
+    name?: string;
+    description?: string;
+    defaultAgent?: AgentInterface;
+    agents?: () => AllAgentInterface[];
+    tenantId?: string;
+    contextConfig?: any;
+    credentials?: () => CredentialReferenceApiInsert[];
+    stopWhen?: GraphStopWhen;
+    graphPrompt?: string;
+    models?: {
+        base?: ModelSettings;
+        structuredOutput?: ModelSettings;
+        summarizer?: ModelSettings;
+    };
+    statusUpdates?: StatusUpdateSettings;
+}
+declare class AgentError extends Error {
+    code?: string | undefined;
+    details?: any | undefined;
+    constructor(message: string, code?: string | undefined, details?: any | undefined);
+}
+declare class MaxTurnsExceededError extends AgentError {
+    constructor(maxTurns: number);
+}
+declare class ToolExecutionError extends AgentError {
+    constructor(toolName: string, originalError: Error);
+}
+declare class TransferError extends AgentError {
+    constructor(sourceAgent: string, targetAgent: string, reason: string);
+}
+interface AgentInterface {
+    config: AgentConfig;
+    type: 'internal';
+    init(): Promise<void>;
+    getId(): string;
+    getName(): string;
+    getInstructions(): string;
+    getTools(): Record<string, any>;
+    getTransfers(): AgentInterface[];
+    getDelegates(): AllAgentInterface[];
+    getDataComponents(): DataComponentApiInsert[];
+    getArtifactComponents(): ArtifactComponentApiInsert[];
+    addTool(name: string, tool: any): void;
+    addTransfer(...agents: AgentInterface[]): void;
+    addDelegate(...agents: AgentInterface[]): void;
+}
+interface ExternalAgentInterface {
+    config: ExternalAgentConfig;
+    type: 'external';
+    init(): Promise<void>;
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getBaseUrl(): string;
+    getCredentialReferenceId(): string | undefined;
+    getHeaders(): Record<string, string> | undefined;
+}
+interface GraphInterface {
+    init(): Promise<void>;
+    setConfig(tenantId: string, projectId: string, apiUrl: string): void;
+    getId(): string;
+    getName(): string;
+    getDescription(): string | undefined;
+    getTenantId(): string;
+    generate(input: MessageInput, options?: GenerateOptions): Promise<string>;
+    stream(input: MessageInput, options?: GenerateOptions): Promise<StreamResponse>;
+    generateStream(input: MessageInput, options?: GenerateOptions): Promise<StreamResponse>;
+    getDefaultAgent(): AgentInterface | undefined;
+    getAgent(name: string): AllAgentInterface | undefined;
+    getAgents(): AllAgentInterface[];
+}
+interface BuilderToolConfig {
+    name: string;
+    description: string;
+    config: {
+        type: 'mcp';
+        mcp: {
+            server: {
+                url: string;
+            };
+        };
+    };
+    parameters?: Record<string, any>;
+}
+interface BuilderRelationConfig {
+    targetAgent: string;
+    relationType: 'transfer' | 'delegate';
+}
+interface BuilderAgentConfig {
+    name: string;
+    description: string;
+    instructions: string;
+    tools: BuilderToolConfig[];
+    relations?: BuilderRelationConfig[];
+}
+
+declare class Agent implements AgentInterface {
+    config: AgentConfig;
+    readonly type: "internal";
+    private baseURL;
+    private tenantId;
+    private projectId;
+    private initialized;
+    constructor(config: AgentConfig);
+    getId(): string;
+    getName(): string;
+    getInstructions(): string;
+    getTools(): Record<string, unknown>;
+    getModels(): typeof this$1.config.models;
+    setModels(models: typeof this$1.config.models): void;
+    getTransfers(): AgentInterface[];
+    getDelegates(): AllAgentInterface[];
+    getDataComponents(): DataComponentApiInsert[];
+    getArtifactComponents(): ArtifactComponentApiInsert[];
+    addTool(_name: string, tool: Tool): void;
+    addTransfer(...agents: AgentInterface[]): void;
+    addDelegate(...agents: AllAgentInterface[]): void;
+    init(): Promise<void>;
+    private upsertAgent;
+    private saveToolsAndRelations;
+    private saveDataComponents;
+    private saveArtifactComponents;
+    private loadDataComponents;
+    private loadArtifactComponents;
+    private createTool;
+    private createDataComponent;
+    private createArtifactComponent;
+    private createAgentDataComponentRelation;
+    private createAgentArtifactComponentRelation;
+    private createAgentToolRelation;
+}
+
+interface ArtifactComponentInterface {
+    config: Omit<ArtifactComponentInsert, 'id'>;
+    init(): Promise<void>;
+    getId(): ArtifactComponentInsert['id'];
+    getName(): ArtifactComponentInsert['name'];
+    getDescription(): ArtifactComponentInsert['description'];
+    getSummaryProps(): ArtifactComponentInsert['summaryProps'];
+    getFullProps(): ArtifactComponentInsert['fullProps'];
+}
+declare class ArtifactComponent implements ArtifactComponentInterface {
+    config: ArtifactComponentInsert;
+    private baseURL;
+    private tenantId;
+    private projectId;
+    private initialized;
+    private id;
+    constructor(config: Omit<ArtifactComponentInsert, 'id'>);
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getSummaryProps(): ArtifactComponentInsert['summaryProps'];
+    getFullProps(): ArtifactComponentInsert['fullProps'];
+    init(): Promise<void>;
+    private upsertArtifactComponent;
+}
+
+interface DataComponentInterface {
+    config: Omit<DataComponentInsert, 'id'>;
+    init(): Promise<void>;
+    getId(): DataComponentInsert['id'];
+    getName(): DataComponentInsert['name'];
+    getDescription(): DataComponentInsert['description'];
+    getProps(): DataComponentInsert['props'];
+}
+declare class DataComponent implements DataComponentInterface {
+    config: DataComponentInsert;
+    private baseURL;
+    private tenantId;
+    private projectId;
+    private initialized;
+    private id;
+    constructor(config: Omit<DataComponentInsert, 'id'>);
+    getId(): string;
+    getName(): string;
+    getDescription(): string;
+    getProps(): DataComponentInsert['props'];
+    init(): Promise<void>;
+    private upsertDataComponent;
+}
+
+declare class AgentGraph implements GraphInterface {
+    private agents;
+    private agentMap;
+    private defaultAgent?;
+    private baseURL;
+    private tenantId;
+    private projectId;
+    private graphId;
+    private graphName;
+    private graphDescription?;
+    private initialized;
+    private contextConfig?;
+    private credentials?;
+    private models?;
+    private statusUpdateSettings?;
+    private graphPrompt?;
+    private stopWhen?;
+    private dbClient;
+    constructor(config: GraphConfig);
+    /**
+     * Set or update the configuration (tenantId, projectId and apiUrl)
+     * This is used by the CLI to inject configuration from inkeep.config.ts
+     */
+    setConfig(tenantId: string, projectId: string, apiUrl: string): void;
+    /**
+     * Convert the AgentGraph to FullGraphDefinition format for the new graph endpoint
+     */
+    private toFullGraphDefinition;
+    /**
+     * Initialize all tools in all agents (especially IPCTools that need MCP server URLs)
+     */
+    private initializeAllTools;
+    /**
+     * Initialize the graph and all agents in the backend using the new graph endpoint
+     */
+    init(): Promise<void>;
+    /**
+     * Legacy initialization method - kept for backward compatibility
+     * Initialize the graph and all agents in the backend using individual endpoints
+     */
+    initLegacy(): Promise<void>;
+    /**
+     * Generate a response using the default agent
+     */
+    generate(input: MessageInput, options?: GenerateOptions): Promise<string>;
+    /**
+     * Stream a response using the default agent
+     */
+    stream(input: MessageInput, options?: GenerateOptions): Promise<StreamResponse>;
+    /**
+     * Alias for stream() method for consistency with naming patterns
+     */
+    generateStream(input: MessageInput, options?: GenerateOptions): Promise<StreamResponse>;
+    /**
+     * Run with a specific agent from the graph
+     */
+    runWith(agentId: string, input: MessageInput, options?: GenerateOptions): Promise<RunResult>;
+    /**
+     * Get an agent by name (unified method for all agent types)
+     */
+    getAgent(name: string): AllAgentInterface | undefined;
+    /**
+     * Add an agent to the graph
+     */
+    addAgent(agent: AgentInterface): void;
+    /**
+     * Remove an agent from the graph
+     */
+    removeAgent(id: string): boolean;
+    /**
+     * Get all agents in the graph
+     */
+    getAgents(): AllAgentInterface[];
+    /**
+     * Get all agent ids (unified method for all agent types)
+     */
+    getAgentIds(): string[];
+    /**
+     * Set the default agent
+     */
+    setDefaultAgent(agent: AgentInterface): void;
+    /**
+     * Get the default agent
+     */
+    getDefaultAgent(): AgentInterface | undefined;
+    /**
+     * Get the graph ID
+     */
+    getId(): string;
+    getName(): string;
+    getDescription(): string | undefined;
+    getTenantId(): string;
+    /**
+     * Get the graph's model settingsuration
+     */
+    getModels(): typeof this.models;
+    /**
+     * Set the graph's model settingsuration
+     */
+    setModels(models: typeof this.models): void;
+    /**
+     * Get the graph's prompt configuration
+     */
+    getGraphPrompt(): string | undefined;
+    /**
+     * Get the graph's stopWhen configuration
+     */
+    getStopWhen(): GraphStopWhen;
+    /**
+     * Get the graph's status updates configuration
+     */
+    getStatusUpdateSettings(): StatusUpdateSettings | undefined;
+    /**
+     * Get the summarizer model from the graph's model settings
+     */
+    getSummarizerModel(): ModelSettings | undefined;
+    /**
+     * Get graph statistics
+     */
+    getStats(): {
+        agentCount: number;
+        defaultAgent: string | null;
+        initialized: boolean;
+        graphId: string;
+        tenantId: string;
+    };
+    /**
+     * Validate the graph configuration
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    private _init;
+    /**
+     * Type guard to check if an agent is an internal AgentInterface
+     */
+    isInternalAgent(agent: AllAgentInterface): agent is AgentInterface;
+    /**
+     * Get project-level model settingsuration defaults
+     */
+    private getProjectModelDefaults;
+    /**
+     * Get project-level stopWhen configuration defaults
+     */
+    private getProjectStopWhenDefaults;
+    /**
+     * Apply model inheritance hierarchy: Project -> Graph -> Agent
+     */
+    private applyModelInheritance;
+    /**
+     * Apply stopWhen inheritance hierarchy: Project -> Graph -> Agent
+     */
+    private applyStopWhenInheritance;
+    /**
+     * Propagate graph-level model settings to agents (supporting partial inheritance)
+     */
+    private propagateModelSettingsToAgent;
+    /**
+     * Immediately propagate graph-level models to all agents during construction
+     */
+    private propagateImmediateModelSettings;
+    /**
+     * Type guard to check if an agent is an external AgentInterface
+     */
+    isExternalAgent(agent: AllAgentInterface): agent is ExternalAgentInterface;
+    /**
+     * Execute agent using the backend system instead of local runner
+     */
+    private executeWithBackend;
+    /**
+     * Parse streaming response in SSE format
+     */
+    private parseStreamingResponse;
+    /**
+     * Normalize input messages to the expected format
+     */
+    private normalizeMessages;
+    private saveToDatabase;
+    private saveRelations;
+    private createAgentRelations;
+    private createInternalAgentRelation;
+    private createExternalAgentRelation;
+    /**
+     * Create external agents in the database
+     */
+    private createExternalAgents;
+}
+
+/**
+ * Project configuration interface for the SDK
+ */
+interface ProjectConfig {
+    id: string;
+    name: string;
+    description?: string;
+    tenantId?: string;
+    models?: {
+        base?: ModelSettings;
+        structuredOutput?: ModelSettings;
+        summarizer?: ModelSettings;
+    };
+    stopWhen?: StopWhen;
+    graphs?: () => AgentGraph[];
+}
+/**
+ * Project interface for operations
+ */
+interface ProjectInterface {
+    init(): Promise<void>;
+    setConfig(tenantId: string, apiUrl: string): void;
+    getId(): string;
+    getName(): string;
+    getDescription(): string | undefined;
+    getTenantId(): string;
+    getModels(): ProjectConfig['models'];
+    getStopWhen(): ProjectConfig['stopWhen'];
+    getGraphs(): AgentGraph[];
+    addGraph(graph: AgentGraph): void;
+    removeGraph(id: string): boolean;
+    getStats(): {
+        projectId: string;
+        tenantId: string;
+        graphCount: number;
+        initialized: boolean;
+    };
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+/**
+ * Project class for managing agent projects
+ *
+ * Projects are the top-level organizational unit that contains graphs, agents, and shared configurations.
+ * They provide model inheritance and execution limits that cascade down to graphs and 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-4o-mini' },
+ *     structuredOutput: { model: 'gpt-4o' }
+ *   },
+ *   stopWhen: {
+ *     transferCountIs: 10,
+ *     stepCountIs: 50
+ *   }
+ * });
+ *
+ * await myProject.init();
+ * ```
+ */
+declare class Project implements ProjectInterface {
+    private projectId;
+    private projectName;
+    private projectDescription?;
+    private tenantId;
+    private baseURL;
+    private initialized;
+    private models?;
+    private stopWhen?;
+    private graphs;
+    private graphMap;
+    constructor(config: ProjectConfig);
+    /**
+     * Set or update the configuration (tenantId and apiUrl)
+     * This is used by the CLI to inject configuration from inkeep.config.ts
+     */
+    setConfig(tenantId: string, apiUrl: string): void;
+    /**
+     * Initialize the project and create/update it in the backend using full project approach
+     */
+    init(): Promise<void>;
+    /**
+     * Get the project ID
+     */
+    getId(): string;
+    /**
+     * Get the project name
+     */
+    getName(): string;
+    /**
+     * Get the project description
+     */
+    getDescription(): string | undefined;
+    /**
+     * Get the tenant ID
+     */
+    getTenantId(): string;
+    /**
+     * Get the project's model configuration
+     */
+    getModels(): ProjectConfig['models'];
+    /**
+     * Set the project's model configuration
+     */
+    setModels(models: ProjectConfig['models']): void;
+    /**
+     * Get the project's stopWhen configuration
+     */
+    getStopWhen(): ProjectConfig['stopWhen'];
+    /**
+     * Set the project's stopWhen configuration
+     */
+    setStopWhen(stopWhen: ProjectConfig['stopWhen']): void;
+    /**
+     * Get all graphs in the project
+     */
+    getGraphs(): AgentGraph[];
+    /**
+     * Get a graph by ID
+     */
+    getGraph(id: string): AgentGraph | undefined;
+    /**
+     * Add a graph to the project
+     */
+    addGraph(graph: AgentGraph): void;
+    /**
+     * Remove a graph from the project
+     */
+    removeGraph(id: string): boolean;
+    /**
+     * Get project statistics
+     */
+    getStats(): {
+        projectId: string;
+        tenantId: string;
+        graphCount: number;
+        initialized: boolean;
+    };
+    /**
+     * Validate the project configuration
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Convert the Project to FullProjectDefinition format
+     */
+    private toFullProjectDefinition;
+    /**
+     * Convert project configuration to API format
+     */
+    private toApiFormat;
+}
+
+/**
+ * Helper function to create graphs - OpenAI style
+ */
+declare function agentGraph(config: GraphConfig): AgentGraph;
+/**
+ * Helper function to create projects - OpenAI style
+ *
+ * Projects are the top-level organizational unit that contains graphs, agents, and shared configurations.
+ * They provide model inheritance and execution limits that cascade down to graphs and 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-4o-mini' },
+ *     structuredOutput: { model: 'gpt-4o' }
+ *   },
+ *   stopWhen: {
+ *     transferCountIs: 10,
+ *     stepCountIs: 50
+ *   },
+ *   graphs: () => [
+ *     agentGraph({
+ *       id: 'support-graph',
+ *       name: 'Support Graph',
+ *       // ... graph 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 Agent 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 agent(config: AgentConfig): Agent;
+/**
+ * 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',
+ *   type: 'bearer',
+ *   value: process.env.GITHUB_TOKEN
+ * });
+ * ```
+ */
+declare function credential(config: CredentialReferenceApiInsert): {
+    id: string;
+    credentialStoreId: string;
+    type: "nango" | "memory" | "keychain";
+    retrievalParams?: Record<string, unknown> | 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',
+ *     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$1): 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',
+ *   summaryProps: {
+ *     title: 'Product',
+ *     price: '$0'
+ *   },
+ *   fullProps: {
+ *     title: 'Product',
+ *     price: '$0',
+ *     description: 'Product description',
+ *     image: 'product.jpg'
+ *   }
+ * });
+ * ```
+ */
+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;
+declare function agentMcp(config: AgentMcpConfig): AgentMcpConfig;
+
+interface EnvironmentSettingsConfig {
+    credentials?: {
+        [settingId: string]: CredentialReferenceApiInsert;
+    };
+}
+/**
+ * Create a setting helper with TypeScript autocomplete
+ */
+declare function createEnvironmentSettings<T extends Record<string, EnvironmentSettingsConfig>>(environments: T): {
+    getEnvironmentSetting: (key: keyof NonNullable<T[keyof T]["credentials"]>) => Promise<CredentialReferenceApiInsert>;
+};
+/**
+ * Create type-safe environment configurations
+ */
+declare function registerEnvironmentSettings<T extends EnvironmentSettingsConfig>(config: T): T;
+
+/**
+ * Client-side functions for interacting with the Full Project API
+ * These functions make HTTP requests to the server instead of direct database calls
+ */
+
+/**
+ * Create a full project via HTTP API
+ */
+declare function createFullProjectViaAPI(tenantId: string, apiUrl: string, projectData: FullProjectDefinition): Promise<FullProjectDefinition>;
+/**
+ * Update a full project via HTTP API (upsert behavior)
+ */
+declare function updateFullProjectViaAPI(tenantId: string, apiUrl: string, projectId: string, projectData: FullProjectDefinition): Promise<FullProjectDefinition>;
+/**
+ * Get a full project via HTTP API
+ */
+declare function getFullProjectViaAPI(tenantId: string, apiUrl: string, projectId: string): Promise<FullProjectDefinition | null>;
+/**
+ * Delete a full project via HTTP API
+ */
+declare function deleteFullProjectViaAPI(tenantId: string, apiUrl: string, projectId: string): Promise<void>;
+
+declare class Runner {
+    /**
+     * Run a graph until completion, handling transfers and tool calls
+     * Similar to OpenAI's Runner.run() pattern
+     * NOTE: This now requires a graph instead of an agent
+     */
+    static run(graph: GraphInterface, messages: MessageInput, options?: GenerateOptions): Promise<RunResult>;
+    /**
+     * Stream a graph's response
+     */
+    static stream(graph: GraphInterface, messages: MessageInput, options?: GenerateOptions): Promise<StreamResponse>;
+    /**
+     * Execute multiple graphs in parallel and return the first successful result
+     */
+    static raceGraphs(graphs: GraphInterface[], messages: MessageInput, options?: GenerateOptions): Promise<RunResult>;
+    private static normalizeToMessageHistory;
+    /**
+     * Validate graph configuration before running
+     */
+    static validateGraph(graph: GraphInterface): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Get execution statistics for a graph
+     */
+    static getExecutionStats(graph: GraphInterface, messages: MessageInput, options?: GenerateOptions): Promise<{
+        estimatedTurns: number;
+        estimatedTokens: number;
+        agentCount: number;
+        defaultAgent: string | undefined;
+    }>;
+}
+declare const run: typeof Runner.run;
+declare const stream: typeof Runner.stream;
+declare const raceGraphs: typeof Runner.raceGraphs;
+
+export { Agent, type AgentCanUseType, type AgentConfig, AgentError, type AgentInterface, type AgentResponse, type AllAgentInterface, ArtifactComponent, type AssistantMessage, type BuilderAgentConfig, type BuilderRelationConfig, type BuilderToolConfig, DataComponent, ExternalAgent, type ExternalAgentInterface, type FetchDefinitionConfig, type GenerateOptions, type GraphConfig, type GraphInterface, type MCPToolConfig, MaxTurnsExceededError, type Message, type MessageInput, type ModelSettings, ModelSettingsSchema, Project, type RequestSchemaConfig, type RequestSchemaDefinition, type RunResult, Runner, type ServerConfig, type StatusComponent, type StatusUpdateSettings, type StreamEvent, type StreamResponse, type SystemMessage, Tool, type ToolCall, type ToolConfig, ToolExecutionError, type ToolMessage, type ToolResult, type TransferConfig, TransferError, type UserMessage, agent, agentGraph, agentMcp, artifactComponent, createEnvironmentSettings, createFullProjectViaAPI, credential, dataComponent, deleteFullProjectViaAPI, externalAgent, externalAgents, getFullProjectViaAPI, mcpServer, mcpTool, project, raceGraphs, registerEnvironmentSettings, run, stream, transfer, updateFullProjectViaAPI };