3. Use the Graph in an Agent
In this page, the PR Review agent reads the graph from page 2. Each review then starts with a "Context" section: the changed service, its owner team, the services that it calls, and the services that call it.
Step 1: Check that the agent has the Context Graph tools
The Context Graph tools are system tools. Five of them only read, so the system_tools: operation_type == "read" filter from chapter 4 keeps them:
| Tool | What it does |
|---|---|
context_graph_list_blueprints | Lists the blueprints, with their properties and relations. |
context_graph_get_blueprint | Gets one blueprint in full. |
context_graph_list_entities | Finds entities by blueprint, text, labels, properties and relations. |
context_graph_get_entity | Gets one entity by blueprint and name, or by id. |
context_graph_get_neighborhood | Gets the nodes and edges around one node, up to 5 hops. |
The filter removes the two write tools, context_graph_write and context_graph_delete_entities.
Run autoheal agents tools pr-review. Check that the five read tools have the status available.
Step 2: Tell the agent to read the graph
A tool alone does not change what the agent does. The instructions must say when to use it. Replace the content of instructions.md with this:
You review one pull request on GitHub.
1. The prompt has the pull request URL. Clone the repository with the `git_clone` tool. Give it the repository's https URL and the ref `pull/<number>/head`.
2. In the clone, compare the pull request with the default branch: `git diff origin/HEAD...HEAD`.
3. Read the changed files in full, not only the diff.
4. Find the context of the change in the Context Graph. See "Context" below.
5. Write a verdict: merge, merge with changes, or do not merge.
6. Name the riskiest change, with its file and line.
7. Ask the author one question.
## Context
Each folder under `src/` is one service.
1. Take the folder names from the paths of the changed files.
2. For each folder, call `context_graph_list_entities` with blueprint `service`, the folder name as `search`, and `include: ["relations"]`.
3. Call `context_graph_get_neighborhood` with root kind `catalog_entity`, the `id` of the service, and depth 1.
4. Start the review with a section named "Context". Give the service, its owner team, the services that it depends on, and the services that depend on it.
An edge with `relationKey: depends_on` goes from the service that calls to the service that it calls.
If the Context Graph does not have the service, say so in the "Context" section. Do not guess an owner.
Look hardest at the `focus` input. For `correctness`, look for bugs and errors that the code does not handle. For `security`, look for secrets, unsafe input and permissions. For `tests`, say what the tests do not cover.
If the `post_comment` input is true, post the review as one comment on the pull request with `gh pr comment <URL> --body-file <file>`. If it is false, do not comment.
Do not push, approve, merge or close anything.
The entity of a service has its owner and the services that it depends on. The services that depend on it are not on the entity: they point at it. Only the neighborhood shows them. This is why step 3 of "Context" reads the neighborhood.
Step 3: Limit what the agent reads
Add these lines to agent.yaml:
context_graph:
blueprints: [service, team]
relation_keys: [owner, depends_on]
The context_graph field makes the agent's access to the graph smaller. This agent can read only services and teams, and follow only owner and depends_on relations. A read of another blueprint fails, for example: Blueprint "person" is outside this agent's declared Context Graph read scope. The agent writes nothing to the graph, because the field has no writable_blueprints.
Step 4: Link the agent to its team with a label
Add a label to agent.yaml, below icon:
labels:
- team: shop-backend
The key team is the name of a blueprint, and shop-backend is the name of a team entity. So the label links the agent to the team in the graph. A label never changes what the agent does. It only helps people and agents find the agent from the team.
Commit your changes. Then read the team's neighborhood:
autoheal context-graph nodes --search shop-backend
autoheal context-graph neighborhood --root-kind catalog_entity --root-id <id> --depth 1
Check that the output has a node of kind agent for pr-review, and an edge of kind label_association with the evidence {"labelKey": "team", "labelValue": "shop-backend"}.
Step 5: Run the agent on the example pull request
On the agent's Overview tab, paste https://github.com/autohealai/astronomy-shop-template/pull/1 and click Start run. Keep post_comment off.
When the run ends, read the Summary. Check that the review starts with a "Context" section like this:
- Service: Recommendation (
recommendation) - Owner team: Shop Backend (
shop-backend) - Depends on: Product Catalog (
product-catalog) - Depended on by: Frontend (
frontend)
Open the Transcript. Find the context_graph_list_entities call with "search": "recommendation", and the context_graph_get_neighborhood call after it.
The pull request adds a timeout to the call to the product catalog. With the graph, the review can say who sees the effect of a wrong timeout: the frontend, because it calls the recommendation service.
The git_clone tool and the Context Graph
Agents also have the git_clone tool. It clones a repository into /workspace/git-repos/ and returns the folder. You name the repository by its full name (owner/repo) or by its https URL. The two forms do not always work the same:
- The https URL always works. A public repository needs no Integration Connection.
- The full name works when the repository is in the Context Graph. It must be a repository entity that a code integration (GitHub, GitLab, Bitbucket or Azure DevOps) imported, with a clone URL. A repository entity that you add by hand does not count.
- The full name also works when the project has Integration Connections for exactly one git host, for example only GitHub. Autoheal then clones the repository from that host.
In a project with no code integration, git_clone with autohealai/astronomy-shop-template fails with this message:
"autohealai/astronomy-shop-template" is not in the project's catalog. Look up a repository's full name in the catalog's repository entities: each one's title is its full name. To clone a repository that is not in the catalog, pass its https URL.
The same call with https://github.com/autohealai/astronomy-shop-template clones the repository. So, in instructions, tell the agent to use the https URL unless you know that the repository is in the graph.
What to know
context_graph: {}lets the agent read everything that its user can read, and write nothing. An omitted list allows everything. An empty list ([]) allows nothing.- A run reads only what its user can read. A run that a trigger starts has no user, and it reads what its
context_graphscope allows. - To let an agent write to the graph, add
|| name == "context_graph_write"tosystem_tools, and list the blueprints incontext_graph.writable_blueprints. Start with read only. - A subagent does not get its caller's
context_graphscope. Set the field on each subagent. - A skill uses the same labels in its
SKILL.mdfrontmatter. A skill with the labelservice: recommendationlinks to that service. See Label associations. - The graph tells the agent what exists. Tools and the shell read the live systems. Keep facts in the graph and procedures in skills.
From the CLI
autoheal agents tools pr-review
autoheal agents push agents/pr-review -m "Read the Context Graph"
autoheal run pr-review "https://github.com/autohealai/astronomy-shop-template/pull/1" --follow
See Agent tools and Context Graph tools in the reference.