Skip to main content

Agent tools

Agents read the Context Graph to find out what they are working on: which service a pull request changes, which team owns it, which services call it, and which skills and memories apply. They write back what they learn, so the next run starts from a better graph.

The tools​

The Context Graph tools are system tools. An agent can call them when its system_tools filter keeps them. See Tools and integrations.

ToolTypeWhat it does
context_graph_list_blueprintsreadLists the blueprints the agent can read, compactly: each property's type and each relation's target. Use it first, to find which entity types and relations exist.
context_graph_get_blueprintreadGets one blueprint in full: its property schema and relation definitions.
context_graph_list_entitiesreadFinds entities, in one blueprint or all of them. Filter by labels, property values, relations, integration source, or a search on name and title.
context_graph_get_entityreadGets one entity by blueprint and name, for example blueprint service, name checkout, or by ID. Returns its properties, labels, relations and sources.
context_graph_get_neighborhoodreadReads the graph around one resource: relations and label associations, up to five hops.
context_graph_writewriteCreates or updates entities: properties, labels, relations. An update changes only what it is sent.
context_graph_delete_entitieswriteDeletes entities. Only for an agent that sets writable_blueprints.

To give an agent read access only:

YAML
system_tools: operation_type == "read"

To let it write to the graph as well:

YAML
system_tools: operation_type == "read" || name == "context_graph_write"

Arguments​

context_graph_list_blueprints

ArgumentRequiredDescription
limitNoResults per page. Default 50, maximum 100.
offsetNoResults to skip.

context_graph_get_blueprint

ArgumentRequiredDescription
blueprintYesThe blueprint name, for example service.

context_graph_list_entities

ArgumentRequiredDescription
blueprintNoThe blueprint name. Omit it to search every blueprint the agent can read.
searchNoText to match against entity names and titles. Not case-sensitive.
labelsNo{key: [values]}. An entity must have every key, with any of its values. An empty list matches any value.
whereNoProperty conditions, all of which must hold: [{property, op, value}], with op one of eq, ne, gt, gte, lt, lte, in, exists, missing. Numbers compare as numbers. Every op but missing skips entities that do not have the property.
related_toNo{relation, blueprint, name}: only entities with that relation to that entity, for example services whose owner is team payments.
sourceNoAn integration type, for example pagerduty. Returns only entities that integration contributed to.
includeNoProperty names to add to each row, relations, or all for whole entities.
sortNo{by, order}: by is name, updated_at or a property; order is asc or desc.
limitNoResults per page. Default 50, maximum 100.
offsetNoResults to skip.

Returns {items, total}. Each row is {id, blueprint, name, title, labels}, plus what include asks for.

context_graph_get_entity

ArgumentRequiredDescription
blueprintWith nameThe blueprint name.
nameWith blueprintThe entity's name.
idInstead of blueprint and nameThe entity's ID, from a list row or a neighborhood.

context_graph_get_neighborhood

ArgumentRequiredDescription
root_kindYesThe kind of the starting resource: catalog_entity, skill, agent, memory, artifact, integration or run.
root_idYesThe resource's ID. For an entity, use the id from context_graph_get_entity.
depthNoHops from the root, 0 to 5. Default 2.
node_kindsNoKinds of node to traverse.
blueprintsNoEntity blueprints to traverse.
edge_kindsNocatalog_relation, label_association, or both.
relation_keysNoRelation keys to follow, for example owner or depends_on.
memory_statusesNoMemory statuses to include. Default: active only.
branchNoThe Git branch to read skills and agents from. Default: the repository's default branch.

The filters limit the paths the traversal takes, not only what it returns. An excluded node or edge is never used as a step between two included ones. An omitted list allows everything. An empty list allows nothing.

The response has nodes and edges. Each node has a key <kind>:<id>, a name and a short metadata object. Each label-association edge carries its evidence: the label key and value that created it. Node content is not included. To read a skill or a memory, the agent uses that resource's own tool.

JSON
{
"rootKey": "catalog_entity:7f3c…",
"depth": 2,
"nodes": [
{"key": "catalog_entity:7f3c…", "kind": "catalog_entity", "name": "acme/checkout-api", "blueprint": "repository"},
{"key": "catalog_entity:a19e…", "kind": "catalog_entity", "name": "checkout", "blueprint": "service"},
{"key": "catalog_entity:0b42…", "kind": "catalog_entity", "name": "payments", "blueprint": "team"},
{"key": "skill:release-checks", "kind": "skill", "name": "release-checks"}
],
"edges": [
{"kind": "catalog_relation", "source": "catalog_entity:7f3c…", "target": "catalog_entity:a19e…", "relationKey": "part_of"},
{"kind": "catalog_relation", "source": "catalog_entity:a19e…", "target": "catalog_entity:0b42…", "relationKey": "owner"},
{"kind": "label_association", "source": "skill:release-checks", "target": "catalog_entity:a19e…",
"evidence": {"labelKey": "service", "labelValue": "checkout"}}
],
"truncation": {"truncated": false},
"unavailableSources": []
}

If truncation.truncated is true, or unavailableSources is not empty, the graph is partial. The agent is told not to present a partial graph as complete.

context_graph_write

ArgumentRequiredDescription
entitiesNoEntities to create or update. Each item has blueprint and name (required), and title, properties, labels, relations and source.
relationsNoRelations to add on their own, for relations that carry properties. Each item has source_blueprint, source_entity, relation_key and target_entity (required), and properties.

An entity that does not exist is created. For one that exists, each field changes only what it names:

  • properties are merged into the entity's properties. A key set to null is removed. Keys the blueprint does not declare, such as maturity_score, are allowed and can be filtered on.
  • labels are merged per key. A key with an empty list is removed.
  • relations set exactly the targets of each key named. A key with an empty list is cleared. Other keys stay as they are.
  • source records the integration the data came from, and replaces that integration's earlier entry.

