Hane Platform

Agent と AgentRun

Agent の定義、ドライバー、Tool Gateway を通したツール、実行の中の承認、会話のコンテキスト、評価の仕組みを説明します。

このページでは、Hane の Agent がどう定義され、どう実行されるかを説明します。ドライバーごとの提供状況、ツールの呼び方、外への操作の承認、評価までを順に見ていきます。

Agent と AgentRun

Agent は、目的・使ってよいツール・上限・入力と出力の Schema を持つ定義です。マニフェスト（agents/v1alpha1 の Agent）に書き、ほかの定義と同じく ReleaseBundle にまとめて有効化します。

AgentRun は、有効なバージョンの Agent を 1 回動かした記録です。入力・結果・ツールの呼出しの要約・使ったトークン・状態を持ちます。状態は queued・running から始まり、succeeded・failed・cancelled・limit_exceeded のどれかで終わります。

定義の項目	意味
`purpose`・`examples`	何をする Agent か。受付が自由な文から Agent を選ぶときにも使います
`input`・`output`	入力の JSON Schema と、`submit_result` で返す結果の JSON Schema。結果には `status` を必ず持たせます
`driver`	どう動かすか（下の表）
`instructions`・`script`	モデルに渡す指示か、台本のドライバーの手順
`tools`	呼んでよいツール。Tool Gateway は呼出しのたびにこの一覧を確かめます
`limits`	`maxToolCalls`・`maxSeconds`・`maxModelTokens`（1 回の実行のトークン。既定は 50,000）
`approval`・`handover`	外への操作の承認と、人への引き継ぎで Task を作る割り当ての規則
`workflows`・`connections`・`toolExposures`	起動してよい Workflow、呼んでよい顧客の API

apiVersion: agents/v1alpha1
kind: Agent
metadata:
  name: vehicle-check
spec:
  purpose: 登録番号から、車両の車種・車検の満了日・走行距離を車両台帳で調べて答える
  input:
    type: object
    required: [vehicle]
    properties:
      vehicle: { type: string, title: 登録番号 }
  driver: opencode
  instructions: |-
    data.find_record で車両を探し、見つかったら submit_result で答える。
    見つからなければ request_human_help で車両管理チームに引き継ぐ。台帳にない値を作らない。
  tools: [data.find_record, request_human_help]
  handover:
    assignment: fleet-desk
  limits:
    maxToolCalls: 4
    maxSeconds: 120
  output:
    type: object
    required: [status, vehicle]
    properties:
      status: { type: string }
      vehicle: { type: string }

ドライバー

ドライバーは、Agent を何で動かすかを決めます。どのドライバーも、同じ Tool Gateway を通してツールを呼び、submit_result で結果を返します。

`driver`	動き方	動く場所と提供状況
`scripted`	定義の `script` の手順どおりにツールを呼びます。モデルを使いません	どの環境でも動きます
`llm`	モデルにツールを選ばせます	プレビュー手元の開発環境では記録した応答で動きます。クラウド環境では、まだ有効にしていません
`opencode`	オープンソースのハーネス opencode を、サンドボックスのコンテナで起動します。モデルの呼出しは Model Gateway を通ります	プレビュークラウド環境のサンドボックスで動きます。上流のモデルは Cloudflare Workers AI で確かめています
`codex`・`claude`	開発者の手元の Codex CLI・Claude Code を起動し、Hane の MCP のツールだけを使わせます	プレビュー手元の開発環境での検証用です。クラウド環境では提供していません

CLI のドライバー（opencode・codex・claude）は、cliProfile で CLI のバージョンとサンドボックスのイメージの組を選びます。書かなければ、ドライバーごとの基準の組を使います。どの組で動くかは ReleaseBundle で決まるので、CLI を上げるのも戻すのも、定義の評価と有効化の流れに乗ります。

ツールと Tool Gateway

Agent がツールを呼ぶ先は、いつも Tool Gateway です。ドライバーは、実行ごとに発行される短命の RunToken を付けて呼びます。Tool Gateway は呼出しのたびに、定義の tools にあるか、実行が止められていないか、上限を超えていないかを確かめます。実行を取り消すと、RunToken の期限を待たずに次の呼出しから拒否します。

主なツールは次のとおりです。

