@promptbook/remote-server 0.105.0-26 → 0.105.0-30

package/esm/typings/src/_packages/openai.index.d.ts

@@ -3,6 +3,7 @@ import { createOpenAiAssistantExecutionTools } from '../llm-providers/openai/cre
 import { createOpenAiCompatibleExecutionTools } from '../llm-providers/openai/createOpenAiCompatibleExecutionTools';
 import { createOpenAiExecutionTools } from '../llm-providers/openai/createOpenAiExecutionTools';
 import { OPENAI_MODELS } from '../llm-providers/openai/openai-models';
+import { OpenAiAgentExecutionTools } from '../llm-providers/openai/OpenAiAgentExecutionTools';
 import { OpenAiAssistantExecutionTools } from '../llm-providers/openai/OpenAiAssistantExecutionTools';
 import type { OpenAiAssistantExecutionToolsOptions } from '../llm-providers/openai/OpenAiAssistantExecutionToolsOptions';
 import { OpenAiCompatibleExecutionTools } from '../llm-providers/openai/OpenAiCompatibleExecutionTools';
@@ -19,6 +20,7 @@ export { createOpenAiAssistantExecutionTools };
 export { createOpenAiCompatibleExecutionTools };
 export { createOpenAiExecutionTools };
 export { OPENAI_MODELS };
+export { OpenAiAgentExecutionTools };
 export { OpenAiAssistantExecutionTools };
 export type { OpenAiAssistantExecutionToolsOptions };
 export { OpenAiCompatibleExecutionTools };

package/esm/typings/src/_packages/types.index.d.ts

@@ -136,6 +136,7 @@ import type { AzureOpenAiExecutionToolsOptions } from '../llm-providers/azure-op
 import type { DeepseekExecutionToolsOptions } from '../llm-providers/deepseek/DeepseekExecutionToolsOptions';
 import type { GoogleExecutionToolsOptions } from '../llm-providers/google/GoogleExecutionToolsOptions';
 import type { OllamaExecutionToolsOptions } from '../llm-providers/ollama/OllamaExecutionToolsOptions';
+import type { OpenAiAgentExecutionToolsOptions } from '../llm-providers/openai/OpenAiAgentExecutionTools';
 import type { OpenAiAssistantExecutionToolsOptions } from '../llm-providers/openai/OpenAiAssistantExecutionToolsOptions';
 import type { OpenAiCompatibleExecutionToolsOptions } from '../llm-providers/openai/OpenAiCompatibleExecutionToolsOptions';
 import type { OpenAiCompatibleExecutionToolsNonProxiedOptions } from '../llm-providers/openai/OpenAiCompatibleExecutionToolsOptions';
@@ -530,6 +531,7 @@ export type { AzureOpenAiExecutionToolsOptions };
 export type { DeepseekExecutionToolsOptions };
 export type { GoogleExecutionToolsOptions };
 export type { OllamaExecutionToolsOptions };
+export type { OpenAiAgentExecutionToolsOptions };
 export type { OpenAiAssistantExecutionToolsOptions };
 export type { OpenAiCompatibleExecutionToolsOptions };
 export type { OpenAiCompatibleExecutionToolsNonProxiedOptions };

package/esm/typings/src/book-components/Chat/utils/resolveCitationUrl.d.ts

@@ -0,0 +1,11 @@
+import { ChatParticipant } from '../types/ChatParticipant';
+/**
+ * Resolves the URL for a citation source by looking up KNOWLEDGE commitments in the agent's source code.
+ *
+ * @param source - The source filename (e.g. "document.pdf")
+ * @param participants - List of chat participants to search in
+ * @returns The resolved URL if found, or null
+ *
+ * @private utility of <Chat/> component
+ */
+export declare function resolveCitationUrl(source: string, participants: ReadonlyArray<ChatParticipant>): string | null;

package/esm/typings/src/llm-providers/agent/Agent.d.ts

@@ -14,7 +14,8 @@ import type { AgentOptions } from './AgentOptions';
  * - `Agent` - which represents an AI Agent with its source, memories, actions, etc. Agent is a higher-level abstraction which is internally using:
  * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
  * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
- * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
+ * - `OpenAiAgentExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with agent capabilities (using Responses API), recommended for usage in `Agent` or `AgentLlmExecutionTools`
+ * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
  * @public exported from `@promptbook/core`

package/esm/typings/src/llm-providers/agent/AgentLlmExecutionTools.d.ts

@@ -16,7 +16,8 @@ import type { CreateAgentLlmExecutionToolsOptions } from './CreateAgentLlmExecut
  * - `Agent` - which represents an AI Agent with its source, memories, actions, etc. Agent is a higher-level abstraction which is internally using:
  * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
  * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
- * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
+ * - `OpenAiAgentExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with agent capabilities (using Responses API), recommended for usage in `Agent` or `AgentLlmExecutionTools`
+ * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
  * @public exported from `@promptbook/core`
@@ -27,6 +28,10 @@ export declare class AgentLlmExecutionTools implements LlmExecutionTools {
      * Cache of OpenAI assistants to avoid creating duplicates
      */
     private static assistantCache;
+    /**
+     * Cache of OpenAI vector stores to avoid creating duplicates
+     */
+    private static vectorStoreCache;
     /**
      * Cached model requirements to avoid re-parsing the agent source
      */

package/esm/typings/src/llm-providers/openai/OpenAiAgentExecutionTools.d.ts

@@ -0,0 +1,43 @@
+import OpenAI from 'openai';
+import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
+import type { ChatPromptResult } from '../../execution/PromptResult';
+import type { Prompt } from '../../types/Prompt';
+import type { string_markdown, string_markdown_text, string_title } from '../../types/typeAliases';
+import type { OpenAiCompatibleExecutionToolsNonProxiedOptions } from './OpenAiCompatibleExecutionToolsOptions';
+import { OpenAiExecutionTools } from './OpenAiExecutionTools';
+/**
+ * Options for OpenAiAgentExecutionTools
+ */
+export type OpenAiAgentExecutionToolsOptions = OpenAiCompatibleExecutionToolsNonProxiedOptions & {
+    /**
+     * ID of the vector store to use for file search
+     */
+    readonly vectorStoreId?: string;
+};
+/**
+ * Execution Tools for calling OpenAI API using the Responses API (Agents)
+ *
+ * @public exported from `@promptbook/openai`
+ */
+export declare class OpenAiAgentExecutionTools extends OpenAiExecutionTools implements LlmExecutionTools {
+    readonly vectorStoreId?: string;
+    constructor(options: OpenAiAgentExecutionToolsOptions);
+    get title(): string_title & string_markdown_text;
+    get description(): string_markdown;
+    /**
+     * Calls OpenAI API to use a chat model with streaming.
+     */
+    callChatModelStream(prompt: Prompt, onProgress: (chunk: ChatPromptResult) => void): Promise<ChatPromptResult>;
+    /**
+     * Creates a vector store from knowledge sources
+     */
+    static createVectorStore(client: OpenAI, name: string, knowledgeSources: ReadonlyArray<string>): Promise<string>;
+    /**
+     * Discriminant for type guards
+     */
+    protected get discriminant(): string;
+    /**
+     * Type guard to check if given `LlmExecutionTools` are instanceof `OpenAiAgentExecutionTools`
+     */
+    static isOpenAiAgentExecutionTools(llmExecutionTools: LlmExecutionTools): llmExecutionTools is OpenAiAgentExecutionTools;
+}

package/esm/typings/src/llm-providers/openai/OpenAiAssistantExecutionTools.d.ts

@@ -18,6 +18,7 @@ import { OpenAiExecutionTools } from './OpenAiExecutionTools';
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
  * @public exported from `@promptbook/openai`
+ * @deprecated Use `OpenAiAgentExecutionTools` instead which uses the new OpenAI Responses API
  */
 export declare class OpenAiAssistantExecutionTools extends OpenAiExecutionTools implements LlmExecutionTools {
     readonly assistantId: string_token;

package/esm/typings/src/llm-providers/openai/OpenAiCompatibleExecutionTools.d.ts

@@ -73,7 +73,7 @@ export declare abstract class OpenAiCompatibleExecutionTools implements LlmExecu
     /**
      * Calls OpenAI compatible API to use a image generation model
      */
-    callImageGenerationModel(prompt: Pick<Prompt, 'content' | 'parameters' | 'modelRequirements'>): Promise<ImagePromptResult>;
+    callImageGenerationModel(prompt: Prompt): Promise<ImagePromptResult>;
     /**
      * Internal method that handles parameter retry for image generation model calls
      */

package/esm/typings/src/types/ModelRequirements.d.ts

@@ -129,6 +129,12 @@ export type CommonModelRequirements = {
      * Note: [🚉] This is fully serializable as JSON
      */
     readonly tools?: LlmToolDefinition[];
+    /**
+     * Optional list of knowledge source links that the model can use
+     *
+     * Note: [🚉] This is fully serializable as JSON
+     */
+    readonly knowledgeSources?: string[];
 };
 /**
  * TODO: [🧠][🈁] `seed` should maybe be somewhere else (not in `ModelRequirements`) (similar that `user` identification is not here)

package/esm/typings/src/types/Prompt.d.ts

@@ -72,6 +72,14 @@ export type ImagePrompt = CommonPrompt & {
      * Requirements for image generation model
      */
     modelRequirements: ImageGenerationModelRequirements;
+    /**
+     * Optional file attachments
+     */
+    attachments?: Array<{
+        name: string;
+        type: string;
+        url: string;
+    }>;
 };
 /**
  * Embedding prompt

package/esm/typings/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.105.0-25`).
+ * It follows semantic versioning (e.g., `0.105.0-28`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/remote-server",
-    "version": "0.105.0-26",
+    "version": "0.105.0-30",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,
@@ -95,7 +95,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/remote-server.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.105.0-26"
+        "@promptbook/core": "0.105.0-30"
     },
     "dependencies": {
         "@mozilla/readability": "0.6.0",

package/umd/index.umd.js

@@ -50,7 +50,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.105.0-26';
+    const PROMPTBOOK_ENGINE_VERSION = '0.105.0-30';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -19175,7 +19175,11 @@
                 quality: currentModelRequirements.quality,
                 style: currentModelRequirements.style,
             };
-            const rawPromptContent = templateParameters(content, { ...parameters, modelName });
+            let rawPromptContent = templateParameters(content, { ...parameters, modelName });
+            if ('attachments' in prompt && Array.isArray(prompt.attachments) && prompt.attachments.length > 0) {
+                rawPromptContent +=
+                    '\n\n' + prompt.attachments.map((attachment) => `Image attachment: ${attachment.url}`).join('\n');
+            }
             const rawRequest = {
                 ...modelSettings,
                 prompt: rawPromptContent,
@@ -19468,6 +19472,207 @@
         }
     }
 
+    /**
+     * Execution Tools for calling OpenAI API using the Responses API (Agents)
+     *
+     * @public exported from `@promptbook/openai`
+     */
+    class OpenAiAgentExecutionTools extends OpenAiExecutionTools {
+        constructor(options) {
+            super(options);
+            this.vectorStoreId = options.vectorStoreId;
+        }
+        get title() {
+            return 'OpenAI Agent';
+        }
+        get description() {
+            return 'Use OpenAI Responses API (Agentic)';
+        }
+        /**
+         * Calls OpenAI API to use a chat model with streaming.
+         */
+        async callChatModelStream(prompt, onProgress) {
+            if (this.options.isVerbose) {
+                console.info('💬 OpenAI Agent callChatModel call', { prompt });
+            }
+            const { content, parameters, modelRequirements } = prompt;
+            const client = await this.getClient();
+            if (modelRequirements.modelVariant !== 'CHAT') {
+                throw new PipelineExecutionError('Use callChatModel only for CHAT variant');
+            }
+            const rawPromptContent = templateParameters(content, {
+                ...parameters,
+                modelName: 'agent',
+            });
+            // Build input items
+            const input = []; // TODO: Type properly when OpenAI types are updated
+            // Add previous messages from thread (if any)
+            if ('thread' in prompt && Array.isArray(prompt.thread)) {
+                const previousMessages = prompt.thread.map((msg) => ({
+                    role: msg.sender === 'assistant' ? 'assistant' : 'user',
+                    content: msg.content,
+                }));
+                input.push(...previousMessages);
+            }
+            // Add current user message
+            input.push({
+                role: 'user',
+                content: rawPromptContent,
+            });
+            // Prepare tools
+            const tools = modelRequirements.tools ? mapToolsToOpenAi(modelRequirements.tools) : undefined;
+            // Add file_search if vector store is present
+            const agentTools = tools ? [...tools] : [];
+            let toolResources = undefined;
+            if (this.vectorStoreId) {
+                agentTools.push({ type: 'file_search' });
+                toolResources = {
+                    file_search: {
+                        vector_store_ids: [this.vectorStoreId],
+                    },
+                };
+            }
+            // Add file_search also if knowledgeSources are present in the prompt (passed via AgentLlmExecutionTools)
+            if (modelRequirements.knowledgeSources &&
+                modelRequirements.knowledgeSources.length > 0 &&
+                !this.vectorStoreId) {
+                // Note: Vector store should have been created by AgentLlmExecutionTools and passed via options.
+                // If we are here, it means we have knowledge sources but no vector store ID.
+                // We can't easily create one here without persisting it.
+                console.warn('Knowledge sources provided but no vector store ID. Creating temporary vector store is not implemented in callChatModelStream.');
+            }
+            const start = $getCurrentDate();
+            // Construct the request
+            const rawRequest = {
+                // TODO: Type properly as OpenAI.Responses.CreateResponseParams
+                model: modelRequirements.modelName || 'gpt-4o',
+                input,
+                instructions: modelRequirements.systemMessage,
+                tools: agentTools.length > 0 ? agentTools : undefined,
+                tool_resources: toolResources,
+                store: false, // Stateless by default as we pass full history
+            };
+            if (this.options.isVerbose) {
+                console.info(colors__default["default"].bgWhite('rawRequest (Responses API)'), JSON.stringify(rawRequest, null, 4));
+            }
+            // Call Responses API
+            // Note: Using any cast because types might not be updated yet
+            const response = await client.responses.create(rawRequest);
+            if (this.options.isVerbose) {
+                console.info(colors__default["default"].bgWhite('rawResponse'), JSON.stringify(response, null, 4));
+            }
+            const complete = $getCurrentDate();
+            let resultContent = '';
+            const toolCalls = [];
+            // Parse output items
+            if (response.output) {
+                for (const item of response.output) {
+                    if (item.type === 'message' && item.role === 'assistant') {
+                        for (const contentPart of item.content) {
+                            if (contentPart.type === 'output_text') {
+                                // "output_text" based on migration guide, or "text"? Guide says "output_text" in example.
+                                resultContent += contentPart.text;
+                            }
+                            else if (contentPart.type === 'text') {
+                                resultContent += contentPart.text.value || contentPart.text;
+                            }
+                        }
+                    }
+                    else if (item.type === 'function_call') ;
+                }
+            }
+            // Use output_text helper if available (mentioned in guide)
+            if (response.output_text) {
+                resultContent = response.output_text;
+            }
+            // TODO: Handle tool calls properly (Requires clearer docs or experimentation)
+            onProgress({
+                content: resultContent,
+                modelName: response.model || 'agent',
+                timing: { start, complete },
+                usage: UNCERTAIN_USAGE,
+                rawPromptContent,
+                rawRequest,
+                rawResponse: response,
+            });
+            return exportJson({
+                name: 'promptResult',
+                message: `Result of \`OpenAiAgentExecutionTools.callChatModelStream\``,
+                order: [],
+                value: {
+                    content: resultContent,
+                    modelName: response.model || 'agent',
+                    timing: { start, complete },
+                    usage: UNCERTAIN_USAGE,
+                    rawPromptContent,
+                    rawRequest,
+                    rawResponse: response,
+                    toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+                },
+            });
+        }
+        /**
+         * Creates a vector store from knowledge sources
+         */
+        static async createVectorStore(client, name, knowledgeSources) {
+            // Create a vector store
+            const vectorStore = await client.beta.vectorStores.create({
+                name: `${name} Knowledge Base`,
+            });
+            const vectorStoreId = vectorStore.id;
+            // Upload files from knowledge sources to the vector store
+            const fileStreams = [];
+            for (const source of knowledgeSources) {
+                try {
+                    // Check if it's a URL
+                    if (source.startsWith('http://') || source.startsWith('https://')) {
+                        // Download the file
+                        const response = await fetch(source);
+                        if (!response.ok) {
+                            console.error(`Failed to download ${source}: ${response.statusText}`);
+                            continue;
+                        }
+                        const buffer = await response.arrayBuffer();
+                        const filename = source.split('/').pop() || 'downloaded-file';
+                        const blob = new Blob([buffer]);
+                        const file = new File([blob], filename);
+                        fileStreams.push(file);
+                    }
+                    else {
+                        // Local files not supported in browser env easily, same as before
+                    }
+                }
+                catch (error) {
+                    console.error(`Error processing knowledge source ${source}:`, error);
+                }
+            }
+            // Batch upload files to the vector store
+            if (fileStreams.length > 0) {
+                try {
+                    await client.beta.vectorStores.fileBatches.uploadAndPoll(vectorStoreId, {
+                        files: fileStreams,
+                    });
+                }
+                catch (error) {
+                    console.error('Error uploading files to vector store:', error);
+                }
+            }
+            return vectorStoreId;
+        }
+        /**
+         * Discriminant for type guards
+         */
+        get discriminant() {
+            return 'OPEN_AI_AGENT';
+        }
+        /**
+         * Type guard to check if given `LlmExecutionTools` are instanceof `OpenAiAgentExecutionTools`
+         */
+        static isOpenAiAgentExecutionTools(llmExecutionTools) {
+            return llmExecutionTools.discriminant === 'OPEN_AI_AGENT';
+        }
+    }
+
     /**
      * Uploads files to OpenAI and returns their IDs
      *
@@ -19502,6 +19707,7 @@
      * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
      *
      * @public exported from `@promptbook/openai`
+     * @deprecated Use `OpenAiAgentExecutionTools` instead which uses the new OpenAI Responses API
      */
     class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
         /**
@@ -20142,7 +20348,8 @@
      * - `Agent` - which represents an AI Agent with its source, memories, actions, etc. Agent is a higher-level abstraction which is internally using:
      * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
      * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
-     * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
+     * - `OpenAiAgentExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with agent capabilities (using Responses API), recommended for usage in `Agent` or `AgentLlmExecutionTools`
+     * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
      * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
      *
      * @public exported from `@promptbook/core`
@@ -20270,15 +20477,78 @@
                     ...modelRequirements,
                     // Spread tools to convert readonly array to mutable
                     tools: modelRequirements.tools ? [...modelRequirements.tools] : chatPrompt.modelRequirements.tools,
+                    // Spread knowledgeSources to convert readonly array to mutable
+                    knowledgeSources: modelRequirements.knowledgeSources
+                        ? [...modelRequirements.knowledgeSources]
+                        : undefined,
                     // Prepend agent system message to existing system message
                     systemMessage: modelRequirements.systemMessage +
                         (chatPrompt.modelRequirements.systemMessage
                             ? `\n\n${chatPrompt.modelRequirements.systemMessage}`
                             : ''),
-                },
+                }, // Cast to avoid readonly mismatch from spread
             };
             console.log('!!!! promptWithAgentModelRequirements:', promptWithAgentModelRequirements);
-            if (OpenAiAssistantExecutionTools.isOpenAiAssistantExecutionTools(this.options.llmTools)) {
+            if (OpenAiAgentExecutionTools.isOpenAiAgentExecutionTools(this.options.llmTools)) {
+                const requirementsHash = cryptoJs.SHA256(JSON.stringify(modelRequirements)).toString();
+                const cached = AgentLlmExecutionTools.vectorStoreCache.get(this.title);
+                let agentTools;
+                if (cached && cached.requirementsHash === requirementsHash) {
+                    if (this.options.isVerbose) {
+                        console.log(`1️⃣ Using cached OpenAI Agent Vector Store for agent ${this.title}...`);
+                    }
+                    // Create new instance with cached vectorStoreId
+                    // We need to access options from the original tool.
+                    // We assume isOpenAiAgentExecutionTools implies it has options we can clone.
+                    // But protected options are not accessible.
+                    // We can cast to access options if they were public, or use a method to clone.
+                    // OpenAiAgentExecutionTools doesn't have a clone method.
+                    // However, we can just assume the passed tool *might* not have the vector store yet, or we are replacing it.
+                    // Actually, if the passed tool IS OpenAiAgentExecutionTools, we should use it as a base.
+                    // TODO: [🧠] This is a bit hacky, accessing protected options or recreating tools.
+                    // Ideally OpenAiAgentExecutionTools should have a method `withVectorStoreId`.
+                    agentTools = new OpenAiAgentExecutionTools({
+                        ...this.options.llmTools.options,
+                        vectorStoreId: cached.vectorStoreId,
+                    });
+                }
+                else {
+                    if (this.options.isVerbose) {
+                        console.log(`1️⃣ Creating/Updating OpenAI Agent Vector Store for agent ${this.title}...`);
+                    }
+                    let vectorStoreId;
+                    if (modelRequirements.knowledgeSources && modelRequirements.knowledgeSources.length > 0) {
+                        const client = await this.options.llmTools.getClient();
+                        vectorStoreId = await OpenAiAgentExecutionTools.createVectorStore(client, this.title, modelRequirements.knowledgeSources);
+                    }
+                    if (vectorStoreId) {
+                        AgentLlmExecutionTools.vectorStoreCache.set(this.title, {
+                            vectorStoreId,
+                            requirementsHash,
+                        });
+                    }
+                    agentTools = new OpenAiAgentExecutionTools({
+                        ...this.options.llmTools.options,
+                        vectorStoreId,
+                    });
+                }
+                // Create modified chat prompt with agent system message specific to OpenAI Agent
+                // Note: Unlike Assistants API, Responses API expects instructions (system message) to be passed in the call.
+                // So we use promptWithAgentModelRequirements which has the system message prepended.
+                // But we need to make sure we pass knowledgeSources in modelRequirements so OpenAiAgentExecutionTools can fallback to warning if vectorStoreId is missing (though we just handled it).
+                const promptForAgent = {
+                    ...promptWithAgentModelRequirements,
+                    modelRequirements: {
+                        ...promptWithAgentModelRequirements.modelRequirements,
+                        knowledgeSources: modelRequirements.knowledgeSources
+                            ? [...modelRequirements.knowledgeSources]
+                            : undefined, // Pass knowledge sources explicitly
+                    },
+                };
+                underlyingLlmResult = await agentTools.callChatModelStream(promptForAgent, onProgress);
+            }
+            else if (OpenAiAssistantExecutionTools.isOpenAiAssistantExecutionTools(this.options.llmTools)) {
+                // ... deprecated path ...
                 const requirementsHash = cryptoJs.SHA256(JSON.stringify(modelRequirements)).toString();
                 const cached = AgentLlmExecutionTools.assistantCache.get(this.title);
                 let assistant;
@@ -20373,6 +20643,10 @@
      * Cache of OpenAI assistants to avoid creating duplicates
      */
     AgentLlmExecutionTools.assistantCache = new Map();
+    /**
+     * Cache of OpenAI vector stores to avoid creating duplicates
+     */
+    AgentLlmExecutionTools.vectorStoreCache = new Map();
     /**
      * TODO: [🍚] Implement Destroyable pattern to free resources
      * TODO: [🧠] Adding parameter substitution support (here or should be responsibility of the underlying LLM Tools)
@@ -20386,7 +20660,8 @@
      * - `Agent` - which represents an AI Agent with its source, memories, actions, etc. Agent is a higher-level abstraction which is internally using:
      * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
      * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
-     * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
+     * - `OpenAiAgentExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with agent capabilities (using Responses API), recommended for usage in `Agent` or `AgentLlmExecutionTools`
+     * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
      * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
      *
      * @public exported from `@promptbook/core`