Hydra for the
age of agents
HydrAI is an opinionated companion vocabulary that makes a Hydra/JSON-LD API legible and safe for LLM agents — a conservative superset of Hydra core, with a generic client and MCP server as the reference implementation.
In one line: Hydra was designed for machines that navigate. Agents reason in examples and plan and act. HydrAI is one vocabulary you can learn in an afternoon instead of a dozen you have to assemble yourself.
Meaning doesn't have to stop with your data
Semantically grounded data is essential for safe, cost-effective, accurate AI. HydrAI is the last mile of that idea — extending the semantic layer from your data to the surface an agent acts through.
There is no mechanism in an LLM's architecture for truth — only probability. Whole classes of AI problems will not be solved by a bigger model, only by better data.
Ground the data
JSON-LD turns magic strings into terms with identity — a semantic layer over the APIs you already have, additive and non-breaking. Every term a doorway down to bedrock.
Describe the surface
Meaning doesn't stop at data. Hydra describes an API's affordances — what an agent can do and where it can go — carried in the responses themselves.
Hand agents a web
A generic agent connects with one fact — the entry-point URL — and discovers the rest. No prompt, no custom tooling. Self-describing interoperability: a web for agents.
The agent arrived after the spec did
Hydra is a beautiful piece of work built for generic hypermedia clients. An LLM agent is a different consumer with two needs Hydra never had to serve.
It learns from examples
Few-shot is how an agent orients. It wants a greeting and worked queries as data it can consume — not prose comments. Hydra carries neither.
It plans and acts
Before firing an operation, an agent wants to know whether it is reversible, expensive, or idempotent. Hydra describes an operation's method, input, and output — and stops.
These are not bugs in Hydra. They are a generational mismatch. The Hydra Community Group is dormant, so HydrAI picks up the torch — stewarding Hydra core unchanged and adding the agentic last mile on top.
A companion, not a replacement
One place to learn the whole agent-friendly hypermedia surface — and it stays domain-agnostic. HydrAI describes how to interact with an API, never what your API is about; your entities keep their own vocabulary.
Hydra-compatible
Every HydrAI document is a valid Hydra document. Additive and degradable by design.
Agent-native
Greeting, example queries, and action semantics — the affordances agents actually need.
One vocabulary
A curated @context hides Hydra, SHACL, and VoID behind one legible surface.
Untrusted by default
All server content is data, never commands. A proof upgrades attribution, not authority.
Terms an agent can actually use
A greeting — identity and stance in a few sentences, capped by a SHACL shape in the vocabulary itself so it stays a greeting, not a manual.
A worked example query — an (intent, query, endpoint) tuple the agent learns from. Executable, so a client never runs it verbatim: it is a candidate routed through the client's own query gates.
hydrai:greeting a owl:DatatypeProperty ;
rdfs:comment "Who this API is and its
cross-cutting conventions. Orientation,
not documentation." .
hydrai:GreetingShape a sh:NodeShape ;
sh:targetSubjectsOf hydrai:greeting ;
sh:property [ sh:path hydrai:greeting ;
sh:maxLength 500 ; sh:maxCount 1 ] .[] a hydrai:ExampleQuery ;
hydrai:intent "Contacts created this quarter" ;
hydrai:queryText "SELECT ?c WHERE { … }" ;
hydrai:overEndpoint <…/sparql> .The stances baked into the vocabulary
Where the standards leave a choice, HydrAI makes one, states why, and proves it in working code.
A hypermedia API is a UI for agents
The web gave humans one browser and delivered every site's capability as content. Give agents the same — driving a generic client, capability carried by the API's responses, not bespoke per-API tools.
Mint only at the gap; reuse everything else
A term enters HydrAI only when no standard says it and a real client already needs it. Every term carries a “why not the existing thing.”
Learn one vocabulary, not a dozen
A single curated context maps friendly terms to the canonical IRIs of Hydra, SHACL, VoID, and HydrAI's own additions.
Steward the orphans; reference the living
HydrAI mirrors dormant Hydra via equivalence axioms; it merely references the vocabularies that are still maintained.
Refuse, don't warn
Invalid input is rejected with an honest error, not silently coerced. A constraint that can be ignored is not a constraint.
Untrusted by default; signing is authenticity, not authority
Even a signed greeting is data, never a command. Executable examples run only through the client's own gates.
Not a committee draft — a working thing
This repository is the monorepo: the vocabulary, this site, and the example tools that consume it.
The generic agent — demo (opens in a new tab)
A generic Hydra/JSON-LD client with an agent loop. Everything it knows about an API it learns at runtime. Hosted here, runs in your browser.
⇄The MCP server →
The same runtime, embedded as a Model Context Protocol server. Drive any conformant Hydra API from Claude Code, Claude Desktop, or any MCP client.
❋The vocabulary →
Published at a neutral namespace in HTML, Turtle, and JSON-LD. Every term is a doorway into the standard behind it.
This is a community effort
HydrAI is picking up dormant community work; it aims to become community work. Issues, counter-examples, and “why not standard X instead” are exactly the contributions that make it better. Come argue with us.