GraphRAG in Action: A Simple Agent for Know-Your-Customer Investigations

the world of monetary providers, Know-Your-Buyer (KYC) and Anti-Cash Laundering (AML) are important protection strains in opposition to illicit actions. KYC is of course modelled as a graph drawback, the place clients, accounts, transactions, IP addresses, gadgets, and places are all interconnected nodes in an enormous community of relationships. Investigators sift by means of these complicated webs of connections, attempting to attach seemingly disparate dots to uncover fraud, sanctions violations, and cash laundering rings. 

It is a nice use case for AI grounded by a information graph (GraphRAG). The intricate net of connections requires capabilities past normal document-based RAG (sometimes based mostly on vector similarity search and reranking strategies).

Disclosure

I’m a Senior Product Manager for AI at Neo4j, the graph database featured on this submit. Though the snippets deal with Neo4j, the identical patterns may be utilized with any graph database. My important purpose 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 submit had been created by the writer.

A GraphRAG KYC Agent

This weblog submit supplies a hands-on information for AI engineers and builders on the best way to construct an preliminary KYC agent prototype with the OpenAI Agents SDK. We’ll discover the best way to equip our agent with a collection of instruments to uncover and examine potential fraud patterns.

The diagram beneath illustrates the agent processing pipeline to reply questions raised throughout a KYC investigation.

Let’s stroll by means of the foremost elements:

• The KYC Agent: It leverages the OpenAI Brokers SDK and acts because the “mind,” deciding which software to make use of based mostly on the person’s question and the dialog historical past. It performs the function of MCP Host and MCP shopper 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 conserving the dialog historical past.
• The Toolset. A group of instruments obtainable to the agent.
  • GraphRAG Instruments: These are Graph information retrieval capabilities that wrap a really particular Cypher question. For instance:
    • Get Buyer Particulars: A graph retrieval software 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 supplies three important instruments:
    1. Get Schema from the Database.
    2. Run a READ Cypher Question in opposition to the database
    3. Run a WRITE Cypher QUery in opposition to the database
  • A Textual content-To-Cypher software: A python perform wrapping a fine-tuned Gemma3-4B mannequin operating regionally by way of Ollama. The software interprets pure language questions into Cypher graph queries.
  • A Reminiscence Creation software: This software allows investigators to doc their findings straight 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.
• A KYC Information Graph: A Neo4j database storing a information graph of 8,000 fictitious clients, their accounts, transactions, gadgets and IP addresses. It’s also used because the agent’s long-term reminiscence retailer.

Need to check out the agent now? Simply observe the instructions on the project 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 can be chunked up into fragments. KYC investigations depend on discovering attention-grabbing patterns in a posh net of interconnected information – clients linked to accounts, accounts related by means of transactions, transactions tied to IP addresses and gadgets, and clients related to private and employer addresses.

Understanding these relationships is vital to uncovering refined fraud patterns.

• “Does this buyer share an IP handle with somebody on a watchlist?”
• “Is that this transaction a part of a round fee 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 gadgets are nodes and their relationships are specific edges, is the best information construction for this activity. GraphRAG (information retrieval) instruments make it easy to determine 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, gadgets and IP addresses. 

The picture beneath 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, Handle, Accounts, Gadget, IP Handle, Transactions. The principle relationships amongst them are as illustrated beneath.

The dataset accommodates just a few anomalies. Some clients are concerned in suspicious transaction rings. There are just a few remoted gadgets and IP addresses (not linked to any buyer or account). There are some addresses shared by a lot of clients. Be at liberty to discover the artificial dataset generation script, if you wish to perceive or modify the dataset to your necessities.

A Primary Agent with OpenAI Brokers SDK

Let’s stroll by means of the key components of our KYC Agent.

The implementation is usually inside kyc_agent.py. The total supply code and step-by-step directions on the best way to run the agent can be found on Github.

