コンテンツにスキップ
HaneDOCSEN

API リファレンス

Agent

Agent の定義と実行(AgentRun)、組み込みチャットの会話。

Agent の定義と実行(AgentRun)。手元では、LLM の CLI の代わりに台本のドライバー(scripted)が、定義の手順どおりに Tool Gateway のツールを呼んで submit_result を返す。ドライバーは RunToken でしかツールを呼べない

説明は公開 API の契約(OpenAPI)から生成しています。

GET /v1/agents/conversations
POST /v1/agents/conversations
GET /v1/agents/conversations/{id}
GET /v1/agents/conversations/{id}/messages
POST /v1/agents/conversations/{id}/messages
GET /v1/agents/conversations/{id}/events
GET /v1/agents/conversations/{conversation_id}/memory
POST /v1/agents/conversations/{conversation_id}/memory
GET /v1/agents/conversations/{conversation_id}/memory/{digest}
POST /v1/agents/conversations/{conversation_id}/memory/{digest}/restore
GET /v1/agents/tools
GET /v1/agents/definitions
GET /v1/agents/runs
POST /v1/agents/runs
POST /v1/agents/requests
GET /v1/agents/runs/{id}
POST /v1/agents/runs/{id}/cancel
GET /v1/agents/action-requests
GET /v1/agents/action-requests/{id}
POST /v1/agents/action-requests/{id}/cancel
POST /v1/agents/action-requests/{id}/revise
POST /v1/agents/action-requests/{id}/perform
POST /v1/agents/action-requests/{id}/handoff
GET /v1/agents/browser-runners
POST /v1/agents/browser-runners
POST /v1/agents/browser-runners/{id}/revoke
POST /v1/agents/browser-runners/{id}/attend
POST /v1/agents/browser-runners/{id}/claim
POST /v1/agents/browser-runners/{id}/jobs/{action}/result
POST /v1/agents/action-requests/{id}/reconcile
GET /v1/agents/decider-overrides
POST /v1/agents/decider-overrides
DELETE /v1/agents/decider-overrides/{tool}
GET /v1/agents/budget
GET /v1/agents/model-usage
GET /v1/agents/eval-suites
GET /v1/agents/evals
POST /v1/agents/evals
GET /v1/agents/evals/compare
GET /v1/agents/evals/{id}

GET/v1/agents/conversations

agents:read が必要。自分が作った会話を新しい順に返す

名前 場所 型 必須 説明
agent query string
limit query integer
  • 200 — object: 会話の一覧
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/conversations

agents:run が必要。自分だけが読める会話を作る。会話のメッセージは、有効なバージョンのチャットの Agent(default: true)が受ける。 title を指定しなければ、最初のメッセージの 1 行目(40 文字まで)を題名にする

名前 場所 型 必須 説明
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
title string
  • 201 — Conversation: 作った会話
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/conversations/{id}

agents:read が必要。自分が作った会話を返す

名前 場所 型 必須 説明
id path string はい
  • 200 — Conversation: 会話
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/conversations/{id}/messages

agents:read が必要。自分の会話のメッセージを古い順に返す

名前 場所 型 必須 説明
id path string はい
limit query integer
  • 200 — object: メッセージの一覧
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/conversations/{id}/messages

agents:run が必要。自然文のメッセージを保存し、同じトランザクションでチャットの Agent(default: true)の AgentRun を始める。 チャットの Agent は、必要なときに業務の Agent を agents.run で呼んで結果を受け取り、答えを返事にする。 同じ会話と client_message_id の組では一度だけ受け付ける。返事が終わるまで、次のメッセージは CONFLICT にする。 チャットの返事を外への操作の承認には使わない。 agent を指定すると、チャットの Agent はこのメッセージではその Agent だけを呼べる。 チャットの Agent がないか、チャットの Agent が呼べない Agent を指定したら VALIDATION_FAILED を返し、何も保存しない

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
content string はい
client_message_id string はい
agent string 利用者が指定する業務の Agent。チャットの Agent は、このメッセージではこの Agent だけを呼べる
attachments object[] 添付する文書。先にアップロードし、自分が読める文書だけを付けられる。 チャットの Agent の文書の入力(format: document)には、会話に添付した文書をすべて渡す
  • 202 — ChatMessage: チャットの Agent の答えを待つメッセージ(run_id はチャットの Agent の実行)
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/conversations/{id}/events