Each item is applied whole or not at all, and items are independent. At most 100 items per call. The tool returns one result per item: created, updated, unchanged or failed, with what changed or why it failed.

context_graph_delete_entities

ArgumentRequiredDescription
entitiesYes[{blueprint, name}], at most 100.
unlinkNoAlso delete the relations other entities have to these. Default false: an entity that others point at is not deleted, and the result names them.

Only an agent that sets writable_blueprints can delete, and only in those blueprints. With unlink, every entity that points at the deleted one must also be in a writable blueprint.

Scope an agent with context_graph​

The context_graph field in agent.yaml sets which parts of the graph an agent can read and write. Set it on any agent that writes to the graph. Until November 2026 it was called enterprise_context; a push that still uses the old name fails with a diagnostic that names the new one.

YAML
name: pr-risk-review
context_graph:
blueprints: [service, team, repository, person]
writable_blueprints: [service]
resource_kinds: [skill, memory]
relation_keys: [owner, depends_on, part_of, members]
KeyDefault when omittedDescription
blueprintsAll blueprintsThe blueprints the agent can read.
writable_blueprintsNoneThe blueprints the agent can write. Each one must also be readable.
resource_kindsAll kindsThe node kinds besides entities the agent can see in a neighborhood: integration, skill, agent, memory, artifact, run. Entities follow blueprints.
edge_kindsAll kindsThe edge kinds the agent can follow: catalog_relation, label_association.
relation_keysAll keysThe relation keys the agent can follow.
  • context_graph: {} lets the agent read everything its user can read, and write nothing.
  • An empty list allows nothing. For example, resource_kinds: [] hides every node that is not an entity, so a neighborhood can start only from an entity.
  • You can set context_graph on an agent, a workflow, or one step.

Autoheal checks the field when you push the agent. An unknown key, an unknown resource or edge kind, or a writable blueprint that is not readable is an error. The version is committed with the diagnostic agent.context_graph, and its runs do not start (code 22321).

How Autoheal enforces the scope​

  • When a run starts, Autoheal reads the scope from the run's own agent definition and records it with the run.
  • Every Context Graph tool call gets the scope from the calling run. It never comes from tool arguments or from the prompt, so an instruction in a document the agent reads cannot widen it.
  • Filters the agent passes, such as blueprints on a neighborhood read, are intersected with the scope. They can make the read smaller, never larger.
  • A relation is returned only when its key is allowed and its target blueprint is readable. Relations that fail this test are removed from entity reads and blueprint definitions.
  • A subagent does not inherit its caller's scope. Set context_graph on each subagent you want to restrict.

Permissions​

A scope only makes access smaller. A run never reads or writes more than the user it runs for:

  • Every tool needs the user's permission to see blueprints and entities on the run's project. context_graph_write also needs permission to create entities (catalog:create) for an item that creates one, and to edit entities (catalog:update) for an item that changes one or adds a relation. context_graph_delete_entities needs permission to delete them.
  • A run that a trigger, Slack or a benchmark starts has no user behind it. It reads what its scope allows, and writes or deletes only in its writable_blueprints. An agent without a context_graph field cannot write from such a run.
  • Each node kind in a neighborhood also needs its own read permission: integration:read, registry:read for skills and agents, memory:read and artifact:read. A kind the user cannot read is left out of the response.
  • A run without a project reads nothing.

See the Context Graph permissions in Roles.

How agent writes work​

An agent writes as a source with its own rank, the lowest. This lets agents fill the graph as they learn, without overwriting what an integration or a person set. See Every fact has a source.

The agent writesResult
A field or relation that no other source has setApplied at once
A value that matches the current valueNo change. The agent is added to the field's sources.
A value that conflicts with a value from an integration or a personNot applied. A suggestion goes to the review queue.
A relation to an entity that does not exist yetKept as an unresolved relation. It resolves when the target appears.

More rules for writes:

  • A relation belongs to its source entity. To write one, the agent needs write scope on the source blueprint and read scope on the target blueprint.
  • An update changes only the relation keys the item names. Other relations on the entity stay as they are.
  • An agent cannot create or change the target of a relation through that relation.
  • Each write records the run that made it. The entity's Sources tab shows the run, the agent and the time for each value.

Write instructions that use the graph​

Agents use the graph better when their instructions say what to look for. For example:

MARKDOWN
Before you review the pull request:
1. Get the repository entity for this repository with context_graph_get_entity.
2. Read its neighborhood at depth 2, following part_of, owner and depends_on.
3. Name the owning team in your review, and list the services that depend on the changed service.
4. If you find that the changed code calls a service that is not in depends_on, add the relation with context_graph_write.

Error codes​

CodeHTTPMeaning
14115403The read is outside the agent's context_graph scope.
14116403The write or delete is outside the agent's context_graph scope, or the agent sets no writable_blueprints where they are needed.
14117500The run's recorded scope could not be read. The call fails closed.
14200404The neighborhood root was not found in the project.
14201400An argument is not valid, for example depth outside 0 to 5.
22405422The run has no project.
22321422The agent cannot run because it, or a skill, subagent, eval or artifact template it uses, has an error, for example because context_graph is not valid. The message names the file and the reason.

Limits​

  • A neighborhood read returns up to 500 nodes and 1,500 edges.
  • Entity and blueprint lists return up to 100 items per page.
  • Graph nodes carry metadata only. Finding a skill, memory or artifact in the graph does not let the agent load, recall or edit it. Each resource keeps its own tools and permissions.