First, let’s outline the agent’s core id 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're additionally a Neo4j skilled and might use the Neo4j MCP server to question the graph.
If you happen to get a query concerning the KYC database that you may 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 software 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 the best way to strategy issues, particularly when a pre-defined software doesn’t match the person’s request. 

Now, let’s begin with a minimal agent. No instruments. Simply the directions.

# Agent Definition, we are going to add instruments later. 
kyc_agent = Agent(
   title="KYC Analyst",
   directions=directions,
   instruments=[...],      # We are going to populate this checklist
   mcp_servers=[...] # And this one
)

Let’s add some instruments to our KYC Agent

An agent is just nearly as good as its instruments. Let’s look at 5 instruments we’re giving our KYC analyst.

Device 1 & 2: Pre-defined Cypher Queries

For frequent and significant queries, it’s greatest to have optimized, pre-written Cypher queries wrapped in Python capabilities. You should use the @function_tool decorator from the OpenAI Agent SDK to make these capabilities obtainable to the agent.

Device 1: `find_customer_rings`

This software is designed to detect recursive patterns attribute of cash laundering, particularly ‘round transactions’ the place funds cycle by means of 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 place to begin 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 beneath reveals a find_customer_rings perform 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 carried out)
   Returns:
       dict: Accommodates 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 value noting that the documentation string (doc string) is mechanically utilized by OpenAI Brokers SDK because the software description! So good Python perform documentation pays off!.

Device 2: `get_customer_and_accounts`

A easy, but important, software 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 just like our earlier software – a perform that takes a buyer ID and wraps round a easy Cypher question. 

As soon as once more, the perform is embellished with @function_tool to make it obtainable to the agent. 

