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.
| Tool | Type | What it does |
|---|---|---|
context_graph_list_blueprints | read | Lists 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_blueprint | read | Gets one blueprint in full: its property schema and relation definitions. |
context_graph_list_entities | read | Finds 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_entity | read | Gets 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_neighborhood | read | Reads the graph around one resource: relations and label associations, up to five hops. |
context_graph_write | write | Creates or updates entities: properties, labels, relations. An update changes only what it is sent. |
context_graph_delete_entities | write | Deletes entities. Only for an agent that sets writable_blueprints. |
To give an agent read access only:
system_tools: operation_type == "read"
To let it write to the graph as well:
system_tools: operation_type == "read" || name == "context_graph_write"
Arguments
context_graph_list_blueprints
| Argument | Required | Description |
|---|---|---|
limit | No | Results per page. Default 50, maximum 100. |
offset | No | Results to skip. |
context_graph_get_blueprint
| Argument | Required | Description |
|---|---|---|
blueprint | Yes | The blueprint name, for example service. |
context_graph_list_entities
| Argument | Required | Description |
|---|---|---|
blueprint | No | The blueprint name. Omit it to search every blueprint the agent can read. |
search | No | Text to match against entity names and titles. Not case-sensitive. |
labels | No | {key: [values]}. An entity must have every key, with any of its values. An empty list matches any value. |
where | No | Property 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_to | No | {relation, blueprint, name}: only entities with that relation to that entity, for example services whose owner is team payments. |
source | No | An integration type, for example pagerduty. Returns only entities that integration contributed to. |
include | No | Property names to add to each row, relations, or all for whole entities. |
sort | No | {by, order}: by is name, updated_at or a property; order is asc or desc. |
limit | No | Results per page. Default 50, maximum 100. |
offset | No | Results to skip. |
Returns {items, total}. Each row is {id, blueprint, name, title, labels}, plus what include asks for.
context_graph_get_entity
| Argument | Required | Description |
|---|---|---|
blueprint | With name | The blueprint name. |
name | With blueprint | The entity's name. |
id | Instead of blueprint and name | The entity's ID, from a list row or a neighborhood. |
context_graph_get_neighborhood
| Argument | Required | Description |
|---|---|---|
root_kind | Yes | The kind of the starting resource: catalog_entity, skill, agent, memory, artifact, integration or run. |
root_id | Yes | The resource's ID. For an entity, use the id from context_graph_get_entity. |
depth | No | Hops from the root, 0 to 5. Default 2. |
node_kinds | No | Kinds of node to traverse. |
blueprints | No | Entity blueprints to traverse. |
edge_kinds | No | catalog_relation, label_association, or both. |
relation_keys | No | Relation keys to follow, for example owner or depends_on. |
memory_statuses | No | Memory statuses to include. Default: active only. |
branch | No | The 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.
{
"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
| Argument | Required | Description |
|---|---|---|
entities | No | Entities to create or update. Each item has blueprint and name (required), and title, properties, labels, relations and source. |
relations | No | Relations 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:
propertiesare merged into the entity's properties. A key set tonullis removed. Keys the blueprint does not declare, such asmaturity_score, are allowed and can be filtered on.labelsare merged per key. A key with an empty list is removed.relationsset exactly the targets of each key named. A key with an empty list is cleared. Other keys stay as they are.sourcerecords 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
| Argument | Required | Description |
|---|---|---|
entities | Yes | [{blueprint, name}], at most 100. |
unlink | No | Also 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.
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]
| Key | Default when omitted | Description |
|---|---|---|
blueprints | All blueprints | The blueprints the agent can read. |
writable_blueprints | None | The blueprints the agent can write. Each one must also be readable. |
resource_kinds | All kinds | The node kinds besides entities the agent can see in a neighborhood: integration, skill, agent, memory, artifact, run. Entities follow blueprints. |
edge_kinds | All kinds | The edge kinds the agent can follow: catalog_relation, label_association. |
relation_keys | All keys | The 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_graphon 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
blueprintson 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_graphon 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_writealso 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_entitiesneeds 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 acontext_graphfield cannot write from such a run. - Each node kind in a neighborhood also needs its own read permission:
integration:read,registry:readfor skills and agents,memory:readandartifact: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 writes | Result |
|---|---|
| A field or relation that no other source has set | Applied at once |
| A value that matches the current value | No change. The agent is added to the field's sources. |
| A value that conflicts with a value from an integration or a person | Not applied. A suggestion goes to the review queue. |
| A relation to an entity that does not exist yet | Kept 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:
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
| Code | HTTP | Meaning |
|---|---|---|
| 14115 | 403 | The read is outside the agent's context_graph scope. |
| 14116 | 403 | The write or delete is outside the agent's context_graph scope, or the agent sets no writable_blueprints where they are needed. |
| 14117 | 500 | The run's recorded scope could not be read. The call fails closed. |
| 14200 | 404 | The neighborhood root was not found in the project. |
| 14201 | 400 | An argument is not valid, for example depth outside 0 to 5. |
| 22405 | 422 | The run has no project. |
| 22321 | 422 | The 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.