مايكروسوفت فاوندري

يدعم Microsoft Foundry نمطين متميزين للسياق. يستخدم كلاهما الموارد المدارة بواسطة Foundry، ولكنهما يرفقان بعامل بشكل مختلف ويحلان مشكلات مختلفة.

النمط	آلية إطار عمل العامل	السلوك
بحث عن الملفات RAG	أداة البحث عن الملفات المستضافة من قبل الموفر	البحث في الملفات ومخازن المتجهات التي يقوم التطبيق الخاص بك بتحميلها وإدارتها بشكل صريح في مشروع Foundry.
الذاكرة الدلالية المدارة	FoundryMemoryProvider موفر السياق	استخراج الحقائق والملخصات من المحادثات وتخزينها حسب النطاق واسترداد الذكريات ذات الصلة في عمليات التشغيل اللاحقة.

للحصول على استدلال النموذج ووكلاء Foundry المدارين بواسطة الخدمة، راجع Microsoft موفر نموذج Foundry وخدمة عامل Microsoft Foundry.

استخدام RAG للبحث في الملفات

استخدم هذا النمط عندما يجب أن يمتلك Foundry دورة حياة تخزين المستندات ومخزن المتجهات لقاعدة معارف منسقة. البحث عن الملفات هو أداة مستضافة بدلا من موفر سياق؛ راجع إرشادات البحث العام عن الملفات لسلوك الأداة. استخدم البحث باستخدام الذكاء الاصطناعي في Azure عندما يكون مصدر الحقيقة للتطبيق فهرسا البحث باستخدام الذكاء الاصطناعي في Azure.

إنشاء مخزن متجهات Foundry وعامل

قم بتحميل ملف قاعدة المعارف، وإنشاء مخزن متجهات، وإرفاق FileSearchTool، وإنشاء إصدار FoundryAgent.

var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";

// Create an AI Project client and get an OpenAI client that works with the foundry service.
// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
AIProjectClient aiProjectClient = new(
    new Uri(endpoint),
    new DefaultAzureCredential());
OpenAIClient openAIClient = aiProjectClient.GetProjectOpenAIClient();

// Upload the file that contains the data to be used for RAG to the Foundry service.
OpenAIFileClient fileClient = openAIClient.GetOpenAIFileClient();
ClientResult<OpenAIFile> uploadResult = await fileClient.UploadFileAsync(
    filePath: "contoso-outdoors-knowledge-base.md",
    purpose: FileUploadPurpose.Assistants);

// Create a vector store in the Foundry service using the uploaded file.
VectorStoreClient vectorStoreClient = openAIClient.GetVectorStoreClient();
ClientResult<VectorStore> vectorStoreCreate = await vectorStoreClient.CreateVectorStoreAsync(options: new VectorStoreCreationOptions()
{
    Name = "contoso-outdoors-knowledge-base",
    FileIds = { uploadResult.Value.Id }
});

// Use the native OpenAI SDK FileSearchTool directly with the vector store ID.
#pragma warning disable OPENAI001
FileSearchTool fileSearchTool = new([vectorStoreCreate.Value.Id]);
#pragma warning restore OPENAI001

ProjectsAgentVersion agentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
    "AskContoso",
    new ProjectsAgentVersionCreationOptions(
        new DeclarativeAgentDefinition(model: deploymentName)
        {
            Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
            Tools = { fileSearchTool }
        }));
FoundryAgent agent = aiProjectClient.AsAIAgent(agentVersion);

AgentSession session = await agent.CreateSessionAsync();

Console.WriteLine(">> Asking about returns\n");
Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", session));

Console.WriteLine("\n>> Asking about shipping\n");
Console.WriteLine(await agent.RunAsync("How long does standard shipping usually take?", session));

Console.WriteLine("\n>> Asking about product care\n");
Console.WriteLine(await agent.RunAsync("What is the best way to maintain the TrailRunner tent fabric?", session));

// Cleanup
await fileClient.DeleteFileAsync(uploadResult.Value.Id);
await vectorStoreClient.DeleteVectorStoreAsync(vectorStoreCreate.Value.Id);
await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(agent.Name);

إعادة استخدام مخازن المتجهات المستمرة لقواعد معرفة الإنتاج بدلا من إنشائها لكل عملية تشغيل.

تثبيت الحزمة

pip install agent-framework-foundry --pre

قم بإنشاء ملفات ومخزن متجه من خلال عميل OpenAI لمشروع Foundry، ثم مرر أداة البحث عن الملفات الناتجة إلى العامل.