The Cypher question wrapped by this Python is proven beneath

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 acquire(t) as transactions
           
           RETURN c as buyer, a as account, transactions
           """,
           customer_id=enter.customer_id
       )

A notable facet of this software’s design is using Pydantic to specify the perform’s output. The OpenAI AgentsSDK makes use of Pydantic fashions returned by the perform to mechanically generate a textual content description of the output parameters. 

If you happen to look fastidiously, the perform 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 an inventory of latest 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 attention-grabbing powers.

A big problem in constructing versatile AI brokers is enabling them to work together dynamically with complicated information sources, past pre-defined, static capabilities. Brokers want the power to carry out general-purpose querying the place new insights would possibly require spontaneous information exploration with out requiring a priori Python wrappers for each doable motion.

This part explores a typical architectural sample to handle this. A software to translate pure language query into Cypher coupled with one other software to permit dynamic question execution.

We reveal 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 know 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 supplies the essential 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 beneath reveals how straightforward 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,
   title="Neo4j MCP Server",
)

You may study extra about how MCP is supported in OpenAI Agents SDK 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, similar 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 a neighborhood machine, we are able to flip to Ollama. Utilizing Llama.cpp, it’s comparatively simple 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-35k

What 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 an alternative 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 a neighborhood 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 software addresses the problem of Cypher question technology, however how does the agent know when to make use of this software? The reply lies within the agent directions.

It’s possible you’ll keep in mind that in the beginning 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're additionally a Neo4j skilled and might use the Neo4j MCP server to question the graph.
   If you happen to get a query concerning the KYC database that you may 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 software 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, notice the particular directions to deal with ad-hoc queries that may not be answered by the graph retrieval based mostly instruments.

When the agent goes down this path, it goes by means of following steps:

1. The agent will get a novel query.
2. It first calls `neo4j-mcp-server.get-neo4j-schema` to get the schema of the database.
3. It then feeds the schema and the person’s query to the `generate_cypher` software. This may generate a Cypher question.
4. 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 strategy will not be bullet-proof. It depends closely on the Textual content-To-Cypher mannequin to provide legitimate and proper Cypher. Most often, it really works. Nonetheless, in circumstances the place it doesn’t, it is best to contemplate:

• Defining specific Cypher retrieval instruments for such a questions.
• Including some type of finish person suggestions (thumbs up / down) in your UI/UX. This may assist flag questions that the agent is battling. You may then determine greatest strategy to deal with this class of questions. (e.g cypher retrieval software, 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 numerous consideration recently.

Whereas brokers inherently handle short-term reminiscence by means of 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 software 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: checklist[str] = [], account_ids: checklist[str] = [], transaction_ids: checklist[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 support
           MATCH (a:Account {id: support})
           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 concerns for implementing “agent reminiscence” embrace:

• Reminiscence Architectures: Exploring various kinds of reminiscence (episodic, semantic, procedural) and their frequent 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 reminiscences, enabling highly effective retrieval based mostly on relationships and patterns, somewhat than simply key phrase matching.
• Replace and Retrieval Methods: How reminiscences are up to date over time (e.g., appended, summarized, refined) and the way they’re retrieved by the agent (e.g., by means of graph traversal, semantic similarity, or fastened guidelines).
• Challenges: The complexities of managing reminiscence consistency, dealing with conflicting data, stopping ‘hallucinations’ in reminiscence retrieval, and making certain the reminiscence stays related and up-to-date with out turning into overly giant or noisy.”

That is an space of energetic growth and quickly evolving with many frameworks addressing a number of the concerns 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 happy to observe 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` software.

2. “Present me 5 watchlisted clients concerned in suspicious rings“

• Agent Motion: This straight matches the aim of our customized software. 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: It is a query that may’t be answered with any of the GraphRAG instruments. The agent ought to observe its directions:
  • It already has the schema (from our first interplay above).
  • It calls `generate_cypher` with the query and schema. The software 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` software.

4. “For the shopper whose handle is shared , are you able to get me extra particulars“

• Agent Motion: The agent determines that the `get_customer_and_accounts` software is the right match and calls it with the shopper’s ID.

5. “Write a 300-word abstract of this investigation. Retailer it as a reminiscence. Ensure to hyperlink it to each account and transaction belonging to this buyer“.

• Agent Motion: The agent first makes use of its inner LLM capabilities to generate the abstract. Then, it calls the `create_memory` software, passing the abstract textual content and the checklist of all buyer, account, and transaction IDs it has encountered throughout the dialog.

Key Takeaways

If you happen to received this far, I hope you loved the journey of getting acquainted with a fundamental implementation of a KYC GraphRAG Agent. A number 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 information retrieval as a necessary for connected-data issues. It permits brokers to reply questions on closely related information that may be not possible to reply with normal RAG.
• The significance of a balanced toolkit is highly effective. Mix MCP Server instruments with your personal optimized instruments.
• MCP Servers are a game-changer. They help you join your brokers to an rising set of MCP servers.
  • Experiment with more MCP Servers so that you get a greater sense of the probabilities.
• Brokers ought to have the ability to write again to your information retailer in a managed method. 
  • 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 total groups of investigators. 
  • The agent provides data to the information graph and it by no means updates or deletes present data. 

The patterns and instruments mentioned right here aren’t restricted to KYC. They are often utilized to produce chain evaluation, digital twin administration, drug discovery, and every other area the place the relationships between information 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 prime of OpenAI Brokers SDK with MCP, Neo4j and a Textual content-to-Cypher mannequin. All operating on a single machine.

Whereas this preliminary agent supplies a powerful basis, transitioning to a production-level system includes addressing a number of further necessities, similar to:

• Agent UI/UX: That is the central half to your customers to work together together with your agent. This may in the end be a key driver of the adoption and success of your agent.
  Lengthy operating duties and multiagent techniques: Some duties are useful however take a big 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 however it may not be appropriate for long-running brokers.
• Agent Guardrails – OpenAI Brokers SDK supplies 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 Information Graph.
• Dialog Historical past.
• Agent Observability.
• Agent Reminiscence.
• Agent Analysis – What’s the influence of fixing agent instruction and or including/eradicating a software?.
• And extra…

Within the meantime, I hope this has impressed you to continue learning and experimenting!.

Studying Assets