Building a Neo4j Memory and Graph Agent for IBM watsonx Orchestrate

• 에이전트 AI

IBM watsonx Orchestrate의 상담원에게 조직 지식 그래프와 장기 기억을 제공하세요.

이 가이드에서는 Neo4j 지원 에이전트를 구축하기 위한 아키텍처 및 구현 단계를 간략하게 설명합니다.IBM watsonx Orchestrate. It covers two capabilities. First, a native Orchestrate agent that answers questions about companies, people, and investments by querying Neo4j through the Model Context Protocol (MCP), augmented with a custom Python tool. Second, a LangGraph agent imported into Orchestrate that adds long-term memory across sessions, using the Neo4j Agent Memory Service (NAMS), so Neo4j serves as both the knowledge layer and the memory layer.

You can find the full code in the Neo4j Agent Integrations repository.

Key features of this architecture

• Platform-native agents: The primary agent is a declarative Orchestrate agent. Its behavior is defined by a model, instructions, and a toolset, with no application code to host.
• Zero-infrastructure MCP: The official Neo4j MCP server runs as a local (stdio) toolkit that Orchestrate installs and executes inside its own runtime. There is no container to deploy and no public endpoint to maintain.
• 관리되는 자격 증명:Neo4j 자격 증명은 Orchestrate 연결에 저장되고 별도의 초안 및 라이브 범위와 함께 환경 변수로 MCP 서버에 삽입됩니다.
• Extensible logic: A custom Python tool is registered alongside the MCP tools, giving the agent a curated operation next to general-purpose Cypher execution.
• Cross-session memory: A LangGraph agent, imported into Orchestrate, recalls and persists facts through Neo4j Agent Memory Service (NAMS), so the agent remembers users across separate conversations.

1. Connecting Neo4j through MCP

The Model Context Protocol is an open standard for exposing tools to AI agents. Neo4j publishes an official MCP server, neo4j-mcp-서버 which exposes schema inspection and read-only Cypher execution as tools. Orchestrate can consume an MCP server either as a remote HTTP server that you host, or as a local server that it installs and runs itself. This integration uses the local option to avoid hosting entirely.

모든 구성은 Orchestrate ADK 명령줄 도구를 통해 수행됩니다. 환경이 먼저 등록됩니다.

pip install ibm-watsonx-orchestrate
orchestrate env add -n trial -u "https://api.<region>.watson-orchestrate.ibm.com/instances/<instance-id>" - activate

The API key must be generated inside the Orchestrate console under Settings → API details.

1.1 Storing credentials in a connection

Orchestrate stores tool credentials in connections and injects them at call time. For an MCP toolkit, the connection is of kind key_value, and each entry is passed to the MCP server process as an environment variable. Both the draft scope (used when Orchestrate discovers tools) and the live scope (used at runtime after deployment) are configured:

orchestrate connections add --app-id neo4j_local_creds

for env in draft live; do
  orchestrate connections configure --app-id neo4j_local_creds \
    --environment $env --kind key_value --type team
  orchestrate connections set-credentials --app-id neo4j_local_creds \
    --environment $env \
    -e "NEO4J_URI=neo4j+s://demo.neo4jlabs.com:7687" \
    -e "NEO4J_USERNAME=companies" \
    -e "NEO4J_PASSWORD=companies" \
    -e "NEO4J_DATABASE=companies" \
    -e "NEO4J_READ_ONLY=true"
done

초안 범위만 구성하는 것은 오류의 일반적인 원인입니다. 툴킷은 올바르게 가져오고 테스트한 다음 에이전트가 배포되면 작동을 멈추고 라이브 자격 증명을 사용하기 시작합니다.

1.2 MCP 서버를 툴킷으로 가져오기

단일 명령으로 서버를 등록하고 해당 도구를 반환합니다. 서버는 Python으로 실행되며, Python을 사용하면 한 단계로 설치하고 실행할 수 있습니다.

orchestrate toolkits add \
  --kind mcp \
  --name neo4j_local_mcp \
  --description "Neo4j companies knowledge graph: schema inspection and read-only Cypher" \
  --command "python -m  neo4j_mcp_server" \
  --tools "*" \
  --app-id neo4j_local_creds

