the world of economic companies, Know-Your-Buyer (KYC) and Anti-Cash Laundering (AML) are vital protection traces in opposition to illicit actions. KYC is of course modelled as a graph drawback, the place clients, accounts, transactions, IP addresses, units, and places are all interconnected nodes in an enormous community of relationships. Investigators sift by these complicated webs of connections, making an attempt to attach seemingly disparate dots to uncover fraud, sanctions violations, and cash laundering rings.
This can be a nice use case for AI grounded by a information graph (GraphRAG). The intricate net of connections requires capabilities past commonplace document-based RAG (sometimes primarily based on vector similarity search and reranking methods).
Disclosure
I’m a Senior Product Supervisor for AI at Neo4j, the graph database featured on this put up. Though the snippets deal with Neo4j, the identical patterns might be utilized with any graph database. My predominant goal is to share sensible steering on constructing GraphRAG brokers with the AI/ML neighborhood. All code within the linked repository is open-source and free so that you can discover, experiment with, and adapt.
All on this weblog put up have been created by the creator.
A GraphRAG KYC Agent
This weblog put up offers a hands-on information for AI engineers and builders on find out how to construct an preliminary KYC agent prototype with the OpenAI Brokers SDK. We’ll discover find out how to equip our agent with a collection of instruments to uncover and examine potential fraud patterns.
The diagram under illustrates the agent processing pipeline to reply questions raised throughout a KYC investigation.
Let’s stroll by the key parts:
- The KYC Agent: It leverages the OpenAI Brokers SDK and acts because the “mind,” deciding which instrument to make use of primarily based on the person’s question and the dialog historical past. It performs the position of MCP Host and MCP consumer to the Neo4j MCP Cypher Server. Most significantly, it runs a quite simple loop that takes a query from the person, invokes the agent, and processes the outcomes, whereas maintaining the dialog historical past.
- The Toolset. A set of instruments obtainable to the agent.
- GraphRAG Instruments: These are Graph knowledge retrieval capabilities that wrap a really particular Cypher question. For instance:
- Get Buyer Particulars: A graph retrieval instrument that given a Buyer ID, it retrieves details about a buyer, together with their accounts and up to date transaction historical past.
- Neo4j MCP Server: A Neo4j MCP Cypher Server exposing instruments to work together with a Neo4j database. It offers three important instruments:
- Get Schema from the Database.
- Run a READ Cypher Question in opposition to the database
- Run a WRITE Cypher QUery in opposition to the database
- A Textual content-To-Cypher instrument: A python operate wrapping a fine-tuned Gemma3-4B mannequin working regionally by way of Ollama. The instrument interprets pure language questions into Cypher graph queries.
- A Reminiscence Creation instrument: This instrument allows investigators to doc their findings instantly within the information graph. It creates a “reminiscence” (of an investigation) within the information graph and hyperlinks it to all related clients, transactions, and accounts. Over time, this helps construct a useful information base for future investigations.
- GraphRAG Instruments: These are Graph knowledge retrieval capabilities that wrap a really particular Cypher question. For instance:
- A KYC Data Graph: A Neo4j database storing a information graph of 8,000 fictitious clients, their accounts, transactions, units and IP addresses. It is usually used because the agent’s long-term reminiscence retailer.
Wish to check out the agent now? Simply comply with the directions on the undertaking repo. You may come again and browse how the agent was constructed later.
Why GraphRAG for KYC?
Conventional RAG techniques deal with discovering data inside giant our bodies of textual content which are chunked up into fragments. KYC investigations depend on discovering fascinating patterns in a posh net of interconnected knowledge – clients linked to accounts, accounts related by transactions, transactions tied to IP addresses and units, and clients related to private and employer addresses.
Understanding these relationships is essential to uncovering refined fraud patterns.
- “Does this buyer share an IP deal with with somebody on a watchlist?”
- “Is that this transaction a part of a round cost loop designed to obscure the supply of funds?”
- “Are a number of new accounts being opened by people working for a similar, newly-registered, shell firm?”
These are questions of connectivity. A information graph, the place clients, accounts, transactions, and units are nodes and their relationships are specific edges, is the best knowledge construction for this activity. GraphRAG (knowledge retrieval) instruments make it easy to establish uncommon patterns of exercise.
A Artificial KYC Dataset
For the needs of this weblog, I’ve created an artificial dataset with 8,000 fictitious clients and their accounts, transactions, registered addresses, units and IP addresses.
The picture under reveals the “schema” of the database after the dataset is loaded into Neo4j. In Neo4j, a schema describes the kind of entities and relationships saved within the database. In our case, the principle entities are: Buyer, Deal with, Accounts, System, IP Deal with, Transactions. The primary relationships amongst them are as illustrated under.
The dataset comprises a number of anomalies. Some clients are concerned in suspicious transaction rings. There are a number of remoted units and IP addresses (not linked to any buyer or account). There are some addresses shared by numerous clients. Be at liberty to discover the artificial dataset technology script, if you wish to perceive or modify the dataset to your necessities.
A Primary Agent with OpenAI Brokers SDK
Let’s stroll by the key components of our KYC Agent.
The implementation is generally inside kyc_agent.py. The total supply code and step-by-step directions on find out how to run the agent can be found on Github.
First, let’s outline the agent’s core identification with appropriate directions.
import os
from brokers import Agent, Runner, function_tool
# ... different imports
# Outline the directions for the agent
directions = """You're a KYC analyst with entry to a information graph. Use the instruments to reply questions on clients, accounts, and suspicious patterns.
You might be additionally a Neo4j professional and may use the Neo4j MCP server to question the graph.
For those who get a query in regards to the KYC database which you can not reply with GraphRAG instruments, it is best to
- use the Neo4j MCP server to fetch the schema of the graph (if wanted)
- use the generate_cypher instrument to generate a Cypher question from query and the schema
- use the Neo4j MCP server to question the graph to reply the query
"""The directions are essential. They set the agent’s persona and supply a high-level technique for find out how to method issues, particularly when a pre-defined instrument doesn’t match the person’s request.
Now, let’s begin with a minimal agent. No instruments. Simply the directions.
# Agent Definition, we'll add instruments later.
kyc_agent = Agent(
identify="KYC Analyst",
directions=directions,
instruments=[...], # We'll populate this listing
mcp_servers=[...] # And this one
)
Let’s add some instruments to our KYC Agent
An agent is barely pretty much as good as its instruments. Let’s study 5 instruments we’re giving our KYC analyst.
Device 1 & 2: Pre-defined Cypher Queries
For widespread and important queries, it’s finest to have optimized, pre-written Cypher queries wrapped in Python capabilities. You should utilize the @function_tool decorator from the OpenAI Agent SDK to make these capabilities obtainable to the agent.
Device 1: `find_customer_rings`
This instrument is designed to detect recursive patterns attribute of cash laundering, particularly ‘round transactions’ the place funds cycle by a number of accounts to disguise their origin.
In KYC graph, this interprets on to discovering cycles or paths that return to or close to their start line inside a directed transaction graph. Implementing such detection includes complicated graph traversal algorithms, usually using variable-length paths to discover connections as much as a sure ‘hop’ distance.
The code snippet under reveals a find_customer_rings operate that executes a Cypher Question in opposition to the KYC database and returns as much as 10 potential buyer rings. For every rings, the next data is returned: the shoppers accounts and transactions concerned in these rings.
@function_tool
def find_customer_rings(max_number_rings: int = 10, customer_in_watchlist: bool = True, ...):
"""
Detects round transaction patterns (as much as 6 hops) involving high-risk clients.
Finds account cycles the place the accounts are owned by clients matching specified
threat standards (watchlisted and/or PEP standing).
Args:
max_number_rings: Most rings to return (default: 10)
customer_in_watchlist: Filter for watchlisted clients (default: True)
customer_is_pep: Filter for PEP clients (default: False)
customer_id: Particular buyer to deal with (not applied)
Returns:
dict: Incorporates ring paths and related high-risk clients
"""
logger.data(f"TOOL: FIND_CUSTOMER_RINGS")
with driver.session() as session:
end result = session.run(
f"""
MATCH p=(a:Account)-[:FROM|TO*6]->(a:Account)
WITH p, [n IN nodes(p) WHERE n:Account] AS accounts
UNWIND accounts AS acct
MATCH (cust:Buyer)-[r:OWNS]->(acct)
WHERE cust.on_watchlist = $customer_in_watchlist
// ... extra Cypher to gather outcomes ...
""",
max_number_rings=max_number_rings,
customer_in_watchlist=customer_in_watchlist,
)
# ... Python code to course of and return outcomes ...
It’s price noting that the documentation string (doc string) is robotically utilized by OpenAI Brokers SDK because the instrument description! So good Python operate documentation pays off!.
Device 2: `get_customer_and_accounts`
A easy, but important, instrument for retrieving a buyer’s profile, together with their accounts and most up-to-date transactions. That is the bread-and-butter of any investigation. The code is much like our earlier instrument – a operate that takes a buyer ID and wraps round a easy Cypher question.
As soon as once more, the operate is embellished with @function_tool to make it obtainable to the agent.
The Cypher question wrapped by this Python is proven under
end result = session.run(
"""
MATCH (c:Buyer {id: $customer_id})-[o:OWNS]->(a:Account)
WITH c, a
CALL (c,a) FROM]->(t:Transaction)
ORDER BY t.timestamp DESC
LIMIT $tx_limit
RETURN accumulate(t) as transactions
RETURN c as buyer, a as account, transactions
""",
customer_id=enter.customer_id
)
A notable side of this instrument’s design is the usage of Pydantic to specify the operate’s output. The OpenAI AgentsSDK makes use of Pydantic fashions returned by the operate to robotically generate a textual content description of the output parameters.
For those who look rigorously, the operate returns
return CustomerAccountsOutput(
buyer=CustomerModel(**buyer),
accounts=[AccountModel(**a) for a in accounts],
)
The CustomerModel and AccountModel embrace every of the properties returned for every Buyer, its accounts and a listing of current transactions. You may see their definition in schemas.py.
Instruments 3 & 4: The place Neo4j MCP Server meets Textual content-To-Cypher
That is the place our KYC agent will get some extra fascinating powers.
A big problem in constructing versatile AI brokers is enabling them to work together dynamically with complicated knowledge sources, past pre-defined, static capabilities. Brokers want the power to carry out general-purpose querying the place new insights would possibly require spontaneous knowledge exploration with out requiring a priori Python wrappers for each doable motion.
This part explores a standard architectural sample to deal with this. A instrument to translate pure language query into Cypher coupled with one other instrument to permit dynamic question execution.
We exhibit this mechanism utilizing the Neo4 MCP Server to show dynamic graph question execution and a Google Gemma3-4B fine-tuned mannequin for Textual content-to-Cypher translation.
Device 3: Including the Neo4j MCP server toolset
For a sturdy agent to function successfully with a information graph, it wants to grasp the graph’s construction and to execute Cypher queries. These capabilities allow the agent to introspect the information and execute dynamic ad-hoc queries.
The MCP Neo4j Cypher server offers the fundamental instruments: get-neo4j-schema (to retrieve graph schema dynamically), read-neo4j-cypher (for executing arbitrary learn queries), and write-neo4j-cypher (for create, replace, delete queries).
Thankfully, the OpenAI Brokers SDK has assist for MCP. The code snippet under reveals how simple it’s so as to add the Neo4j MCP Server to our KYC Agent.
# Device 3: Neo4j MCP server setup
neo4j_mcp_server = MCPServerStdio(
params={
"command": "uvx",
"args": ["[email protected]"],
"env": {
"NEO4J_URI": NEO4J_URI,
"NEO4J_USERNAME": NEO4J_USER,
"NEO4J_PASSWORD": NEO4J_PASSWORD,
"NEO4J_DATABASE": NEO4J_DATABASE,
},
},
cache_tools_list=True,
identify="Neo4j MCP Server",
)
You may study extra about how MCP is supported in OpenAI Brokers SDK right here.
Device 4: A Textual content-To-Cypher Device
The flexibility to dynamically translate pure language into highly effective graph queries usually depends on specialised Massive Language Fashions (LLMs) – finetuned with schema-aware question technology.
We will use open weights, publicly obtainable Textual content-to-Cypher fashions obtainable on Huggingface, akin to neo4j/text-to-cypher-Gemma-3-4B-Instruct-2025.04.0. This mannequin was particularly finetuned to generate correct Cypher queries from person query and a schema.
With a view to run this mannequin on an area machine, we are able to flip to Ollama. Utilizing Llama.cpp, it’s comparatively easy to transform any HuggingFace fashions to GGUF format, which is required to run a mannequin in Ollama. Utilizing the ‘convert-hf-to-GGUF’ python script, I generated a GGUF model of the Gemma3-4B finetuned mannequin and uploaded it to Ollama.
In case you are an Ollama person, you possibly can obtain this mannequin to your native machine with:
ollama pull ed-neo4j/t2c-gemma3-4b-it-q8_0-35kWhat occurs when a person asks a query that doesn’t match any of our pre-defined instruments?
For instance, “For buyer CUST_00001, discover his addresses and verify if they’re shared with different clients”
As a substitute of failing, our agent can generate a Cypher question on the fly…
@function_tool
async def generate_cypher(request: GenerateCypherRequest) -> str:
"""
Generate a Cypher question from pure language utilizing an area finetuned text2cypher Ollama mannequin
"""
USER_INSTRUCTION = """...""" # Detailed immediate directions
user_message = USER_INSTRUCTION.format(
schema=request.database_schema,
query=request.query
)
# Generate Cypher question utilizing the text2cypher mannequin
mannequin: str = "ed-neo4j/t2c-gemma3-4b-it-q8_0-35k"
response = await chat(
mannequin=mannequin,
messages=[{"role": "user", "content": user_message}]
)
return response['message']['content']
The generate_cypher instrument addresses the problem of Cypher question technology, however how does the agent know when to make use of this instrument? The reply lies within the agent directions.
It’s possible you’ll do not forget that firstly of the weblog, we outlined the directions for the agent as follows:
directions = """You're a KYC analyst with entry to a information graph. Use the instruments to reply questions on clients, accounts, and suspicious patterns.
You might be additionally a Neo4j professional and may use the Neo4j MCP server to question the graph.
For those who get a query in regards to the KYC database which you can not reply with GraphRAG instruments, it is best to
- use the Neo4j MCP server to get the schema of the graph (if wanted)
- use the generate_cypher instrument to generate a Cypher question from query and the schema
- use the Neo4j MCP server to question the graph to reply the query
"""
This time, observe the particular directions to deal with ad-hoc queries that may not be answered by the graph retrieval primarily based instruments.
When the agent goes down this path, it goes by following steps:
- The agent will get a novel query.
- It first calls `neo4j-mcp-server.get-neo4j-schema` to get the schema of the database.
- It then feeds the schema and the person’s query to the `generate_cypher` instrument. This can generate a Cypher question.
- Lastly, it takes the generated Cypher question and run it utilizing `neo4j-mcp-server.read-neo4j-cypher`.
If there are errors, in both the cypher technology or the execution of the cypher, the agent retries to generate Cypher and rerun it.
As you possibly can see, the above method isn’t bullet-proof. It depends closely on the Textual content-To-Cypher mannequin to provide legitimate and proper Cypher. Generally, it really works. Nevertheless, in circumstances the place it doesn’t, it is best to think about:
- Defining specific Cypher retrieval instruments for the sort of questions.
- Including some type of finish person suggestions (thumbs up / down) in your UI/UX. This can assist flag questions that the agent is battling. You may then resolve finest method to deal with this class of questions. (e.g cypher retrieval instrument, higher directions, enchancment to text2cypher mannequin, guardrails or simply get your agent to politely decline to reply the query).
Device 5 – Including Reminiscence to the KYC Agent
The subject of agent reminiscence is getting plenty of consideration recently.
Whereas brokers inherently handle short-term reminiscence by conversational historical past, complicated, multi-session duties like monetary investigations demand a extra persistent and evolving long-term reminiscence.
This long-term reminiscence isn’t only a log of previous interactions; it’s a dynamic information base that may accumulate insights, observe ongoing investigations, and supply context throughout completely different periods and even completely different brokers.
The create_memory instrument implements a type of specific information graph reminiscence, the place summaries of investigations are saved as devoted nodes and explicitly linked to related entities (clients, accounts, transactions).
@function_tool
def create_memory(content material: str, customer_ids: listing[str] = [], account_ids: listing[str] = [], transaction_ids: listing[str] = []) -> str:
"""
Create a Reminiscence node and hyperlink it to specified clients, accounts, and transactions
"""
logger.data(f"TOOL: CREATE_MEMORY")
with driver.session() as session:
end result = session.run(
"""
CREATE (m:Reminiscence {content material: $content material, created_at: datetime()})
WITH m
UNWIND $customer_ids as cid
MATCH (c:Buyer {id: cid})
MERGE (m)-[:FOR_CUSTOMER]->(c)
WITH m
UNWIND $account_ids as assist
MATCH (a:Account {id: assist})
MERGE (m)-[:FOR_ACCOUNT]->(a)
WITH m
UNWIND $transaction_ids as tid
MATCH (t:Transaction {id: tid})
MERGE (m)-[:FOR_TRANSACTION]->(t)
RETURN m.content material as content material
""",
content material=content material,
customer_ids=customer_ids,
account_ids=account_ids,
transaction_ids=transaction_ids
# ...
)Further issues for implementing “agent reminiscence” embrace:
- Reminiscence Architectures: Exploring various kinds of reminiscence (episodic, semantic, procedural) and their widespread implementations (vector databases for semantic search, relational databases, or information graphs for structured insights).
- Contextualization: How the information graph construction permits for wealthy contextualization of recollections, enabling highly effective retrieval primarily based on relationships and patterns, fairly than simply key phrase matching.
- Replace and Retrieval Methods: How recollections are up to date over time (e.g., appended, summarized, refined) and the way they’re retrieved by the agent (e.g., by graph traversal, semantic similarity, or mounted guidelines).
- Challenges: The complexities of managing reminiscence consistency, dealing with conflicting data, stopping ‘hallucinations’ in reminiscence retrieval, and guaranteeing the reminiscence stays related and up-to-date with out turning into overly giant or noisy.”
That is an space of lively growth and quickly evolving with many frameworks addressing a few of the issues above.
Placing all of it collectively – An Instance Investigation
Let’s see how our agent handles a typical workflow. You may run this your self (or be at liberty to comply with alongside step-by-step directions on the KYC agent github repo)
1. “Get me the schema of the database“
- Agent Motion: The agent identifies this as a schema question and makes use of the Neo4j MCP Server’s `get-neo4j-schema` instrument.
2. “Present me 5 watchlisted clients concerned in suspicious rings“
- Agent Motion: This instantly matches the aim of our customized instrument. The agent calls `find_customer_rings` with `customer_in_watchlist=True`.
3. “For every of those clients, discover their addresses and discover out if they’re shared with different clients“.
- Agent Motion: This can be a query that may’t be answered with any of the GraphRAG instruments. The agent ought to comply with its directions:
- It already has the schema (from our first interplay above).
- It calls `generate_cypher` with the query and schema. The instrument returns a Cypher question that tries to reply the investigator’s query.
- It executes this Cypher question utilizing the Neo4j MCP Cypher Server `read-neo4j-cypher` instrument.
4. “For the shopper whose deal with is shared , are you able to get me extra particulars“
- Agent Motion: The agent determines that the `get_customer_and_accounts` instrument is the proper match and calls it with the shopper’s ID.
5. “Write a 300-word abstract of this investigation. Retailer it as a reminiscence. Be certain that to hyperlink it to each account and transaction belonging to this buyer“.
- Agent Motion: The agent first makes use of its inside LLM capabilities to generate the abstract. Then, it calls the `create_memory` instrument, passing the abstract textual content and the listing of all buyer, account, and transaction IDs it has encountered in the course of the dialog.
Key Takeaways
For those who acquired this far, I hope you loved the journey of getting acquainted with a fundamental implementation of a KYC GraphRAG Agent. Plenty of cool applied sciences right here: OpenAI Agent SDK, MCP, Neo4j, Ollama and a Gemma3-4B finetuned Textual content-To-Cypher mannequin!
I hope you gained some appreciation for:
- GraphRAG, or extra particularly Graph-powered knowledge retrieval as an important for connected-data issues. It permits brokers to reply questions on closely related knowledge that will be inconceivable to reply with commonplace RAG.
- The significance of a balanced toolkit is highly effective. Mix MCP Server instruments with your individual optimized instruments.
- MCP Servers are a game-changer. They let you join your brokers to an growing set of MCP servers.
- Experiment with extra MCP Servers so that you get a greater sense of the probabilities.
- Brokers ought to have the ability to write again to your knowledge retailer in a managed means.
- In our instance we noticed how an analyst can persist its findings (e.g., including Reminiscence nodes to the knowlege graph) and within the course of making a virtuous cycle the place the agent improves the underlying information base for whole groups of investigators.
- The agent provides data to the information graph and it by no means updates or deletes current data.
The patterns and instruments mentioned right here are usually not restricted to KYC. They are often utilized to provide chain evaluation, digital twin administration, drug discovery, and every other area the place the relationships between knowledge factors are as vital as the information itself.
The period of graph-aware AI brokers is right here.
What’s Subsequent?
You’ve got constructed a easy AI agent on high of OpenAI Brokers SDK with MCP, Neo4j and a Textual content-to-Cypher mannequin. All working on a single machine.
Whereas this preliminary agent offers a robust basis, transitioning to a production-level system includes addressing a number of extra necessities, akin to:
- Agent UI/UX: That is the central half on your customers to work together together with your agent. This can in the end be a key driver of the adoption and success of your agent.
Lengthy working duties and multiagent techniques: Some duties are priceless however take a major period of time to run. In these circumstances, brokers ought to have the ability to offload components of their workload to different brokers.- OpenAI does present some assist for handing off to subagents nevertheless it may not be appropriate for long-running brokers.
- Agent Guardrails – OpenAI Brokers SDK offers some assist for Guardrails.
- Agent Internet hosting – It exposes your agent to your customers.
- Securing comms to your agent – Finish person authentication and authorization to your agent.
- Database entry controls – Managing entry management to the information saved within the KYC Data Graph.
- Dialog Historical past.
- Agent Observability.
- Agent Reminiscence.
- Agent Analysis – What’s the affect of fixing agent instruction and or including/eradicating a instrument?.
- And extra…
Within the meantime, I hope this has impressed you to continue to learn and experimenting!.
