Skip to content

Build Agents on a shared base

API onlyIntermediate~10 min

Give several Agents the same tasks, processes and know-how by keeping them once, in a base Agent, and making each of the others extend it. Each Agent then inherits everything in the base's system memory except its boot prompt, always the current version, and you write into each Agent only what it does differently. Agent inheritance explains how it works.

Today this needs a GraphQL call, which you can make with the CLI. No MCP tool sets a base yet, so you can't ask your agent to do it (hadron-server#1936), and the portal has no setting. A dedicated hadron agent set-base command is coming (hadron-cli#881); until then, the CLI's raw GraphQL command, hadron api, makes the call. Once the base is set, checking what the Agent inherited is something you can ask your agent for.

Before you start

  • You manage the child Agent. Setting its base is for whoever manages it.
  • Your organization may use the base. A base in your own organization needs nothing more, unless its grant was revoked. A base in another organization needs your organization's grant for it, and an Agent you own as a person needs your subscription to a public base.
  • You have both Agents' URNs, such as hrn:agent:acme.com:engineer. Each call also takes an Agent's id.
  • The hadron CLI is installed and signed in.

Decide what goes in the base

Put in the base what every child should share: the common tasks, the processes the whole team runs, reference nodes everyone reads. Leave in each child only what it does differently, at the same loc as the base's node it replaces. The nearest node to the child wins at a shared loc, and it replaces the base's node whole.

For example, if engineer holds tasks:open-pr, tasks:review and processes:release, and backend-engineer reviews differently, give backend-engineer its own tasks:review. It inherits the other two.

Boot prompts are never inherited, so each child keeps its own.

Set the base

hadron api 'mutation {
  setAgentBase(ref: "hrn:agent:acme.com:backend-engineer", baseRef: "hrn:agent:acme.com:engineer") {
    urn
    extendsAgentId
  }
}'

extendsAgentId comes back as the base's id. The child reads through the base from now on: nothing is copied, so a later change to the base reaches the child on its next read.

A base may have a base of its own, up to 4 Agents in a chain, counting the child. Setting the base again with another Agent changes it; the old chain's nodes drop out and the new chain's come in on the next read. The child's own nodes are never touched.

Check what it inherited

Ask your agent:

List the tasks of hrn:agent:acme.com:backend-engineer, and say which ones it inherits.

The answer lists each task once. An inherited one names the base it comes from and gives a Read through address in the child's own system memory. See See an Agent's tasks and processes.

Clear the base

Pass null as the base:

hadron api 'mutation {
  setAgentBase(ref: "hrn:agent:acme.com:backend-engineer", baseRef: null) { urn extendsAgentId }
}'

The child keeps only its own nodes. Clear the base of every live child before you retire a base: retiring an Agent that a live Agent still extends is refused with AGENT_IN_USE.

Point an Agent at its tasks and processes indexes

An Agent's task list and process list include an index's entries with their triggers: each index edge's name, the situation in which to run that task or process. To give an Agent its own indexes, name the two index nodes:

hadron api 'mutation {
  setAgentIndexRefs(
    ref: "hrn:agent:acme.com:backend-engineer"
    tasksIndexRef: "hrn:node:acme.com:backend-engineer-system:tasks"
    processesIndexRef: "hrn:node:acme.com:eng-team-shared:processes"
  ) { urn tasksIndexRef processesIndexRef }
}'
  • An argument you leave out keeps that pointer as it is; null clears it.
  • Each target is a node id or URN, and must be a node you can read.
  • The child doesn't need its own indexes to inherit: its bases' indexes still give their tasks and processes triggers, and every task in its effective system memory is listed either way.

The CLI commands for these pointers are coming (hadron-cli#874).

If it's refused

Each refusal changes nothing.

Code What it means What to do
AGENT_BASE_CYCLE The base is the child itself, or already extends it. Pick a base outside the child's own family tree.
AGENT_BASE_CHAIN_TOO_LONG A chain through this Agent, its own or one below it, would hold more than 4 Agents. Shorten a chain first, or extend an Agent nearer the top.
AGENT_ORG_GRANT_REQUIRED The base belongs to another organization, and yours has no grant for it. Ask the base's organization for a grant.
AGENT_ORG_GRANT_INACTIVE Your organization's grant for the base was revoked. Ask for the grant again; a revoked grant isn't reactivated by extending.
AGENT_SUBSCRIPTION_REQUIRED The child is yours as a person, and you don't subscribe to the base. Subscribe to the base first.
AGENT_NOT_FOUND The child or the base doesn't exist or is retired, or the base is another organization's and isn't public. Check the URN.
NODE_NOT_FOUND setAgentIndexRefs named an index node you can't read. Check the node's URN and your access to its memory.