agents:read が必要。自分が作った会話の現在状態と進行記録を SSE で配信する。 event: snapshot の data は ConversationSnapshot。最初に現在状態を返し、その後は実際の変更があるときに配信する。 activities は Last-Event-ID より後の進行記録で、再接続の際にも同じ sequence を二重に追加しない。 Last-Event-ID が現在の cursor より大きい場合は、進行記録を先頭から返す。 15 秒ごとにコメントの heartbeat を送り、45 秒以内に接続を閉じて再接続時に認証と閲覧権限を確かめる。 event: failure の data は ConversationStreamFailure で、接続中の拒否を知らせて接続を閉じる。 推論の内部過程、資格情報、モデル内部の JSON は配信しない

名前 場所 型 必須 説明
id path string はい
Last-Event-ID header string 最後に受け取った SSE の id。0 以上かつ 9007199254740991 以下の十進整数の文字列
  • 200 — string: text/event-stream の配信。snapshot の id は data.cursor。 conversation・items・turns はその時点の現在状態で、activities は最後の cursor より後の記録
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/conversations/{conversation_id}/memory

agents:read と会話の作成者であることが必要。資格情報の組織・環境・プロジェクトの範囲で取得する。 現在の Agent に連続して頼んでいる会話のメッセージと、その区間に結び付いたすべての実行を省略せず返す。 実行後も会話を続けるが、別の Agent へ切り替えた境界は越えない。 RunToken・API キー・TenantContext・CLI のセッションファイルは含めない

名前 場所 型 必須 説明
conversation_id path string はい
  • 200 — AgentMemorySnapshot: 現在の Agent に対する会話と実行のコンテキスト
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/conversations/{conversation_id}/memory

agents:read・agents:run と会話の作成者であることが必要。本文は送らず、Idempotency-Key が必要。 現在のコンテキストを、組織・環境・プロジェクト・作成者・会話と内容の digest に結び付けたキーで ObjectStore に保存する。 保存した内容は上書きせず、保存先の key と digest を返す。実行の復元や操作の再実行は行わない

名前 場所 型 必須 説明
conversation_id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
  • 201 — AgentMemoryArchive: 保存したコンテキストの参照
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/conversations/{conversation_id}/memory/{digest}

agents:read と会話の作成者であることが必要。現在の資格情報と会話から組織・環境・プロジェクト・作成者の範囲を確かめる。 保存先の key はサーバーが決め、保存した JSON の digest と組織・環境・プロジェクト・所有者・会話の範囲 が一致することを確認して返す。 取得しても現在の認可や実行台帳は上書きせず、実行の復元や操作の再実行は行わない

名前 場所 型 必須 説明
conversation_id path string はい
digest path string はい
  • 200 — AgentMemorySnapshot: 保存したコンテキスト
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/conversations/{conversation_id}/memory/{digest}/restore

agents:read・agents:run と元の会話の作成者であることが必要。本文は送らず、Idempotency-Key が必要。 ObjectStore から保存したコンテキストを取得し、4 MiB の上限・Schema・digest・組織・環境・プロジェクト・所有者・会話の範囲 を確認して、同じ Agent の新しい会話を作る。 保存した履歴を新しい会話のコンテキストに引き継ぎ、現在の認可と、有効な ReleaseBundle にある同じ Agent の入力の Schema を使って続ける。 別の Agent へ切り替えると、保存した履歴からの引き継ぎもその境界で区切る。 元の AgentRun・ActionRequest・過去の承認状態は再作成せず、操作を再実行しない

名前 場所 型 必須 説明
conversation_id path string はい
digest path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
  • 201 — Conversation: 保存したコンテキストを引き継いだ新しい会話
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/tools

agents:read が必要。Tool Registry。有効な ReleaseBundle で ToolExposure から Agent のツールにしている操作の ToolDefinition

  • 200 — object: ToolDefinition の一覧
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/definitions

agents:read が必要。有効なバージョンの Agent の定義

  • 200 — object: Agent の定義
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/runs

agents:read が必要。新しい順

名前 場所 型 必須 説明
agent query string
case_id query string
limit query integer
  • 200 — object: AgentRun の一覧
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/runs

agents:run が必要。有効なバージョンの定義で AgentRun を作り、ドライバーの起動を頼む(コンソールの Playground からの実行)

名前 場所 型 必須 説明
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
agent string はい
input object はい
shadow boolean 外への操作と人への引き継ぎをせず、記録だけを残す
  • 201 — AgentRun: 起動を待つ AgentRun
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/requests

