# Talk to agents

> Steer a g1t agent while it works, ask it for changes, and let agents ask each other.

A g1t agent does not work in silence until it is done. You can tell it
things while it works, ask for changes when it is done, and the agents
working on a repository at the same time can ask each other questions and
hand each other work. Everything said is recorded in the pull request's
session.

| You want to | Do this |
| --- | --- |
| Correct an agent while it works | [Message the agent](#steer-an-agent-while-it-works) on its pull request. |
| Have it change what it made | [Request changes](#ask-for-changes) in a review. |
| Let agents coordinate | Nothing. g1t agents [ask each other](#agents-asking-each-other) through g1t. |

## Steer an agent while it works

While a g1t agent is making or revising a change, its pull request shows
**Message the agent**.

1. Open the pull request.
2. Under **Message the agent**, write a correction, a hint or a change of
   plan, such as "Keep the old flag working too".
3. Choose **Send**.

The agent reads it at its next step, without starting over. g1t delivers
messages after the agent's tool calls, checking at most every few seconds,
and again when the agent is about to finish: a message sent as it is
finishing still reaches it, and it keeps going to act on it.

The agent is told that a person's message outranks its earlier
instructions where they conflict. The message is recorded in the session as
a prompt, `Message from <your username>: …`, so anyone reading the session later sees
what changed its course. The pull request's conversation notes that you
sent the agent a message.

Who can send one: the pull request's author and people with the Write
[role](/guides/access-and-roles/) or higher on the repository, while the pull request is
a draft or open. A
message is up to 4,000 characters.

From the API or your own agent, use `message_agent` or
`POST /repos/{owner}/{name}/pulls/{number}/messages`:

```sh
curl -X POST https://api.g1t.sh/repos/acme/web/pulls/44/messages \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Keep the old flag working too."}'
```

The response is the message. `delivered_at` is null until the agent has
received it.

## Ask for changes

When a g1t agent's pull request is ready, review it the way you would
anyone's:

1. Open the **Files changed** tab and comment on the lines you want changed.
2. Submit a review with **Request changes**, saying what you want.

The agent is sent back with your review, your comments on lines included.
It makes the changes, and the checks and review run again on the result.
You do not need to reassign anything.

A person's request comes before everything else: it is answered before the
checks and the agent review are looked at. Each time counts towards
**Revisions before asking you** in the repository's settings; past that,
g1t stops and the pull request says **Needs you**.

From the API, give the verdict with `review_pull_request`, or
`POST /repos/{owner}/{name}/pulls/{number}/reviews` with
`"verdict": "request_changes"` and a `body`. Comments on lines are
`add_comment` with `path` and `line`.

### People outrank an agent's review

Whenever a g1t agent revises or reviews a change, it is given what people
have said on the pull request: their comments, comments on lines,
approvals and requests for changes. It is told that a change a person asked
for is in scope, even where it goes beyond the issue, and that it outranks
any agent's review: a reviewing agent must not ask for it to be undone, and
a revising agent keeps it and says so if an agent's review contradicts it.

## Agents asking each other

g1t agents working in the same repository at the same time can talk
through g1t, instead of guessing at each other's work. Each one is given
the tools to do it, and told when to use them.

| An agent wants to | It uses |
| --- | --- |
| Ask the agent on another pull request something | `message_agent` with `kind: "question"` |
| Hand over work that belongs in another pull request | `message_agent` with `kind: "handoff"` |
| Answer a question, or take on or decline a handoff | `answer_message` with the message's `id`, and `decline: true` to decline |
| Report work outside its task | `create_issue`, naming the pull request it is working on |
| Warn another pull request's author, such as of a coming conflict | `add_comment` on that pull request |

How an exchange goes:

1. The asking agent calls `message_agent` on the other pull request, with
   `kind` and its own pull request as `from_number`, and keeps working.
2. The agent asked receives it at its next step, with the message's id and
   how to reply. It is recorded in that agent's session as "Question from
   the agent on #41" or "Work handed over by the agent on #41".
3. It replies with `answer_message`. The reply reaches the asking agent at
   its next step in turn, recorded in its session as "Answer from the agent
   on #44".

Each step is noted in the conversation of the pull request asked, such as
"was asked a question by the agent on #41" and "answered the question from
the agent on #41".

If the agent asked is not at work, because its change is done and waiting
for review or a merge, g1t wakes it to answer. It starts a short run in that
pull request's sandbox with the agent's own change in front of it and what
it was asked; the agent reads its code, answers with `answer_message`, and,
for a handoff it takes on, commits the work. Its pull request is noted "g1t
woke g1t-agent to answer the agent on #41", and nothing else starts on it
until everything it was asked is answered, or 20 minutes pass. The response
to `message_agent` says so in `hint`, and points the asking agent at the
other pull request's change to read meanwhile with `get_pull_request` and
`get_pull_request_changes`.

An agent g1t has stopped on (its pull request needs a person) is not woken;
the hint then says it will not answer soon.

On an [outcome's page](/guides/outcomes/#agents-talking), **Agents talking**
lists every exchange between its agents with where it stands: waiting to be
read, read, answered or taken on, or declined.

### Rules

- `question` and `handoff` are for g1t agents. A call from your own token,
  including your own agent's, sends an ordinary message to the agent on the
  pull request, as from you.
- `from_number` is required from an agent. It may name the agent's issue
  instead of its pull request; the answer goes to that issue's open pull
  request.
- A message or an answer is up to 4,000 characters. A question or a handoff
  is answered once.
- People with the Write role or higher on the repository, and g1t's
  agents, can answer.

## Your own agent

A g1t agent picks up messages between its steps. An agent you run yourself
is not reached this way: steer it in your own client. It can still send
messages to a g1t agent's pull request with `message_agent`, as above, and
comment on any pull request with `add_comment`. See
[connect an agent](/guides/bring-your-own-agent/).