Give Your Agent Domain Knowledge

This guide shows you how to give your agent searchable knowledge graphs built from any text data using Zep’s Graph capabilities. Zep allows you to build knowledge graphs from unstructured text, JSON, or messages—including emails, Slack messages, transcripts, chunked documents, and inventory data. Unlike traditional RAG systems, Zep is designed for evolving, streaming data that continuously updates your agent’s knowledge.

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 excels at building knowledge graphs from streaming data that evolves over time. You can add any unstructured text, JSON, or message data to build your knowledge graph. 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 when you have communications with designated speakers, such as emails or chat logs. See our Adding Data to the Graph guide 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 raw text without speaker attribution, like internal documents or wiki articles. See our Adding Data to the Graph guide for details.

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 any JSON-formatted records. See our Adding Data to the Graph guide 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

See our Advanced Context Block Construction guide for complete examples, helper functions, and best practices for building custom context blocks 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 cases, refer to the Advanced Context Block Construction guide, which 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

Once you’ve retrieved the Context Block, you can include this string in your agent’s context window.

Option 1: Add context block to system prompt

You can append the context block directly to your system prompt. Note that this means the system prompt dynamically updates on every chat turn.

Option 2: Append context block as “context message”

Dynamically updating the system prompt on every chat turn has the downside of preventing prompt caching with LLM providers. In order to reap the benefits of prompt caching while still adding a new Zep context block in every chat, you can append the context block as a “context message” (technically a tool message) just after the user message in the chat history. On each new chat turn, remove the prior context message and replace it with the new one. This allows everything before the context message to be cached.

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 - Learn advanced techniques for building optimized context blocks with helper functions, BFS integration, and custom type filtering.
• Searching the graph - Explore advanced search capabilities and customizable parameters for querying your knowledge graphs.