async def create_vector_store(client: FoundryChatClient) -> tuple[str, str]:
    """Create a vector store with sample documents."""
    file = await client.client.files.create(
        file=("todays_weather.txt", b"The weather today is sunny with a high of 75F."), purpose="assistants"
    )
    vector_store = await client.client.vector_stores.create(
        name="knowledge_base",
        expires_after={"anchor": "last_active_at", "days": 1},
    )
    result = await client.client.vector_stores.files.create_and_poll(vector_store_id=vector_store.id, file_id=file.id)
    if result.last_error is not None:
        raise Exception(f"Vector store file processing failed with status: {result.last_error.message}")

    return file.id, vector_store.id


async def delete_vector_store(client: FoundryChatClient, file_id: str, vector_store_id: str) -> None:
    """Delete the vector store after using it."""
    with contextlib.suppress(Exception):
        await client.client.vector_stores.delete(vector_store_id=vector_store_id)
    with contextlib.suppress(Exception):
        await client.client.files.delete(file_id=file_id)


async def main() -> None:
    print("=== Foundry Chat Client with File Search Example ===\n")

    # Initialize the Foundry chat client
    # Make sure you're logged in via 'az login' before running this sample
    client = FoundryChatClient(credential=AzureCliCredential())

    file_id, vector_store_id = await create_vector_store(client)

    # Create file search tool using instance method
    file_search_tool = client.get_file_search_tool(vector_store_ids=[vector_store_id])

    agent = Agent(
        client=client,
        instructions="You are a helpful assistant that can search through files to find information.",
        tools=[file_search_tool],
    )

    query = "What is the weather today? Do a file search to find the answer."
    print(f"User: {query}")
    result = await agent.run(query)
    print(f"Agent: {result}\n")

    await delete_vector_store(client, file_id, vector_store_id)

Note

تكامل بحث ملف Foundry غير موثق حاليا ل Agent Framework Go. راجع مستودع Agent Framework Go للحصول على أحدث دعم أداة مستضافة.

إضافة ذاكرة دلالية مدارة

استخدم FoundryMemoryProvider عندما يجب على العامل استدعاء سياق المستخدم الدائم أو التطبيق عبر الجلسات. تخزن ذاكرة Foundry الحقائق والملخصات المستخرجة بشكل منفصل عن نسخة المحادثة الكاملة.

تثبيت الحزمة

dotnet add package Microsoft.Agents.AI.Foundry --prerelease

أنشئ FoundryMemoryProvider باستخدام نطاق ثابت، وتأكد من وجود مخزن الذاكرة، وانتظر التحديثات غير المتزامنة قبل الاعتماد على الذكريات المستخرجة حديثا.

// Create an AIProjectClient for Foundry with Azure Identity authentication.
// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(new Uri(foundryEndpoint), credential);

// Get the ChatClient from the AIProjectClient's OpenAI property using the deployment name.
// The stateInitializer can be used to customize the Foundry Memory scope per session and it will be called each time a session
// is encountered by the FoundryMemoryProvider that does not already have state stored on the session.
// If each session should have its own scope, you can create a new id per session via the stateInitializer, e.g.:
// new FoundryMemoryProvider(projectClient, memoryStoreName, stateInitializer: _ => new(new FoundryMemoryProviderScope(Guid.NewGuid().ToString())), ...)
// In our case we are storing memories scoped by user so that memories are retained across sessions.
FoundryMemoryProvider memoryProvider = new(
    projectClient,
    memoryStoreName,
    stateInitializer: _ => new(new FoundryMemoryProviderScope("sample-user-123")));

ChatClientAgent agent = projectClient.AsAIAgent(
    new ChatClientAgentOptions()
    {
        Name = "TravelAssistantWithFoundryMemory",
        ChatOptions = new()
        {
            ModelId = deploymentName,
            Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details."
        },
        AIContextProviders = [memoryProvider]
    });

AgentSession session = await agent.CreateSessionAsync();

Console.WriteLine("\n>> Setting up Foundry Memory Store\n");

// Ensure the memory store exists (creates it with the specified models if needed).
await memoryProvider.EnsureMemoryStoreCreatedAsync(deploymentName, embeddingModelName, "Sample memory store for travel assistant");

// Clear any existing memories for this scope to demonstrate fresh behavior.
await memoryProvider.EnsureStoredMemoriesDeletedAsync(session);

Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));

// Memory extraction in Microsoft Foundry is asynchronous and takes time to process.
// WhenUpdatesCompletedAsync polls all pending updates and waits for them to complete.
Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
await memoryProvider.WhenUpdatesCompletedAsync();

Console.WriteLine("Updates completed.\n");

Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));

Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
JsonElement serializedSession = await agent.SerializeSessionAsync(session);
AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));

Console.WriteLine("\n>> Start a new session that shares the same Foundry Memory scope\n");

Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
await memoryProvider.WhenUpdatesCompletedAsync();

AgentSession newSession = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newSession));

تثبيت الحزمة

pip install agent-framework-foundry --pre

قم بإنشاء مخزن الذاكرة من خلال AIProjectClient، ثم قم بإرفاقه FoundryMemoryProvider بالعامل.

