---
title: エージェントがコメントを書く
description: 文書を読み、run を開始し、コメントを書いて、run を終えるまでの手順。
---

AI エージェントが文書を読んで指摘をコメントとして書き込むまでの流れです。例では、エージェント用トークンを環境変数 `CR_AGENT_TOKEN` に入れています。

```bash
export ORIGIN=https://comment-review.fsmarketing.workers.dev
export REVIEW=review_example01
```

## 流れ

1. 文書を読み、`commentsRevision` を控える。
2. run を開始する。
3. コメントを書く（指摘の数だけ繰り返す）。
4. run を終える。

run は、エージェントの一連の書き込みをまとめる単位です。コメントの作成・返信・解決・編集は、どれも run の ID を付けて送ります。1 つの run で書けるコメントと返信は、合わせて 100 件までです。

## 1. 文書を読む

```bash
curl "$ORIGIN/api/reviews/$REVIEW" -H "Authorization: Bearer $CR_AGENT_TOKEN"
```

応答の `review.commentsRevision` を控えます。コメントが書き換わるたびに 1 増える番号で、run の開始と編集のときに `baseCommentsRevision` として送ります。

本文の HTML は [版の HTML を読む](/reference/reviews/get-version-bundle) で取ります。最初の版の ID は `v1` です。

## 2. run を開始する

```bash
curl -X POST "$ORIGIN/api/reviews/$REVIEW/ai-review-runs" \
  -H "Authorization: Bearer $CR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"baseCommentsRevision": 3, "title": "料金表の確認"}'
```

応答の `run.id` を控えます。run を開始すると `commentsRevision` も 1 増えます。この後の書き込みで `baseCommentsRevision` を送るときは、直前の応答の `review.commentsRevision` を使ってください。文書に版が 2 つ以上あるときは、`targetVersionId` に最新版の ID を入れます。

## 3. コメントを書く

位置は、本文中の文字列をそのまま引用して指定するのがいちばん確実です。

```bash
curl -X POST "$ORIGIN/api/reviews/$REVIEW/ai-review-runs/airun_example01/comments" \
  -H "Authorization: Bearer $CR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "税込か税抜かを書いてください。",
    "dedupeKey": "price-tax",
    "locator": { "quote": "月額 980 円" }
  }'
```

- `dedupeKey` は指摘ごとに変えます。通信が切れて同じ要求を送り直しても、同じキーなら二重には書かれず、前のコメントが返ります。
- 引用が本文の 2 か所以上に当たると 422 `quote_not_unique` になります。引用を長くするか、`sectionId` で範囲を絞ります。区切りの ID は [見出しの区切りの一覧を読む](/reference/reviews/get-dom-context) で取ります。
- 引用のほかに、見出しの区切り・要素の `id`・点・矩形・文書全体でも位置を指定できます。形は [コメントを書く](/reference/comments/create-comment) の Locator を見てください。

## 4. run を終える

```bash
curl -X PATCH "$ORIGIN/api/reviews/$REVIEW/ai-review-runs/airun_example01" \
  -H "Authorization: Bearer $CR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed", "baseCommentsRevision": 5, "summary": "指摘 1 件"}'
```

`baseCommentsRevision` には、書き込みを終えた後の値を入れます。最後の書き込みの応答の `review.commentsRevision` か、文書を読み直して取ります。途中で止めたときは `"status": "failed"` にします。終えた run には書き込めません。

## よくあるエラー

| 応答 | 意味 | 対処 |
|---|---|---|
| 409 `comments revision conflict` | 読んだ後に、ほかの人かエージェントが書き込んだ | 文書を読み直し、応答の `currentRevision` で送り直す |
| 409 `source_changed`・`version_changed` | run を開始した後に、文書の本文か版が変わった | 文書を読み直し、新しい run で書き直す |
| 409 `ai review run is terminal` | run がもう終わっている | 新しい run を開始する |
| 422 `quote_not_found` | 引用が本文に無い | 本文をそのまま写す。改行や空白の違いは 1 つの空白として照合される |
| 422 `run_limit_exceeded` | run の上限を超えた | run を終えて、新しい run で続ける |

## 返信だけする

新しいコメントを書かず、既存のコメントに返信だけするときも run が要ります。run を開始し、返信し、run を終えます。

```bash
# 1. run を開始する（応答の run.id を控える）
curl -X POST "$ORIGIN/api/reviews/$REVIEW/ai-review-runs" \
  -H "Authorization: Bearer $CR_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d '{"baseCommentsRevision": 3}'

# 2. 返信する
curl -X POST "$ORIGIN/api/reviews/$REVIEW/comments/comment_example01/thread" \
  -H "Authorization: Bearer $CR_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d '{"runId": "airun_example01", "body": "税込の表記にしました。", "dedupeKey": "reply-comment_example01"}'

# 3. run を終える（baseCommentsRevision は返信の応答の review.commentsRevision）
curl -X PATCH "$ORIGIN/api/reviews/$REVIEW/ai-review-runs/airun_example01" \
  -H "Authorization: Bearer $CR_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d '{"status": "completed", "baseCommentsRevision": 5}'
```

## 返信・解決・編集

書いた後のコメントは、同じ run の ID を付けて次の操作ができます。

- 返信：[コメントに返信する](/reference/comments/reply-to-comment)。人のコメントにも返信できます。
- 解決・再オープン：[コメントを解決する・再オープンする](/reference/comments/set-comment-status)。
- 本文の修正：[コメントの本文を直す](/reference/comments/edit-comment)。エージェントが書いたコメントだけが対象で、人が触った後は直せません。