Give Your Agent Domain Knowledge

This guide shows you how to build a searchable Context Graph from text, JSON, or messages. The data can include email, chat messages, transcripts, document chunks, and inventory records.

Zep updates the graph as new data arrives. The Graph RAG comparison explains how this differs from static retrieval-augmented generation (RAG).

Install the Zep SDK

$
pip install zep-cloud

Initialize the Zep client

After creating a Zep account, obtaining an API key, and setting the API key as an environment variable, initialize the client once at application startup and reuse it throughout your application.

1
import os
2
from zep_cloud.client import Zep
3
4
API_KEY = os.environ.get('ZEP_API_KEY')
5
6
client = Zep(
7
    api_key=API_KEY,
8
)

Create a graph

Before adding data, you need to create a standalone graph. This gives you an independent knowledge graph that isn’t tied to individual users—useful for shared knowledge bases, domain-specific graphs, or specialized use cases.

1
from zep_cloud.client import Zep
2
3
client = Zep(
4
    api_key=API_KEY,
5
)
6
7
# Create a standalone graph with a custom ID
8
result = client.graph.create(
9
    graph_id="my_custom_graph"
10
)
11
12
print(f"Created graph with ID: {result.graph_id}")

Add streaming data to Zep

Zep builds Context Graphs from data that changes over time. You can add text, JSON, or message data. Common examples include:

• Customer support conversations (emails, chat logs, Slack messages)
• Meeting transcripts and notes
• Chunked documents and knowledge base articles
• Inventory data and business records (JSON format)
• Any ongoing communication or evolving business data

Zep supports three data types when adding data to a graph:

Message data

Use message data for communications with designated speakers, such as email or chat logs. Read Adding business data for details.

1
from zep_cloud.client import Zep
2
3
client = Zep(api_key=API_KEY)
4
5
# Add message data to a graph
6
message = "Sarah (customer): I need help configuring my API keys for production"
7
8
new_episode = client.graph.add(
9
    graph_id="customer-support",
10
    type="message",
11
    data=message
12
)

Text data

Use text data for text without speaker attribution, such as internal documents or wiki articles. Read Adding business data for details.

When you split a source into chunks, pass a document_id on every add. This value lets extraction resolve references against earlier chunks. document_id is available in the pre-release v4 SDKs. The current v3 SDKs do not include this field.

1
from zep_cloud.client import Zep
2
3
client = Zep(api_key=API_KEY)
4
5
# Add text data to a graph
6
text_data = "Production API keys must be configured with rate limiting enabled."
7
8
new_episode = client.graph.add(
9
    graph_id="company-knowledge",
10
    type="text",
11
    data=text_data
12
)

JSON data

Use JSON data for structured business data, REST API responses, or JSON records. Read Adding business data for details.

1
from zep_cloud.client import Zep
2
import json
3
4
client = Zep(api_key=API_KEY)
5
6
# Add JSON data to a graph
7
json_data = {
8
    "product": {
9
        "id": "prod_123",
10
        "name": "Enterprise Plan",
11
        "features": ["Priority Support", "Custom Integration", "99.9% SLA"],
12
        "price": 299
13
    }
14
}
15
16
new_episode = client.graph.add(
17
    graph_id="product-catalog",
18
    type="json",
19
    data=json.dumps(json_data)
20
)

Retrieve Zep context block

After adding data to your knowledge graph and before generating the AI response, you need to construct a custom context block from graph search results. Unlike user-specific context retrieval, knowledge graphs require you to manually search the graph and build the context block.

To build a custom context block, you’ll:

1. Search the graph for relevant edges (facts) and nodes (entities) using your query
2. Format the search results into a structured context block
3. Include this context block in your agent’s prompt

The Advanced Context Block construction guide shows how to build a custom block from graph search results.

Constructed context block example

Here’s a simplified example of searching a knowledge graph and building a context block:

1
from zep_cloud.client import Zep
2
3
client = Zep(api_key=API_KEY)
4
5
# Search for relevant edges (facts) and nodes (entities)
6
query = "What are the API key configuration requirements?"
7
8
edge_results = client.graph.search(
9
    graph_id="company-knowledge",
10
    query=query,
11
    scope="edges",
12
    limit=10
13
)
14
15
node_results = client.graph.search(
16
    graph_id="company-knowledge",
17
    query=query,
18
    scope="nodes",
19
    limit=5
20
)
21
22
# Build context block from results
23
facts = "\n".join([f"  - {edge.fact}" for edge in edge_results.edges])
24
entities = "\n".join([f"  - {node.name}: {node.summary}" for node in node_results.nodes])
25
26
context_block = f"""# These are relevant facts from the knowledge base
27
<FACTS>
28
{facts}
29
</FACTS>
30
31
# These are relevant entities from the knowledge base
32
<ENTITIES>
33
{entities}
34
</ENTITIES>
35
"""
36
37
print(context_block)

For production use, the Advanced Context Block construction guide includes:

• Helper functions for formatting edges and nodes
• Breadth-first search integration for recent context
• Custom entity and edge type filtering
• Temporal validity information handling
• User summary integration

Add context block to agent context window

The Context Block can contain text that came from end users, documents, tools, or other external sources. A privileged message gives that text higher instruction priority than ordinary input. Keep the Context Block out of system messages, developer messages, and other privileged instruction channels.

Follow your model provider’s documented method for separating instructions from data:

• For the OpenAI Responses API, send preloaded context through ordinary input or a user message. Use function_call_output only for the result of an actual function call.
• For the Anthropic Messages API, design retrieval as a tool call when context can contain third-party data. Return the context in a tool_result block linked to the original tool_use_id.
• For other providers, use the documented untrusted-data channel. If the provider does not define one, use an ordinary user-level message with explicit data framing.

OpenAI with preloaded context

Place the Context Block after the conversation history and before the latest user request. Everything before the block stays unchanged between turns, so this order preserves the cacheable prefix that prompt caching needs. Replace the previous turn’s block instead of appending a second one.

If the model requests memory through a function, return the Context Block as function_call_output linked to the original call_id.

OpenAI Chat Completions with tool-retrieved context

Anthropic with tool-retrieved context

Do not create a tool message for preloaded context unless the provider documents that pattern. A tool-result type must remain linked to the model’s actual tool request.

Read Memory security best practices for provider-specific mappings, write controls, action authorization, and recovery guidance.

Next steps

Now that you’ve learned how to give your agent knowledge through graph capabilities, you can explore additional features:

• Customize graph structure to your domain - Define custom entity and edge types to structure domain-specific information.
• Advanced Context Block construction - Build custom blocks with helper functions, graph traversal, and type filters.
• Searching the graph - Configure parameters for Context Graph queries.