하위 명령은 toolkits add입니다. 파일 기반 정의에 대한 별도의 툴킷 가져오기 명령이 존재하며 이러한 플래그를 거부합니다. 가져온 도구는 조정 도구 목록을 통해 확인할 수 있습니다.

에이전트가 사용할 수 있는 Neo4j MCP 도구

2. Adding a custom tool

This MCP server offers general purpose tools: the model composes its own Cypher. Enterprise use cases often call for a curated operation backed by a known-good query. Orchestrate supports plain Python tools, imported alongside the MCP toolkit. The following tool returns the investors backing a company. Users can define their own logic in such custom tools.

from ibm_watsonx_orchestrate.agent_builder.tools import tool
from neo4j import GraphDatabase

@tool(expected_credentials=[{"app_id": "neo4j_local_creds", "type": "key_value_creds"}])
def get_investments(company: str) -> str:
    """Look up the investors backing a company in the knowledge graph.
    Use this for any question about investors, funding, or who backed a company.

    Args:
        company (str): Name or partial name of the company.

    Returns:
        str: JSON list of investors.
    """
    query = """
    MATCH (o:Organization)-[:HAS_INVESTOR]->(i)
    WHERE toLower(o.name) CONTAINS toLower($company)
    RETURN o.name AS company,
           collect(DISTINCT i.name)[..20] AS investors
    LIMIT 5
    """
    # opens a Neo4j driver using the injected connection, runs the query,
    # and returns the rows as JSON

Two aspects of Python tools are worth noting. Dependencies are declared in a requirements.txt, installed server-side at import time, and validated against a tenant package allowlist; versions must be pinned exactly, for example neo4j==6.20.0. The first invocation after import may return a message indicating the tool is being configured in the background the dependency install after which it operates normally. The tool description and argument descriptions are extracted from the Google-style docstring and directly influence tool selection.

The tool is imported with:

orchestrate tools import -k python \
  -f tools/get_investments.py \
  -r tools/requirements.txt \
  -a neo4j_local_creds

3. Defining the agent

에이전트는 선언적 YAML 정의입니다. 그 동작은 전적으로 모델과 지침에 따라 결정됩니다.

spec_version: v1
kind: native
name: neo4j_explorer
llm: bedrock/openai.gpt-oss-120b-1:0
style: default
instructions: >
  You are a graph database assistant connected to a Neo4j knowledge graph.
  1. If you do not know the graph structure, call get-schema first.
  2. For investor or funding questions, use get_investments.
  3. Otherwise, write a Cypher query and run it with read-cypher, limited to
     20 rows.
  The database is read-only.
tools:
  - get_investments
toolkits:
  - neo4j_local_mcp

In the IBM ADK version used for this integration (2.12.0), importing a native agent that references a toolkit from the command line fails with the message “툴킷은 Experiment_customer_care 스타일 상담원에게만 지원됩니다.”The identical agent created through the Agent Builder console succeeds, which indicates a command-line validation gap rather than a platform limitation. The recommended approach is therefore to perform every step by command line and create the agent in the console.

에이전트 구성 및 MCP 도구 세트 연결

The agent can then be tested in the console. A schema question triggers the schema tool; a factual question produces a Cypher query executed through read-cypher.

그래프 도구를 선택하고 실행하는 에이전트

응답을 디버깅하여 어떤 도구가 사용되었는지 이해할 수 있습니다.

디버그 모드의 에이전트 흐름

4. LangGraph 에이전트로 장기 기억 추가

A native agent does not retain information between conversations. To give the reference agent memory that persists across sessions, watsonx Orchestrate’s ability to import a LangGraph agent is used. This deploys a code-based agent written in Python with explicit control flow into the Orchestrate runtime, and is the capability a declarative agent cannot provide.

Long-term memory is provided by the Neo4j Agent Memory Service (NAMS), a hosted service that stores what an agent learns as a knowledge graph and exposes REST endpoints to store and search it. Neo4j therefore serves as the memory layer in addition to the knowledge layer.

4.1 The agent’s control flow

The agent runs a single LangGraph node that performs three steps per turn:

1. Recall search NAMS for entities relevant to the current question and add them to the prompt as context.

2. Respond answer using that context, with the companies graph available as tools; the model queries the graph only when the question requires it.

3. Persist send the user’s message to NAMS, which extracts and stores entities in the background. These entities serve as context for agent answer.

