From bb1ec79ca120b6722e8935312322b8fb617fcc1d Mon Sep 17 00:00:00 2001 From: visy-ani Date: Mon, 4 May 2026 14:29:13 +0530 Subject: [PATCH 1/4] samples: add Synap context provider example --- .../context_providers/synap/README.md | 32 +++++++++++++ .../context_providers/synap/synap_basic.py | 45 +++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 python/samples/02-agents/context_providers/synap/README.md create mode 100644 python/samples/02-agents/context_providers/synap/synap_basic.py diff --git a/python/samples/02-agents/context_providers/synap/README.md b/python/samples/02-agents/context_providers/synap/README.md new file mode 100644 index 0000000000..f1d951d04a --- /dev/null +++ b/python/samples/02-agents/context_providers/synap/README.md @@ -0,0 +1,32 @@ +# Synap Context Provider Sample + +Demonstrates [SynapContextProvider](https://docs.maximem.ai/integrations/microsoft-agent) — a Microsoft Agent Framework `ContextProvider` backed by [Synap](https://maximem.ai), a managed memory layer for AI agents. + +## How It Works + +`SynapContextProvider` implements two lifecycle hooks: +- **`before_run`**: fetches Synap context relevant to the user's input and appends it to the agent's instructions via `context.extend_instructions(...)` +- **`after_run`**: records input and response messages to Synap via `sdk.conversation.record_message(...)` for future retrieval + +Read failures degrade gracefully — a Synap outage never breaks the agent run. Write failures are logged but not re-raised. + +## Setup + +```bash +pip install maximem-synap-microsoft-agent +``` + +Set `SYNAP_API_KEY` (get one at [synap.maximem.ai](https://synap.maximem.ai)). + +## Run + +```bash +python synap_basic.py +``` + +## More Resources + +- [Synap Documentation](https://docs.maximem.ai) +- [Microsoft Agent Framework Integration Guide](https://docs.maximem.ai/integrations/microsoft-agent) +- [Dashboard](https://synap.maximem.ai) +- [PyPI: maximem-synap-microsoft-agent](https://pypi.org/project/maximem-synap-microsoft-agent/) diff --git a/python/samples/02-agents/context_providers/synap/synap_basic.py b/python/samples/02-agents/context_providers/synap/synap_basic.py new file mode 100644 index 0000000000..76e41dbabc --- /dev/null +++ b/python/samples/02-agents/context_providers/synap/synap_basic.py @@ -0,0 +1,45 @@ +# Copyright (c) Microsoft. All rights reserved. +# Demonstrates SynapContextProvider with Microsoft Agent Framework. +# Install: pip install maximem-synap-microsoft-agent +# Get API key at synap.maximem.ai + +import asyncio +import os + +from agent_framework import Agent +from maximem_synap import MaximemSynapSDK +from synap_microsoft_agent import SynapContextProvider + + +async def main() -> None: + """Example: SynapContextProvider for persistent cross-session memory.""" + sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_API_KEY"]) + + user_id = "demo-user-001" + + provider = SynapContextProvider( + sdk=sdk, + user_id=user_id, + customer_id="acme_corp", + ) + + async with Agent( + name="MemoryAssistant", + instructions="You are a helpful assistant with long-term memory.", + context_providers=[provider], + ) as agent: + # First turn — teach the agent something about the user + query = "I always prefer concise answers and I'm a software engineer." + print(f"User: {query}") + result = await agent.run(query) + print(f"Agent: {result}\n") + + # Second turn — the agent recalls from Synap + query = "How should you answer my questions?" + print(f"User: {query}") + result = await agent.run(query) + print(f"Agent: {result}\n") + + +if __name__ == "__main__": + asyncio.run(main()) From 4fcd6c1b4050632ffc8f30fd728c470f7262e7f1 Mon Sep 17 00:00:00 2001 From: visy-ani Date: Mon, 4 May 2026 15:48:00 +0530 Subject: [PATCH 2/4] fix: add FoundryChatClient, uuid user_id, asyncio.sleep, new-session recall, README setup docs --- .../context_providers/synap/README.md | 22 +++++-- .../context_providers/synap/synap_basic.py | 66 ++++++++++++------- 2 files changed, 61 insertions(+), 27 deletions(-) diff --git a/python/samples/02-agents/context_providers/synap/README.md b/python/samples/02-agents/context_providers/synap/README.md index f1d951d04a..2c6ae2d968 100644 --- a/python/samples/02-agents/context_providers/synap/README.md +++ b/python/samples/02-agents/context_providers/synap/README.md @@ -5,18 +5,32 @@ Demonstrates [SynapContextProvider](https://docs.maximem.ai/integrations/microso ## How It Works `SynapContextProvider` implements two lifecycle hooks: -- **`before_run`**: fetches Synap context relevant to the user's input and appends it to the agent's instructions via `context.extend_instructions(...)` +- **`before_run`**: fetches Synap context relevant to the user's input and appends it to the agent's instructions - **`after_run`**: records input and response messages to Synap via `sdk.conversation.record_message(...)` for future retrieval -Read failures degrade gracefully — a Synap outage never breaks the agent run. Write failures are logged but not re-raised. +Read failures degrade gracefully. Write failures are logged but never re-raised. ## Setup +**1. Install dependencies** + ```bash -pip install maximem-synap-microsoft-agent +pip install maximem-synap-microsoft-agent azure-identity python-dotenv +``` + +**2. Configure Azure credentials** + +This sample uses [Azure AI Foundry](https://ai.azure.com) as the model provider. Run `az login` to authenticate, or replace `AzureCliCredential` with your preferred credential. + +Set the following in a `.env` file or as environment variables: + ``` +AZURE_AI_FOUNDRY_PROJECT_ENDPOINT= +``` + +**3. Get a Synap API key** -Set `SYNAP_API_KEY` (get one at [synap.maximem.ai](https://synap.maximem.ai)). +Sign up at [synap.maximem.ai](https://synap.maximem.ai) and set `SYNAP_API_KEY` in your `.env`, or pass it directly to `MaximemSynapSDK(api_key=...)`. ## Run diff --git a/python/samples/02-agents/context_providers/synap/synap_basic.py b/python/samples/02-agents/context_providers/synap/synap_basic.py index 76e41dbabc..5eee28398c 100644 --- a/python/samples/02-agents/context_providers/synap/synap_basic.py +++ b/python/samples/02-agents/context_providers/synap/synap_basic.py @@ -1,44 +1,64 @@ # Copyright (c) Microsoft. All rights reserved. -# Demonstrates SynapContextProvider with Microsoft Agent Framework. -# Install: pip install maximem-synap-microsoft-agent -# Get API key at synap.maximem.ai import asyncio -import os +import uuid from agent_framework import Agent +from agent_framework.foundry import FoundryChatClient +from azure.identity.aio import AzureCliCredential +from dotenv import load_dotenv from maximem_synap import MaximemSynapSDK from synap_microsoft_agent import SynapContextProvider +# Load environment variables from .env file +load_dotenv() + async def main() -> None: - """Example: SynapContextProvider for persistent cross-session memory.""" - sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_API_KEY"]) - - user_id = "demo-user-001" - - provider = SynapContextProvider( - sdk=sdk, - user_id=user_id, - customer_id="acme_corp", - ) - - async with Agent( - name="MemoryAssistant", - instructions="You are a helpful assistant with long-term memory.", - context_providers=[provider], - ) as agent: + """Example of persistent cross-session memory with SynapContextProvider.""" + print("=== Synap Context Provider Example ===") + + # Use a stable user_id so memories persist across runs. + # In production, derive this from the authenticated user's identity. + user_id = str(uuid.uuid4()) + + sdk = MaximemSynapSDK(api_key="your-synap-api-key") # or set SYNAP_API_KEY env var + + # For Azure authentication, run `az login` or replace AzureCliCredential with + # your preferred authentication option. + async with ( + AzureCliCredential() as credential, + Agent( + client=FoundryChatClient(credential=credential), + name="MemoryAssistant", + instructions="You are a helpful assistant with long-term memory.", + context_providers=[ + SynapContextProvider( + sdk=sdk, + user_id=user_id, + customer_id="acme_corp", + ) + ], + ) as agent, + ): # First turn — teach the agent something about the user query = "I always prefer concise answers and I'm a software engineer." print(f"User: {query}") result = await agent.run(query) print(f"Agent: {result}\n") - # Second turn — the agent recalls from Synap + # Synap stores memories asynchronously. Allow time for processing + # before querying in a new session — the agent should recall preferences. + print("Waiting for Synap to process memories...") + await asyncio.sleep(5) + + # Second turn in a new session — agent recalls from Synap + print("Request within a new session:") + session = agent.create_session() query = "How should you answer my questions?" print(f"User: {query}") - result = await agent.run(query) - print(f"Agent: {result}\n") + result = await agent.run(query, session=session) + print(f"Agent: {result}") if __name__ == "__main__": From af6fb7ae9ffed9a9cde9e3a52469795dabba3d3c Mon Sep 17 00:00:00 2001 From: Anish Yadav <80835632+visy-ani@users.noreply.github.com> Date: Mon, 4 May 2026 17:05:14 +0530 Subject: [PATCH 3/4] docs(synap): add open source backlink to integration package --- python/samples/02-agents/context_providers/synap/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/python/samples/02-agents/context_providers/synap/README.md b/python/samples/02-agents/context_providers/synap/README.md index 2c6ae2d968..8ef41a4e26 100644 --- a/python/samples/02-agents/context_providers/synap/README.md +++ b/python/samples/02-agents/context_providers/synap/README.md @@ -44,3 +44,4 @@ python synap_basic.py - [Microsoft Agent Framework Integration Guide](https://docs.maximem.ai/integrations/microsoft-agent) - [Dashboard](https://synap.maximem.ai) - [PyPI: maximem-synap-microsoft-agent](https://pypi.org/project/maximem-synap-microsoft-agent/) +- [Open source integration package](https://github.com/maximem-ai/maximem_synap_sdk/tree/main/packages/integrations) From ba548ea20f7539f7aa200ec4bffdc98e41d1693e Mon Sep 17 00:00:00 2001 From: Anish Yadav <80835632+visy-ani@users.noreply.github.com> Date: Mon, 4 May 2026 23:26:06 +0530 Subject: [PATCH 4/4] fix(synap): use stable user_id for cross-session demo, use env var for API key --- .../02-agents/context_providers/synap/synap_basic.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/python/samples/02-agents/context_providers/synap/synap_basic.py b/python/samples/02-agents/context_providers/synap/synap_basic.py index 5eee28398c..6f5940c8e3 100644 --- a/python/samples/02-agents/context_providers/synap/synap_basic.py +++ b/python/samples/02-agents/context_providers/synap/synap_basic.py @@ -1,7 +1,7 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import uuid +import os from agent_framework import Agent from agent_framework.foundry import FoundryChatClient @@ -18,11 +18,11 @@ async def main() -> None: """Example of persistent cross-session memory with SynapContextProvider.""" print("=== Synap Context Provider Example ===") - # Use a stable user_id so memories persist across runs. + # Stable user_id so memories persist across runs. # In production, derive this from the authenticated user's identity. - user_id = str(uuid.uuid4()) + user_id = "demo-user-001" - sdk = MaximemSynapSDK(api_key="your-synap-api-key") # or set SYNAP_API_KEY env var + sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_API_KEY"]) # For Azure authentication, run `az login` or replace AzureCliCredential with # your preferred authentication option.