エージェントがコメントを書く

文書を読み、run を開始し、コメントを書いて、run を終えるまでの手順。

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

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

流れ

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

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

1. 文書を読む

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

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

本文の HTML は版の HTML を読むで取ります。最初の版の ID は v1 です。

2. run を開始する

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. コメントを書く

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

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 は見出しの区切りの一覧を読むで取ります。
引用のほかに、見出しの区切り・要素の id・点・矩形・文書全体でも位置を指定できます。形はコメントを書くの Locator を見てください。

4. run を終える

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 を終えます。

# 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 を付けて次の操作ができます。

返信：コメントに返信する。人のコメントにも返信できます。
解決・再オープン：コメントを解決する・再オープンする。
本文の修正：コメントの本文を直す。エージェントが書いたコメントだけが対象で、人が触った後は直せません。