agents:run が必要。受付。頼んだ人の自由な文から、有効な Agent の中から頼む Agent を選び、定義の入力の Schema に沿って 文から入力を拾う。入力がそろえば実行を始める(201)。足りなければ足りない項目を、Agent を決めきれなければ候補を返す(200)。 手元の受付は LLM を使わず、定義の目的・頼み方の例(examples)と入力の形(format・pattern)で決める

名前 場所 型 必須 説明
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
messages string[] はい まだ実行を始めていない間の、頼んだ人の文(古い順)。聞き返されて答えた文は後ろに足す。新しい文の値を優先する
agent string 頼む Agent を決めているときの名前。文からは入力だけを拾う
shadow boolean 外への操作と人への引き継ぎをせず、記録だけを残す
  • 200 — AgentRequestResult: 入力が足りないか、Agent を決めきれない
  • 201 — AgentRequestResult: 実行を始めた
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/runs/{id}

agents:read が必要。状態・結果・ツールの呼出しの記録(引数と結果の全文は持たず、要約だけ)

名前 場所 型 必須 説明
id path string はい
  • 200 — AgentRun: AgentRun
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/runs/{id}/cancel

agents:run が必要。止める。RunToken の期限を待たず、次のツールの呼出しから拒否する

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

  • 200 — AgentRun: 止めた AgentRun
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/action-requests

agents:read が必要。外への操作の提案(ActionRequest)。新しい順。Agent が外への操作のツールを呼ぶと、 宛先と内容を固定して digest を付け、定義の approval の割り当てに承認の Task を作る

名前 場所 型 必須 説明
run_id query string
state query string
approval_task_id query string この承認の Task で決める操作だけ
execution_task_id query string この実行の Task で人が行う操作だけ
limit query integer
  • 200 — object: ActionRequest の一覧
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/action-requests/{id}

agents:read が必要

名前 場所 型 必須 説明
id path string はい
  • 200 — ActionRequest: ActionRequest
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/action-requests/{id}/cancel

agents:run が必要。実行の前(承認待ち・実行待ち・ランナー待ち)なら止める。承認を待つ Task も取り消す

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

  • 200 — ActionRequest: 止めた ActionRequest
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/action-requests/{id}/revise

approvals:tasks.decide が必要。承認を待つ台帳への登録の提案の値を直し、そのまま承認する。 直せるのは承認の Task を決められる人だけで、見出し(項目)は変えられない。直した値で digest を取り直し、 承認の Task を「承認する」で閉じて、直した値を推定として取り込む。取り込みの記録には直した人を残す

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
csv string はい 直した値。見出しは提案と同じ
task_version integer はい 承認の Task のバージョン(If-Match と同じ)
  • 200 — ActionRequest: 直して承認した ActionRequest
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/action-requests/{id}/perform

approvals:tasks.decide が必要。人が行う操作の結果を実行台帳に記録し、実行の Task を閉じる。記録できるのは実行の Task を 決められる人だけ。担当が見た digest がいまの内容と違えば 409。accepted・declined は承認された相手・方法・金額で行ったときだけ 記録でき、違えば 409 で何も残さない。違う内容で行ったら deviated で記録する。ActionRequest は failed になり、再承認に回す

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json — ManualResultInput

名前 型 必須 説明
task_version integer はい 実行の Task のバージョン(If-Match と同じ)
action_digest string はい 担当が見た承認の対象の digest
result accepted | declined | deviated | not_performed はい accepted は相手が受け付けた、declined は相手が断った、deviated は承認された内容と違うことをした、 not_performed は行わなかった
performed_at string 行った日時。not_performed のほかは必須
counterparty string 行った相手。not_performed のほかは必須
method ManualMethod
reference string 受付番号。accepted は必須
amount number 行った金額(通貨の最小単位)。承認の対象に金額があれば必須
currency string
note string 断られた理由、違った内容、行わなかった理由。accepted のほかは必須
  • 200 — ActionRequest: 結果を記録した ActionRequest
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/action-requests/{id}/handoff

approvals:tasks.decide が必要で、引き継ぎの Task を決められる人だけが呼べる。CAPTCHA や多要素認証で止まった手順の、 ページの欄に答えて Task を閉じ、止まったところから続ける。答えの値は暗号化して持ち、続きの実行が読んだら消す

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
fields object はい 欄の名前ごとの答え。ページで答えられる欄だけを受け付ける
task_version integer はい
  • 200 — ActionRequest: 続きの実行を待つ
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/browser-runners

