Cypher Agent

The SQLAgent (Code Example) answers questions over a tabular knowledge base. The Cypher Agent is its graph counterpart: it answers questions over a knowledge graph (nodes and edges) by writing read-only Cypher queries.

synalinks.CypherAgent is a thin specialization of FunctionCallingAgent that pre-wires three tools, all bound to a KnowledgeBase with a graph adapter:

Tool	Purpose
`get_graph_schema()`	List every node and relation label with their properties.
`get_node_sample(label, limit, offset)`	Fetch a few nodes of a label to see the data shape. Page-bounded by the agent's `k`.
`run_cypher_query(cypher_query)`	Execute a read-only `MATCH ... RETURN` query. Result sets are capped at `k` rows.

The user asks a question in natural language; the agent discovers the schema, writes Cypher, runs it, and summarizes the rows.

When do you want one?

Graphs shine when the answer follows relationships: friend-of-friend, shortest path, "which X connects to Y through Z". Those are multi-hop traversals that an SQL agent would express as a chain of self-joins. With a graph, the same question is a single MATCH pattern:

MATCH (a:Person {name: 'Alice'})-[:Knows]->(p:Person)-[:LivesIn]->(c:City {name: 'Paris'})
RETURN p.name

Safety

Only read-only Cypher runs. The graph adapter scans the query and rejects any write/admin keyword (CREATE, MERGE, SET, DELETE, DETACH, REMOVE, DROP, ALTER, COPY, INSTALL, LOAD), so an LM can explore the graph but never mutate it.

API References

Source

--8 < --"examples/23_cypher_agent.py:source"

Run log

The log below is the unedited combined output of running the example above with local models (ollama).

Full run log: examples/23_cypher_agent.log

Answer: The person that Alice knows who lives in Paris is Bob.
Cypher: MATCH (alice:Person)-[:Knows]->(person:Person)-[:LivesIn]->(city:City) WHERE alice.name = 'Alice' AND city.name = 'Paris' RETURN person.name