区分	ツールの例
台帳の読み取り	`data.find_record`・`data.get_record`・`ontology.query`・`ontology.knowledge`
文書の読み取り	`documents.search`・`documents.read_pages`・`documents.read_summary`
業務の進行	`workflow.start`・`workflow.get_case`・`tasks.create`・`request_human_help`
顧客の API	`integration.describe`・`integration.read`・`integration.execute`
外への操作	`communication.send_email`・`communication.send_sms`・`communication.place_call`・`browser.run_flow`
結果	`submit_result`（審査用の Agent は `submit_review`）

顧客が公開した API の操作を Agent のツールにするときは、ToolExposure を定義します。ToolExposure から作ったツールの姿（ToolDefinition。入出力の Schema・影響区分・timeout など）は GET /v1/agents/tools で読めます。詳しくは外部連携を見てください。

ツールの結果、文書の本文、受け取ったメールの本文は、信頼できない入力として扱います。そこに書かれた命令を権限の根拠にはしません。

実行の中の承認

メール・SMS・電話・顧客 API の更新のような外への操作は、Agent が呼んでもすぐには実行しません。宛先と内容を固定して digest を付けた ActionRequest にし、承認の Task を作ります。承認されると、実行台帳で一度だけ実行します。

誰が承認してよいかは、Agent の approval.decider が指す DeciderPolicy で、提案したときに決まります。書かなければ、すべての操作を人が決めます。
規則によっては、審査用の Agent が承認・却下・人への引き上げを返したり、事前のポリシーの承認で Task を作らずに承認したりできます。AI とポリシーの決定は、人の承認として数えません。
決定者の上書き（POST /v1/agents/decider-overrides）で、ReleaseBundle を待たずにツールの承認を人だけに戻せます。
結果が分からなくなった操作は unknown にし、送り直さずに人が照合します（POST /v1/agents/action-requests/{id}/reconcile）。

承認の流れの全体は承認にあります。

実行の起動

AgentRun は、次のどれかで始まります。

POST /v1/agents/runs に Agent の名前と入力を渡す
POST /v1/agents/requests（受付）に自由な文を渡し、Agent と入力を決めてもらう
Workflow の agent のステップ、スケジュール、組み込みチャットのメッセージ

import { createHaneClient, unwrap } from "@hane/sdk";

const client = createHaneClient({ baseUrl, token: async () => accessToken });
const run = await unwrap(
  client.POST("/v1/agents/runs", {
    body: { agent: "vehicle-check", input: { vehicle: "架空 300 あ 10-02" } },
  }),
);

shadow: true を付けると、外への操作と人への引き継ぎをせず、記録だけを残します。

上限と予算

1 回の実行の上限は定義の limits で決めます。プロジェクトと環境の 1 日（UTC）の予算は platform/v1alpha1 の Budget で決めます。

apiVersion: platform/v1alpha1
kind: Budget
metadata:
  name: daily-budget
spec:
  agentRunsPerDay: 200
  externalActionsPerDay: 50
  modelTokensPerDay: 200000
  alertAtPercent: 80

モデルを使う実行を作るときは、maxModelTokens の分を 1 日の予算から先に予約します。残りが足りなければ起動しません。今日の使用量は GET /v1/agents/budget で読めます。

会話のコンテキスト

組み込みチャットの会話では、メッセージ・実行の入力と結果・操作の状態を Hane が保存し、それをもとにモデルへ渡すコンテキストを組み立てます。CLI のセッションには依存しません。

/v1/agents/conversations/{id}/memory で、いまのコンテキストをバージョン付きの JSON として取得・保存し、保存した履歴から新しい会話を始められます。保存する JSON には RunToken・API キー・資格情報を含めません。取得した履歴で、いまの権限や実行台帳を上書きすることもありません。

評価

agents/v1alpha1 の EvalSuite に、入力と期待する結果の組を最大 50 件書きます。POST /v1/agents/evals で、件ごとに Agent を shadow で動かし、結果の項目を比べます。GET /v1/agents/evals/compare で、同じ EvalSuite の 2 回の評価を件ごとに比べられます。

apiVersion: agents/v1alpha1
kind: EvalSuite
metadata:
  name: lease-qa-eval
spec:
  agent: lease-qa
  passRate: 1
  cases:
    - name: 台帳にない契約
      input: { contract_no: C-9999 }
      expect: { status: handed_over }

次に読む