agents:read が必要

  • 200 — object: ランナーの一覧
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/browser-runners

agents:runners.manage が必要。ランナーを、動ける主体と扱ってよい接続に束縛して登録する

名前 場所 型 必須 説明
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
name string はい
kind network | laptop はい
principal string はい
connections string[] はい
  • 201 — BrowserRunner: 登録した
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/browser-runners/{id}/revoke

agents:runners.manage が必要。以後は仕事を渡さず、持っている仕事の結果も受け取らない

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
  • 200 — BrowserRunner: 取り消した
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/browser-runners/{id}/attend

agents:runners.run が必要。社員本人の認証だけが呼べる。端末のランナーに立ち会っていることを 5 分間宣言する

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
  • 200 — BrowserRunner: 宣言した
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/browser-runners/{id}/claim

agents:runners.run が必要。ランナーの主体だけが呼べる。次の仕事を受け取る。取り消したランナーは拒み、 立ち会いのない端末のランナーには渡さない。応答は冪等の台帳に保存しないので、同じ Idempotency-Key でも呼ぶたびに確かめる

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
  • 200 — object: 仕事。なければ job は null
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/browser-runners/{id}/jobs/{action}/result

agents:runners.run が必要。受け取った仕事の結果を記録する。取り消したランナーの結果は受け取らない

名前 場所 型 必須 説明
id path string はい
action path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

  • 200 — ActionRequest: 記録した
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/action-requests/{id}/reconcile

agents:run が必要。送ったか分からない(unknown)操作を、相手の記録で確かめた結果にする

名前 場所 型 必須 説明
id path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
sent boolean はい 相手に届いていたか
note string はい 確かめた方法
  • 200 — ActionRequest: 照合した ActionRequest
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/decider-overrides

agents:read が必要。ReleaseBundle を待たずに承認を人だけに戻したツール

  • 200 — object: 上書きの一覧
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/decider-overrides

approvals:deciders.restrict が必要。ツールの承認をすぐに人だけに戻す(審査用の Agent の承認と、policy の自動の承認を止める)。 AI に任せる範囲を狭めるだけなので、ReleaseBundle と公開ゲートを通さない。承認を待つ提案にも効く

名前 場所 型 必須 説明
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
tools string[] はい
reason string はい
  • 200 — object: 上書きの一覧
  • default — Problem: RFC 9457 Problem Details

DELETE/v1/agents/decider-overrides/{tool}

approvals:deciders.restore が必要(admin)。上書きを外し、有効な ReleaseBundle の DeciderPolicy に戻す

名前 場所 型 必須 説明
tool path string はい
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
  • 200 — object: 上書きの一覧
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/budget

agents:read が必要。今日(UTC)の予算(platform/v1alpha1 Budget)と使った数。Budget がなければ limit は null

  • 200 — object: 今日の予算
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/model-usage

agents:read が必要。Model Gateway を通ったモデルの呼出しを、日(UTC)・Agent・モデルごとに数えた直近の使用量。プロンプトと応答の本文は残していない

名前 場所 型 必須 説明
days query integer
  • 200 — object: 使用量
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/eval-suites

agents:read が必要。有効なバージョンの EvalSuite

  • 200 — object: EvalSuite の定義
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/evals

agents:read が必要。評価の実行。新しい順に 50 件

  • 200 — object: 評価の実行
  • default — Problem: RFC 9457 Problem Details

POST/v1/agents/evals

agents:run が必要。EvalSuite の件ごとに Agent を shadow で起動する。外への操作と人への引き継ぎは起きない

名前 場所 型 必須 説明
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

名前 型 必須 説明
suite string はい
release_id string まだ有効にしていないバージョンで評価するときに渡す。stage と prod の有効化には、そのバージョンで通った評価が要る
  • 202 — EvalRun: 始めた評価
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/evals/compare

agents:read が必要。同じ EvalSuite の 2 回の評価を件ごとに比べる。知識を入れる前後の ReleaseBundle で評価を流し、 通るようになった件と落ちるようになった件、結果の項目の違いを見る

名前 場所 型 必須 説明
base query string はい
target query string はい
  • 200 — EvalComparison: 比べた結果
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/evals/{id}

agents:read が必要

名前 場所 型 必須 説明
id path string はい
  • 200 — EvalRun: 評価の実行
  • default — Problem: RFC 9457 Problem Details