Skip to content

Customise an installed Agent for your App

MCPAPIIntermediate~10 min

You can keep your own version of an Agent's instructions for your App only. The Agent stays as its author published it, and no other App that uses it sees your change. You need an agent connected to Hadron over MCP, or a GraphQL client; there is no portal screen for this yet. You must manage the App: be its owner, an OWNER member, or an org or platform admin.

Your changes live in the App's install memory, a memory that belongs to one App and one Agent. It does not exist until your first change creates it.

What takes effect today

Today, saving a node stores it and reads it back. It does not yet change what the Agent does. A customisation takes effect through the boot prompt: you write the App's boot:source node, compile it into boot:compiled, and point the installed Agent at the result with a boot-prompt pointer. Compiling is merged on the server but not yet deployed, and nothing is served from a pointer yet. Until both ship, this page prepares a customisation; it does not activate one. Other nodes you write here can be pulled into the boot source with includes, and a node with the same loc as one of the Agent's replaces it when you compile.

Not run live

This page is written from the merged server code and the tool descriptions, not from a live run. The read query is served by production. The write path has not been exercised for this page.

Ask your agent to make the change

Tell your agent which App and which Agent, and what the new text should say. For example:

In the App "Support desk", customise the Agent "Juno": write the
node boot:source, with the boot-prompt role, so that it tells the Agent to greet people by first name.

Your agent writes the node into the install memory. The first write creates the memory in the same step. A write that is refused leaves nothing behind, not even an empty install memory.

Two refusals to know about:

  • AGENT_NOT_INSTALLED: the Agent is not installed in that App, so there is nothing to customise.
  • You do not manage the App: the write is refused. Someone who cannot see the App at all gets its usual not-found instead.

See what your App has customised

Ask your agent whether the App has customised the Agent. It reads the install memory and reports null if you have not customised it yet. The read never creates anything.

null also comes back if you may not see the memory's record, so it is not proof that nothing exists. See who can see it.

Who can see and change it

Act While the App is live After the App is deleted
Read the nodes The App's participants Nobody
See that the memory exists Participants and managers Managers only
Write Managers, while the Agent is still installed Nobody
Delete Managers Managers

App keys and runs are never admitted. An impersonated session can read as far as the impersonated person's participation allows, but never counts as a manager, so it cannot write or delete. The reasoning is in Memory access.

The exact calls

The MCP tools hadron_create_node and hadron_update_node take an install object. With it set, urn is only the node's loc, not a URN:

{
  "install": { "app": "<app id or URN>", "agent": "<agent id or URN>" },
  "urn": "boot:source",
  "name": "Boot source",
  "role": "boot-prompt",
  "content": "Greet people by their first name."
}

The source node must carry role: "boot-prompt". A compile refuses a source without it as BOOT_PROMPT_SOURCE_INVALID. When you ask your agent in plain words, say so: "mark it with the boot-prompt role".

install is not supported together with edges, isRunnable or abstractStillAccurate.

In GraphQL, createNode and updateNode take install: InstallTargetInput (appRef, agentRef) in place of memoryId; give exactly one of the two. The read is:

query {
  installMemory(appRef: "<app>", agentRef: "<agent>") { id urn isInstallMemory }
}

Other errors: INSTALL_MEMORY_NOT_FOUND (an update before any customisation), INSTALL_TARGET_CHANGED (the App changed owner mid-write; retry) and URN_NOT_QUALIFIED.