Domain Graph Protocol
An agent-first protocol for exposing business domains as unified, queryable graphs
DGP enables AI agents to discover, query, and act on business domains through semantic graphs. Queries traverse relationships in a single call. Mutations orchestrate multi-step operations with automatic rollback. The agent gets domain understanding and domain control—not just a bag of tools.
Think of it as GraphQL redesigned for agent consumers instead of human developers—compressed discovery, semantic state machines, and orchestrated mutations with compensation.
v0.9.0 — Production-ready with 1048 tests passing
DGP and MCP
DGP handles both queries and orchestrated actions. MCP is the compatibility layer that lets agents reach DGP from any client that speaks MCP—Claude Desktop, Claude Code, Cursor, Codex, or anything else.
MCP
Universal Agent Transport
- Ubiquitous—Claude Desktop, Claude Code, Cursor, Codex, Windsurf all speak it
- Great for single-step, fire-and-forget actions
- No transaction semantics, no rollback
- DGP gateways expose MCP endpoints for compatibility
DGP
Domain Understanding + Control
- Queries with relationship traversal and federation
- Orchestrated mutations with declared compensation
- State machines, provenance, cost transparency
- Speaks MCP on the wire—agents don't need a new client
A DGP Gateway as an MCP Server
# Agent connects via MCP, DGP handles everything
# 1. Discover the domain (800 tokens)
schema(task: "find overdue customers")
# 2. Query with relationship traversal
query(entity: "Customer",
where: {"lifetime_value": {"gte": 1000}},
include: {"orders": {"where": {"status": "overdue"}}})
# 3. Orchestrated mutation with rollback
# Sends reminder + updates state, rolls back on failure
mutation(operation: "send_overdue_reminder",
input: {customer_id: "cust_123"})The agent speaks MCP. The gateway speaks DGP. Three tool calls replace what would be five separate MCP tools with no shared context, no relationship awareness, and no rollback.
What a Domain Graph Gives Agents
Domain Model
Entities with semantic meaning. Customer, Order, Zone—the agent understands the domain, not just a list of function signatures.
Relationships
First-class edges and traversal. One query fetches Customer → Orders → LineItems → Products. No N+1 round trips.
Orchestrated Mutations
Multi-step operations with declared compensation. If step 3 fails, steps 1 and 2 roll back. The gateway owns the transaction.
State Machines
Entity lifecycles defined in schema. Order: draft → pending → confirmed → shipped → delivered. Agents know what transitions are valid.
Cross-Source Federation
Transparent joins across Postgres, Stripe, HubSpot, or any API. Application boundaries are implementation details the agent never sees.
Cost & Provenance
Every response includes data sources, freshness, and cost. Agents optimize queries under budget constraints and know where their data came from.
Compressed Schema Notation (CSN)
While Tool Search defers tool loading, CSN provides domain understanding—the semantic context that lets agents reason about your business, not just call your tools. 75-90% token reduction compared to JSON Schema.
JSON Schema (~3500 tokens)
{
"Customer": {
"description": "...",
"attributes": {
"id": {"type": "uuid", ...},
"email": {"type": "email", ...},
"lifetime_value": {
"type": "decimal",
"computed": true,
"formula": "sum(orders.total)"
}
},
"edges": {...}
}
}CSN Format (~900 tokens)
Customer "A purchasing entity"
id : uuid! @key
email : email! @unique @indexed
name : string!
lifetime_value : decimal
@computed(sum:orders.total)
@freshness(1h)
->* orders : Order @inverse(customer)
<-1 customer : Order @inverse(orders)CSN enables agents to understand domain structure—relationships, constraints, state machines—within limited context windows.
Example Query
Query the graph using JSON with semantic filtering and relationship traversal:
{
"query": {
"entity": "Customer",
"where": {
"lifecycle_stage": {"eq": "customer"},
"lifetime_value": {"gte": 1000}
},
"include": {
"orders": {
"where": {"status": {"in": ["confirmed", "shipped"]}},
"limit": 5,
"include": {
"line_items": {"include": {"product": ["name", "price"]}},
"payment": ["status", "amount"]
}
}
},
"aggregate": {
"total_orders": {"count": "orders"},
"total_revenue": {"sum": "orders.total"}
},
"limit": 10
}
}One query traverses Customer → Orders → LineItems → Products, aggregates data, and returns structured results with provenance metadata. Try that with sequential MCP tool calls.
Getting Started
Read the Spec
Understand the protocol design, query language, and mutation patterns.
View Specification →Python Implementation
The official reference implementation provides a complete toolkit for building DGP-powered applications.
pip install dgp-python
Query Builder
from dgp import SchemaLoader, query
# Load a domain schema
schema = SchemaLoader.from_json_file("ecommerce.json")
# Build a query using fluent API
customer_query = (
query("Customer")
.where("email", eq="user@example.com")
.include("orders",
lambda q: q
.limit(10)
.order_by("created_at", "desc")
)
.computed(["lifetime_value"])
.build()
)Production-Ready Gateway
Rate limiting, circuit breakers, retries, caching, timeouts, and Prometheus metrics built-in.
Async Support
Full async/await support for high-concurrency agent workloads.
Adapter Ecosystem
Mock, PostgreSQL, Redis, and generic API adapters included.
1048 Tests Passing
Comprehensive test coverage across all protocol features.
Use Cases
- Agent Orchestration: Coordinate multiple AI agents with shared state and capability discovery
- Workflow Automation: Build durable, observable workflows with full provenance tracking
- Knowledge Graphs: Expose domain knowledge for semantic search and reasoning
- Multi-Agent Systems: Enable agents to discover and invoke each other's capabilities
- Cost-Aware AI: Build budget-conscious applications with transparent token accounting
Works With
Atomic Knowledge Graph (AKG)
DGP is designed as the access protocol for AKG. The atom types queried through DGP (SkillAtom, ToolAtom, TaskAtom, etc.) are defined by the AKG specification, which organizes 23 atom types across five AEONS domains for AI agent orchestration.
Learn about AKG →MCP (Model Context Protocol)
DGP gateways expose themselves as MCP servers. Agents connect using any MCP client and get domain understanding and orchestrated actions—no new transport, no new client library. MCP is the wire protocol. DGP is what makes the tools smart.
Any Backend
DGP doesn't require a graph database—or any database. A gateway can put a domain graph in front of a plain REST API. The graph lives in the schema, not the backing store. Works with REST APIs, PostgreSQL, Neo4j, FalkorDB, or anything an adapter can talk to.