Skip to main content

1. Install an Agent from the Library

In this page, you copy the Release Readiness agent from autohealai/agents into your project. The agent reads the pull requests of a release and gives a verdict: ship or hold. It uses two private subagents and two private skills, so it shows every part of a larger agent.

Step 1: Pick an agent​

Open the Agent Marketplace, or the README of autohealai/agents. Each agent is a folder in agents/ with an agent.yaml and a README.md. Open the folder of release-readiness and read its README.md.

Before you pick an agent, look at the first line of its agent.yaml:

First lineWhat it means
apiVersion: agents.autoheal.ai/v1The current format. You fix a small number of errors, as in step 3.
schema_version: 1An old format. Autoheal does not accept fields such as display_name, metadata, model_settings and capabilities. You must write the agent again in the current format.

Release Readiness uses the current format. Its folder has these parts:

PartWhat it is
agent.yaml, instructions.mdThe agent and its instructions
agents/canary-evidence-auditor/, agents/migration-safety-analyst/Two private subagents. The agent calls them as ./agents:<name>.
skills/canary-coverage/, skills/migration-reversibility/Two private skills. Only this agent and its subagents use them.
evals/Six evals that score the agent's runs
prompts/gate-report.mdA text file that the instructions name
catalog.yamlData for the marketplace page. It is not part of the agent. Do not copy it.

Step 2: Copy the agent into your project​

Clone the library, and copy the agent's folder into an agents/ folder:

BASH
git clone --depth 1 https://github.com/autohealai/agents.git autoheal-agents
mkdir -p agents
cp -R autoheal-agents/agents/release-readiness agents/release-readiness
rm agents/release-readiness/catalog.yaml

The folder name is the agent's ID in your project. Do not push yet.

Step 3: Fix the errors​

BASH
autoheal agents validate agents/release-readiness

The agent shows these errors:

agents/release-readiness:
ERROR agent.yaml /tools: tools was removed. Write system_tools and integration_tools instead; the agent docs list the filter for each old rule (agent.tools_removed)
ERROR agents/canary-evidence-auditor/agent.yaml /tools: tools was removed. Write system_tools and integration_tools instead; the agent docs list the filter for each old rule (agent.tools_removed)
ERROR agents/migration-safety-analyst/agent.yaml /tools: tools was removed. Write system_tools and integration_tools instead; the agent docs list the filter for each old rule (agent.tools_removed)

In each of the three agent.yaml files, replace these lines:

YAML
tools:
- operation_type: read

with these lines:

YAML
system_tools: operation_type == "read"
integration_tools: operation_type == "read"

Run autoheal agents validate again. The next error is about the model of one subagent:

  ERROR agents/canary-evidence-auditor/agent.yaml model/name: model "claude-haiku-4-5" is not one of the models this deployment offers; write one of: ...

The message lists the models that your organization offers. In agents/canary-evidence-auditor/agent.yaml, change name: claude-haiku-4-5 to a model from the list, for example name: claude-haiku-5-5. Run autoheal agents validate again. Make sure that the result is matches the schema.

These are the errors that library agents show most often:

ErrorFix
tools was removed (agent.tools_removed)Write system_tools and integration_tools. See Move from tools for each old rule. A rule with an integration key matched no tool, so drop it.
model "..." is not one of the models this deployment offersWrite a model from the list in the message.
apiVersion is requiredThe agent uses the old schema_version: 1 format. Write it again in the current format.
field ... is not allowed hereThe field is not in the current format. The message lists the fields that you can use.

Step 4: Push the agent​

BASH
autoheal agents push agents/release-readiness -m "Add the release-readiness agent from the library"

The push commits 16 files, then lists the tools that the agent gets. Copy the commit from the line Committed <commit> to main.

The push also resolves the references to the subagents, skills and evals. If a path is wrong, the push shows an error that names the reference.

Step 5: Find what the agent needs​

Before you run an agent from the library, find out what it reads and what it can change.

BASH
autoheal agents show release-readiness
autoheal agents show release-readiness/canary-evidence-auditor
autoheal agents tools release-readiness
  • autoheal agents show gives the agent's files and its link. With --json, its version.dependencies list gives each subagent, skill and eval, with its role.
  • autoheal agents tools lists each tool that a run can use, and the reason for each tool that it cannot use. A tool can be removed by a filter, turned off for your organization, or need an Integration Connection that the project does not have.
  • The agent's README.md and its marketplace page name the integrations that the agent expects. For Release Readiness, these are GitHub, Datadog and PagerDuty.

In the web app, open the agent in the editor and click Agent's tools in the status bar. The list is the same as autoheal agents tools.

The agent's inputs field gives the values that a run needs. Release Readiness has no inputs field, so it needs only the prompt. Its returns field gives the shape of its answer: verdict, summary, blocking_risks, advisory_risks and ship_when.

Look at what the filters allow. With operation_type == "read", the agent can read the project's Slack and the Context Graph, and it can use ask_user_input to ask you a question. It cannot write with a tool. The shell is always available, and filters do not limit it.

Step 6: Run the agent​

BASH
autoheal run release-readiness "This release has one change: https://github.com/autohealai/astronomy-shop-template/pull/1. Decide ship or hold." --commit <commit> --wait

The run takes a few minutes, because the agent calls a subagent and reads many sources. When it ends, open the run.

  • Check that the Summary tab shows a verdict, a summary and a list of advisory risks. Each risk has an owner and evidence.
  • Check that the agent reports a gate as unanswered when your project has no data for it. For example, without Datadog, the agent cannot read the error budget.
  • In the Transcript tab, find the git_clone call and the invoke_audit_canary call. invoke_audit_canary is the call to the canary-evidence-auditor subagent.

A first run often misses one problem of the example pull request. The code gives a time in milliseconds to a call that expects seconds. On the next page, you add a team rule that makes the agent look for it.

What to know​

  • A library agent is a starting point, not a product. Read its instructions before you run it. They decide what the agent does with the access that you give it.
  • The README of a library agent can be older than its agent.yaml. For example, the Release Readiness README names a Slack channel placeholder, but the agent posts nothing. Trust the agent.yaml and the output of autoheal agents tools.
  • Without a field, the agent gets every tool of its group, write tools included. If you remove system_tools or integration_tools to stop an error, you give the agent more access.
  • An agent from the library has the same subagent and skill paths as in the library. If you move a file, change the reference too.
  • The library and your project are not connected. To get a newer version, copy the files again and compare them with your version.

From the CLI​

BASH
git clone --depth 1 https://github.com/autohealai/agents.git autoheal-agents
mkdir -p agents
cp -R autoheal-agents/agents/release-readiness agents/release-readiness
rm agents/release-readiness/catalog.yaml
# fix the errors that validate shows
autoheal agents validate agents/release-readiness
autoheal agents push agents/release-readiness -m "Add the release-readiness agent from the library"
autoheal agents tools release-readiness
autoheal run release-readiness "This release has one change: https://github.com/autohealai/astronomy-shop-template/pull/1. Decide ship or hold." --commit <commit> --wait

See Subagents and See the tools an agent gets in the reference.