async def main() -> None:
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    ):
        # Generate a unique memory store name to avoid conflicts
        memory_store_name = f"agent_framework_memory_{datetime.now(timezone.utc).strftime('%Y%m%d')}"
        # Specify memory store options
        options = MemoryStoreDefaultOptions(
            chat_summary_enabled=False,
            user_profile_enabled=True,
            user_profile_details="Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials",
        )
        memory_store_definition = MemoryStoreDefaultDefinition(
            chat_model=os.environ["FOUNDRY_MODEL"],
            embedding_model=os.environ["AZURE_OPENAI_EMBEDDING_MODEL"],
            options=options,
        )
        print(f"Creating memory store '{memory_store_name}'...")
        try:
            # Create a memory store
            memory_store = await project_client.beta.memory_stores.create(
                name=memory_store_name,
                description="Memory store for Agent Framework with FoundryMemoryProvider",
                definition=memory_store_definition,
            )
        except Exception as e:
            print(f"Failed to create memory store: {e}")
            return

        print(f"Created memory store: {memory_store.name} ({memory_store.id})")
        print(f"Description: {memory_store.description}\n")
        print("==========================================")

        # Create the chat client
        client = FoundryChatClient(project_client=project_client)
        # Create the Foundry Memory context provider
        memory_provider = FoundryMemoryProvider(
            project_client=project_client,
            memory_store_name=memory_store.name,
            scope="user_123",  # Scope memories to a specific user, if not set, the session_id
            # will be used as scope, which means memories are only shared within the same session
            update_delay=0,  # Do not wait to update memories after each interaction (for demo purposes)
            # In production, consider setting a delay to batch updates and reduce costs
        )

        # Create an agent with the memory context provider
        async with Agent(
            name="MemoryAgent",
            client=client,
            instructions="""You are a helpful assistant that remembers past conversations.
                The memories from previous interactions are automatically provided to you.""",
            context_providers=[memory_provider, InMemoryHistoryProvider(load_messages=False)],
            default_options={"store": False},
        ) as agent:
            try:
                # note that we will use the service side storage, nor load messsages from the history provider,
                # but we include it to demonstrate that it can be used alongside the Foundry provider for other use cases.
                session = agent.create_session()

                # First interaction - establish some preferences
                print("=== First conversation ===")
                query1 = "I prefer dark roast coffee and I'm allergic to nuts"
                print(f"User: {query1}")
                result1 = await agent.run(query1, session=session)
                print(f"Agent: {result1}\n")

                # Wait for memories to be processed
                print("Waiting for memories to be stored...")
                await asyncio.sleep(8)

                # Second interaction - test memory recall
                print("=== Second conversation ===")
                query2 = "Can you recommend a coffee and snack for me?"
                print(f"User: {query2}")
                result2 = await agent.run(query2, session=session)
                print(f"Agent: {result2}\n")

                # Third interaction - continue the conversation
                print("=== Third conversation ===")
                query3 = "What do you remember about my preferences?"
                print(f"User: {query3}")
                result3 = await agent.run(query3, session=session)
                print(f"Agent: {result3}\n")

                print(f"Stored memories from: {memory_store.name} ({memory_store.id})")
                res = await project_client.beta.memory_stores.search_memories(name=memory_store.name, scope="user_123")
                for memory in res.memories:
                    print(f"Memory: {memory.memory_item.content}")

            except Exception as e:
                print(f"An error occurred: {e}")

            finally:
                await project_client.beta.memory_stores.delete(memory_store_name)

يقوم النموذج بتعطيل تحميل النص من جانب الخدمة والنسخة المحلية بحيث توضح الاستجابة اللاحقة الذاكرة الدلالية بدلا من إعادة تشغيل محفوظات الدردشة.

Note

Microsoft لا يتوفر تكامل ذاكرة Foundry حاليا ل Agent Framework Go. راجع مستودع Agent Framework Go للحصول على أحدث حالة.

اعتبارات الإنتاج

• إعادة استخدام مخازن المتجهات المستمرة لقواعد معرفة الإنتاج.
• استخدم معرفات نطاق الذاكرة الثابتة المملوكة للتطبيق وتخويل الوصول قبل تحديد نطاق.
• انتظر الاستخراج غير المتزامن عندما تعتمد عملية لاحقة على الذاكرة المكتوبة حديثا.
• احتفظ بالنسخ الدقيقة في موفر المحفوظات عندما تحتاج إلى سجلات محادثات كاملة.
• تكوين عمليات نشر الاستبقاء والمنطقة والنموذج لمطابقة متطلبات التوافق الخاصة بك.

الخطوات التالية

Neo4j

انتقل إلى أبعد من ذلك:

• مفاهيم موفر السياق
• موفر نموذج Microsoft Foundry