Microsoft Agent Framework integration

Microsoft Agent Framework agents using Zep gain long-term memory backed by a temporal knowledge graph. The zep-ms-agent-framework package attaches a context provider that persists each conversation turn and injects relevant context into the model on every run.

Core benefits

• Native context-provider hook: Uses the framework’s own before_run / after_run pipeline — the same surface as its built-in memory providers
• Single round-trip: Persists the user turn and retrieves the context block in one call
• Whole-user-graph recall: Context is fused across all of a user’s threads, so a new conversation still recalls earlier facts
• Lazy resource creation: The Zep user and thread are created on first run and cached
• Graceful degradation: A Zep failure is logged but never crashes the host agent — the turn proceeds without memory

How it works

The integration ships one class, ZepContextProvider, which subclasses the framework’s ContextProvider and overrides the two lifecycle hooks called around every agent.run(...):

• before_run — extracts the latest user message, lazily creates the Zep user and thread, persists the message via thread.add_messages(return_context=True), and injects the returned context block (facts, relationships, and prior knowledge from the whole user graph) into the model’s instructions.
• after_run — reads the assistant’s reply and persists it to the same thread, so both sides of the conversation are captured.

Because context is assembled from the entire user graph, the thread only scopes relevance — an agent on a new thread still recalls facts the same user shared earlier.

Installation

$
pip install zep-ms-agent-framework

The package depends only on agent-framework-core. The example below also uses a model provider:

$
pip install zep-ms-agent-framework agent-framework-openai

Set up your environment variables:

$
export ZEP_API_KEY="your-zep-api-key"
$
export OPENAI_API_KEY="your-openai-api-key"

Usage

Attach a ZepContextProvider to an agent through the context_providers keyword argument:

1
import asyncio
2
from agent_framework import Agent
3
from agent_framework.openai import OpenAIChatClient
4
from zep_cloud.client import AsyncZep
5
from zep_ms_agent_framework import ZepContextProvider
6
7
zep = AsyncZep(api_key="your-zep-api-key")
8
9
agent = Agent(
10
    OpenAIChatClient(model="gpt-4o-mini"),
11
    instructions="You are a helpful assistant with long-term memory.",
12
    context_providers=[
13
        ZepContextProvider(
14
            zep_client=zep,
15
            user_id="user-123",
16
            thread_id="thread-abc",
17
            first_name="Jane",
18
            last_name="Smith",
19
            email="[email protected]",  # optional
20
        )
21
    ],
22
)
23
24
async def main() -> None:
25
    result = await agent.run("Hi, I'm a data scientist in Portland.")
26
    print(result.text)
27
28
asyncio.run(main())

Memory is scoped per ZepContextProvider instance to one user_id and thread_id. For a multi-user application, construct one provider per user or conversation, passing real names so Zep can resolve the user’s identity node in the graph.

Configuration options

ZepContextProvider accepts:

Per-user setup

Use on_user_created to configure per-user resources — a custom ontology, custom extraction instructions, or user summary instructions — the first time a user is created. See customizing graph structure for the available options.

Best practices

• Pass real names so Zep can anchor and resolve the user’s identity node in the graph
• One provider per user/conversation — memory is scoped to a single user_id and thread_id
• Reuse a single AsyncZep client across requests; the caller owns its lifecycle
• Allow time for indexing — Zep extracts knowledge asynchronously, so facts from a turn are not instantly retrievable

Next steps

• Explore customizing graph structure for advanced knowledge organization
• Learn about searching the graph and how to tune search
• See code examples for additional patterns