Using ArangoDB Tools in WorkingAgents

ArangoDB is a multi-model database – it handles documents, graphs, and key-value data in a single engine. When you expose ArangoDB operations as MCP tools inside WorkingAgents, AI agents gain the ability to traverse relationships, query structured documents, and perform graph lookups, all through a governed, permission-gated interface.

Why ArangoDB Fits the Agent Model

Most AI agents need to answer questions that span relationships: who knows whom, what depends on what, which entities share a common attribute. A relational database can do this with joins, but graph traversal is the natural primitive – and ArangoDB speaks both.

For WorkingAgents, this means an agent can:

• Traverse a knowledge graph to find multi-hop relationships between entities
• Fetch document collections to hydrate context before generating a response
• Execute AQL queries scoped to a specific dataset without full database access
• Combine graph edges with document payloads in a single query

Exposing ArangoDB as MCP Tools

WorkingAgents proxies tool calls through its access control layer. An ArangoDB integration follows the same pattern as any other tool module:

1. Define the tools – wrap ArangoDB operations (query, insert, traverse) as named MCP tools with typed input schemas
2. Set a permission – assign a permission key (e.g. arango_read, arango_write) to each tool group
3. Grant selectively – users or agent sessions receive only the permissions they need; a read-only agent cannot mutate collections

A typical read tool takes a collection name and an AQL query string, executes it against the local ArangoDB instance, and returns the result set. A traversal tool takes a start vertex and a traversal depth, returning the subgraph.

Access Control in Practice

Without the permission layer, any agent with network access could issue arbitrary AQL. WorkingAgents prevents this:

• The agent presents a bearer token; WorkingAgents resolves it to a user and their permission set
• The tool dispatcher checks the permission before forwarding the call to the ArangoDB wrapper
• The wrapper can apply additional query scoping (e.g. filtering by tenant ID or document type) before execution
• All calls pass through the audit log

This means the ArangoDB instance never needs to manage per-agent credentials. WorkingAgents handles identity; ArangoDB handles data.

Graph Traversal for Agent Memory

One practical use: store the agent’s working memory as a graph. Each entity (person, task, document, event) is a vertex. Relationships (assigned_to, depends_on, references) are edges. An agent that needs to understand context can traverse the graph rather than loading a flat list of records.

AQL makes this ergonomic:

FOR v, e, p IN 1..3 OUTBOUND 'tasks/123' GRAPH 'work_graph'
  FILTER v.status != 'done'
  RETURN { vertex: v, path: p }

WorkingAgents can expose this as a single MCP tool – graph_context – that takes a seed entity and returns the relevant subgraph. The agent sees a clean JSON result; the AQL and traversal depth are hidden inside the tool implementation.

Document Collections as Structured Knowledge

Beyond graphs, ArangoDB document collections work well as structured knowledge stores. An agent querying a product catalog, a contact directory, or a policy library can do so through a typed MCP tool rather than raw SQL. The tool enforces the schema, limits which fields are returned, and logs the access.

This is particularly useful when different agent roles need different views of the same collection – a support agent sees ticket history, a billing agent sees invoice records, both backed by the same ArangoDB instance but gated by different permissions in WorkingAgents.

Setup Sketch

1. Start an ArangoDB instance (local or remote)
2. Create a WorkingAgents module (ArangoTool) that wraps :arangox or a similar Elixir client
3. Define MCP tool handlers for arango_query, arango_traverse, arango_insert
4. Register the permission keys in AccessControl
5. Grant the appropriate permissions to agent users via the admin interface

The module follows the standard WorkingAgents pattern – a Server module for process lifecycle, a functional module for query execution, and use AccessControlled to tie permissions to tool dispatch.

What You Get

Agents backed by ArangoDB gain persistent, queryable memory with relationship awareness. WorkingAgents ensures they only access what they are permitted to access, every call is auditable, and the database credentials never leave the server. The agent sees tools; the infrastructure manages trust.