Skip to content
HaneDOCS日本語

API reference

Agents

Agent definitions, runs (AgentRun) and embedded chat conversations.

Generated from the public API contract (OpenAPI). Descriptions in the contract are written in Japanese.

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 が必要。自分が作った会話を新しい順に返す

Name In Type Required Description
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 文字まで)を題名にする

Name In Type Required Description
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

Name Type Required Description
title string
  • 201 — Conversation: 作った会話
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/conversations/{id}

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

Name In Type Required Description
id path string yes
  • 200 — Conversation: 会話
  • default — Problem: RFC 9457 Problem Details

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

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

Name In Type Required Description
id path string yes
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 を返し、何も保存しない

Name In Type Required Description
id path string yes
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

Name Type Required Description
content string yes
client_message_id string yes
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 は配信しない

Name In Type Required Description
id path string yes
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 のセッションファイルは含めない

Name In Type Required Description
conversation_id path string yes
  • 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 を返す。実行の復元や操作の再実行は行わない

Name In Type Required Description
conversation_id path string yes
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 と組織・環境・プロジェクト・所有者・会話の範囲 が一致することを確認して返す。 取得しても現在の認可や実行台帳は上書きせず、実行の復元や操作の再実行は行わない

Name In Type Required Description
conversation_id path string yes
digest path string yes
  • 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・過去の承認状態は再作成せず、操作を再実行しない

Name In Type Required Description
conversation_id path string yes
digest path string yes
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 が必要。新しい順

Name In Type Required Description
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 からの実行)

Name In Type Required Description
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

Name Type Required Description
agent string yes
input object yes
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)で決める

Name In Type Required Description
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

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

GET/v1/agents/runs/{id}

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

Name In Type Required Description
id path string yes
  • 200 — AgentRun: AgentRun
  • default — Problem: RFC 9457 Problem Details

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

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

Name In Type Required Description
id path string yes
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 を作る

Name In Type Required Description
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 が必要

Name In Type Required Description
id path string yes
  • 200 — ActionRequest: ActionRequest
  • default — Problem: RFC 9457 Problem Details

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

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

Name In Type Required Description
id path string yes
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 を「承認する」で閉じて、直した値を推定として取り込む。取り込みの記録には直した人を残す

Name In Type Required Description
id path string yes
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

Name Type Required Description
csv string yes 直した値。見出しは提案と同じ
task_version integer yes 承認の 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 になり、再承認に回す

Name In Type Required Description
id path string yes
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json — ManualResultInput

Name Type Required Description
task_version integer yes 実行の Task のバージョン(If-Match と同じ)
action_digest string yes 担当が見た承認の対象の digest
result accepted | declined | deviated | not_performed yes 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 を閉じ、止まったところから続ける。答えの値は暗号化して持ち、続きの実行が読んだら消す

Name In Type Required Description
id path string yes
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

Name Type Required Description
fields object yes 欄の名前ごとの答え。ページで答えられる欄だけを受け付ける
task_version integer yes
  • 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 が必要。ランナーを、動ける主体と扱ってよい接続に束縛して登録する

Name In Type Required Description
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

Name Type Required Description
name string yes
kind network | laptop yes
principal string yes
connections string[] yes
  • 201 — BrowserRunner: 登録した
  • default — Problem: RFC 9457 Problem Details

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

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

Name In Type Required Description
id path string yes
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 分間宣言する

Name In Type Required Description
id path string yes
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 でも呼ぶたびに確かめる

Name In Type Required Description
id path string yes
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 が必要。受け取った仕事の結果を記録する。取り消したランナーの結果は受け取らない

Name In Type Required Description
id path string yes
action path string yes
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)操作を、相手の記録で確かめた結果にする

Name In Type Required Description
id path string yes
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

Name Type Required Description
sent boolean yes 相手に届いていたか
note string yes 確かめた方法
  • 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 と公開ゲートを通さない。承認を待つ提案にも効く

Name In Type Required Description
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

Name Type Required Description
tools string[] yes
reason string yes
  • 200 — object: 上書きの一覧
  • default — Problem: RFC 9457 Problem Details

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

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

Name In Type Required Description
tool path string yes
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・モデルごとに数えた直近の使用量。プロンプトと応答の本文は残していない

Name In Type Required Description
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 で起動する。外への操作と人への引き継ぎは起きない

Name In Type Required Description
Idempotency-Key header string 副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

application/json

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

GET/v1/agents/evals/compare

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

Name In Type Required Description
base query string yes
target query string yes
  • 200 — EvalComparison: 比べた結果
  • default — Problem: RFC 9457 Problem Details

GET/v1/agents/evals/{id}

agents:read が必要

Name In Type Required Description
id path string yes
  • 200 — EvalRun: 評価の実行
  • default — Problem: RFC 9457 Problem Details