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 line | What it means |
|---|---|
apiVersion: agents.autoheal.ai/v1 | The current format. You fix a small number of errors, as in step 3. |
schema_version: 1 | An 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:
| Part | What it is |
|---|---|
agent.yaml, instructions.md | The 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.md | A text file that the instructions name |
catalog.yaml | Data for the marketplace page. It is not part of the agent. Do not copy it. |
Step 2: Copy the agent into your project
- CLI
- Web app
Clone the library, and copy the agent's folder into an agents/ folder:
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.
Go to Agent Studio → Agents and click Create agent. Type release-readiness as the agent name, and click Create blank. If the dialog shows only Create, click Create. The editor opens agents/release-readiness/agent.yaml. Replace its content with the library's agent.yaml.
For each other file of the folder, click New → New file at the bottom of the file tree. In Path, type the file's path under agents/release-readiness/, for example agents/release-readiness/skills/canary-coverage/SKILL.md, and click Create. Paste the file's content. Copy every file except catalog.yaml. The paths must be the same as in the library, because the agent finds its subagents and skills by path.
Do not commit yet.
Step 3: Fix the errors
- CLI
- Web app
autoheal agents validate agents/release-readiness
The editor shows the errors of the open file. Open each agent.yaml of the agent and its subagents.
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:
tools:
- operation_type: read
with these lines:
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:
| Error | Fix |
|---|---|
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 offers | Write a model from the list in the message. |
apiVersion is required | The agent uses the old schema_version: 1 format. Write it again in the current format. |
field ... is not allowed here | The field is not in the current format. The message lists the fields that you can use. |
Step 4: Push the agent
- CLI
- Web app
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.
In the Changes panel, click Commit changes, then Commit 16 files.
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.
autoheal agents show release-readiness
autoheal agents show release-readiness/canary-evidence-auditor
autoheal agents tools release-readiness
autoheal agents showgives the agent's files and its link. With--json, itsversion.dependencieslist gives each subagent, skill and eval, with its role.autoheal agents toolslists 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.mdand 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
- CLI
- Web app
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
Go to Agent Studio → Agents and open release-readiness. On the Overview tab, type the prompt below and click Start run:
This release has one change: https://github.com/autohealai/astronomy-shop-template/pull/1. Decide ship or hold.
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_clonecall and theinvoke_audit_canarycall.invoke_audit_canaryis the call to thecanary-evidence-auditorsubagent.
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 theagent.yamland the output ofautoheal agents tools. - Without a field, the agent gets every tool of its group, write tools included. If you remove
system_toolsorintegration_toolsto 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
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.