2. Put a Person in the Loop
An agent can stop and wait for a person in two ways:
- A question. The agent calls the
ask_user_inputtool. The run waits until a person answers or skips the question. - An approval. An agent policy matches a tool call. The call does not run until a person allows it or rejects it.
On this page, you make the agent ask a question in the project where your pr-review agent is (step 1). Then you make a policy in the practice project from page 1 (steps 2 to 5). For step 2, the practice project needs a GitHub Integration Connection: connect one, or share one first with page 3, step 1.
Step 1: Let the agent ask a question
Open agents/pr-review/instructions.md in the editor. Add this paragraph below the first line, and commit:
If the prompt has no pull request URL, ask the user for the URL with the `ask_user_input` tool. Do not guess a URL.
The agent's system_tools: operation_type == "read" filter keeps ask_user_input, because it is a read tool.
On the agent's Overview tab, type Review the newest pull request. and click Start run. The prompt has no URL, so the agent asks for one. The run stops with the status Waiting, and a question card shows the question.
Type https://github.com/autohealai/astronomy-shop-template/pull/1 in the card and click Submit answer. Check that the run continues and ends with a review of that pull request.
Skip also continues the run. The agent then continues without the answer.
A run that a trigger starts also waits for an answer. Nobody may see the question. To stop such an agent from asking, add && name != "ask_user_input" to its system_tools filter. See Write a tool filter.
Step 2: Make an agent that calls an integration tool
A policy matches a call that touches an Integration Connection. To see a policy work, you need an agent that calls an integration tool. Create an agent named connection-check in the practice project. Replace its agent.yaml with this, and commit:
apiVersion: agents.autoheal.ai/v1
name: Connection Check
icon: plugs-connected
description: Calls one integration tool and reports what it returns.
instructions: |
Call the `github_list_repositories` tool one time.
Then list the names of the repositories, one on each line.
If a person rejects the tool call, say that a person rejected it, and stop. Do not try again.
model:
name: claude-haiku-5-5
limits:
model_requests: 6
system_tools: "false"
integration_tools: name == "github_list_repositories"
Run the agent with the prompt Check the connection. Check that the run ends with a list of repositories and that nothing paused it.
Step 3: Make a policy
You must be a Project Admin. Make the policy in the practice project, because a policy applies to every agent in its project.
- Open Agent policies
Go to Settings → PLATFORM → Agent policies, and click Create policy.
- Name the policy
In the name field, type
Approve practice GitHub calls. In the note field, typePractice policy. Delete it after page 2.Approvers see the note on each paused call. - Add the condition
Under Conditions, pick the field Name, the operator is, and the name of your GitHub Integration Connection as the value. Find the name in Settings → GENERAL → Integrations.
- Save
Leave Approvers empty, so anyone who can approve in the project can approve. Click Create policy.
Applies to shows the Integration Connections that the policy matches now. Check that it shows only your GitHub Integration Connection.
Step 4: Allow one call, and reject one call
Run connection-check again with the same prompt. This time, the run stops with the status Waiting. The approval card shows the tool github_list_repositories and three buttons:
| Button | What it does |
|---|---|
| Reject | The call does not run. You can type a note, and the agent reads it. Click Reject request to send it. |
| Allow for this run | The call runs. Later calls to the same tool on the same Integration Connection in this run do not wait again. Autoheal does not offer it for a compound shell command. |
| Allow once | Only this call runs. The next matching call waits again. |
Click Allow once. Check that the run continues and ends with the list of repositories.
Run the agent a third time. On the approval card, click Reject, type Practice run. Do not call GitHub., and click Reject request. Check that the run ends, and that the summary says that a person rejected the call.
Step 5: Delete the practice policy
Open Agent policies, open the policy, and delete it. Or turn off its switch to keep it for later. Deleting a policy cannot be undone.
For a production project, start with one policy: Operation type is write. It pauses every call that writes through an Integration Connection, in every agent of the project.
What to know
- A policy is a list of conditions on the Integration Connection that a call touches: Type, Name, Operation type, or a label. All conditions must match. A tool call waits if any enabled policy matches it.
- A policy has no condition on the agent or on the person who started the run. It applies to every agent in its project. To try a policy without risk, make it in the practice project.
- Policies do not match system tools, such as
create_artifactorgit_commit. Usesystem_toolsfilters for these. - A policy is not a limit on the shell. A shell command waits only when it runs a CLI that an Integration Connection signs in, such as
ghorgitfor GitHub. The agent itself says whether that command reads or writes. A command such ascurltouches no Integration Connection and never waits. Write what the agent must never change in its instructions, and connect systems with read-only credentials where you can. See The shell is not limited by tool filters. - An approval or a question never expires. A run that seems stuck can be waiting for a person.
- A Member and a Project Admin can answer questions and approve or reject calls. A Read-only user sees them but cannot act. Add people or user groups to a policy's Approvers to limit who can approve. Anyone who can approve in the project can still reject.
From the CLI
autoheal run pr-review "Review the newest pull request." --wait
autoheal runs hitl <run id>
autoheal runs answer <run id> --ref <ref> --text "https://github.com/autohealai/astronomy-shop-template/pull/1"
autoheal runs wait <run id>
--wait stops when the run needs a person, and exits with code 6. runs hitl lists what the run waits for: each line has a ref, a TYPE (question or approval) and the prompt. runs answer also takes --option for an offered choice, or --skip. runs wait waits again until the run ends or needs a person.
For an approval, use the ref of the approval line:
autoheal runs approve <run id> --ref <ref> --reason "Read-only call"
autoheal runs reject <run id> --ref <ref> --reason "Practice run. Do not call GitHub."
runs reject needs --reason, and the agent reads it. runs approve allows the call one time.
To make the policy from the CLI, save it as policy.json:
{
"name": "Approve practice GitHub calls",
"note": "Practice policy. Delete it after page 2.",
"conditions": [
{ "field": "integration.name", "operator": "equals", "values": ["<your GitHub Integration Connection name>"] }
]
}
Then send it to the API:
autoheal api POST /api/v1/agent-policies --project practice --input policy.json
autoheal api GET /api/v1/agent-policies --project practice
autoheal api DELETE /api/v1/agent-policies/<policy id> --project practice
See Governance Policies for conditions, labels, approvers and limits.