The graph is queried only when the model chooses to call a graph tool. A question answerable from memory alone runs no neo4j graph query; a company question triggers one; a question needing both retrieves the preference from memory and adapts the neo4jgraph query accordingly.

def agent(state):
    # 1. Recall relevant facts from NAMS
    context = recall_from_memory(latest_user_message(state))

    # 2. Answer, with the companies graph exposed as tools
    system = SystemMessage(content=PROMPT.format(context=context))
    llm = ChatOpenAI(model="gpt-5.4-mini").bind_tools(graph_tools)

    working = [system] + state["messages"]
    while True:
        reply = llm.invoke(working)
        working.append(reply)
        if not reply.tool_calls:
            answer = reply.content
            break
        # execute each tool call and feed the results back to the model
        for call in reply.tool_calls:
            result = run_tool(call)
            working.append(ToolMessage(content=result, tool_call_id=call["id"]))

    # 3. Persist the user's message for background extraction
    persist_to_memory(latest_user_message(state))

    # Return exactly one plain assistant message
    return {"messages": [AIMessage(content=answer)]}

4.2 Deploying and connecting

The agent and its credentials are registered from the command line. Unlike the native agent, an imported LangGraph agent imports fully through the CLI:

orchestrate agents import --package-root memory-agent
orchestrate agents connect -n memory_agent -a nams_api -a nams_workspace -a llm_openai

Credentials for NAMS and the LLM are supplied through connections and injected into the agent at runtime, keyed as {app_id}_{credential_type}.

4.3 Demonstrating cross-session memory

Because memory is held in NAMS rather than in the agent’s own state, it persists across separate conversations. The demonstration therefore uses two sessions.

In the first session, a fact is stated: ”Remember that John is researching on opportunities in cyber security domain.”
The agent acknowledges it and persists the message. NAMS then extracts the entities in the background.

Entities extracted from the stated fact

In a new session, the agent recalls the stored preference and applies it: asked 어떤 회사를 살펴봐야 할까요?, 메모리에서 사이버 보안 선호도를 검색하고 그에 따라 필터링된 회사 그래프를 쿼리합니다.

Entity extraction in NAMS is asynchronous. A stated fact is acknowledged immediately but may take from a few seconds to a few minutes to become searchable. Cross-session recall is unaffected, since time passes between sessions, but same-turn recall of a just-stated fact is not guaranteed.

 

이 통합은 IBM watsonx Orchestrate와 함께 Neo4j를 사용하기 위한 두 가지 보완 패턴을 보여줍니다.

– 지식 계층으로 그래프를 작성합니다.선언적 Orchestrate 에이전트는 공식 MCP 서버를 통해 Neo4j 그래프를 쿼리하고, 호스팅할 인프라 없이 로컬 툴킷으로 실행되며, 엄선된 Python 도구로 확장됩니다. 자격 증명 및 도구 거버넌스는 플랫폼에서 처리됩니다.

– 메모리 계층으로 그래프를 작성합니다.가져온 LangGraph 에이전트는 Neo4j 에이전트 메모리 서비스를 통해 장기 교차 세션 메모리를 추가하고 쿼리별로 메모리, 회사 그래프 또는 둘 다를 참조할지 여부를 결정합니다.

그들은 함께 구성을 통해 Watsonx Orchestrate에서 유능하고 개인화된 그래프 에이전트를 구성할 수 있으며 코드를 큐레이트된 도구와 메모리 인식 추론 루프라는 두 위치에 추가하도록 예약할 수 있음을 보여줍니다.

전체 코드는 GitHub 저장소를 참조하세요.

• ibm-watsonx-오케스트레이트

IBM watsonx 오케스트레이션:

• IBM watsonx 오케스트레이트
• watsonx Orchestrate ADK 개발자 문서

모델 컨텍스트 프로토콜:

• Neo4j MCP 서버
• 모델 컨텍스트 프로토콜 사양

Neo4j 에이전트 메모리 서비스:

• Neo4j 에이전트 메모리

---

• 에이전트 AI
• IBM-Watsonx
• neo4j-에이전트-메모리
• watsonx-오케스트라

---

에이치시스템즈의 LogTree는 Neo4j 기반 GraphRAG 플랫폼으로, 데이터를 자동으로 지식그래프화하고 자연어 질의로 즉시 답을 제공합니다.

👉 에이치시스템즈 홈페이지