Ability API エンドポイントの使い方

Agentriaで作成したアビリティ(Ability、ワークフロー)をAPIとして公開すると、外部サービスからこのAPIエンドポイント(Endpoint)を呼び出してアビリティを実行できます。Ability APIは、非同期実行、SSE(Server-Sent Events)ストリーミング、ステータス照会、リクエストのキャンセルに対応するREST APIです。

このガイドでは、各エンドポイントの呼び出し方と、実行結果を安全に取得する方法を案内します。

事前準備

• アビリティがAPIとして公開済みである必要があります。まだ公開していない場合は、先に🔗API公開ガイドを完了してください。

• 公開時に発行されたエンドポイントコード(api_endpoint)とAPIキー(Key)が必要です。

ベースURLと認証方式は、以下のすべてのエンドポイントに共通です。

ベースURL

すべてのリクエストにX-API-KEYヘッダーが必要です。

ステップ1：アビリティを非同期で実行する

アビリティを非同期(Async)で実行し、request_id(トランザクションID)を即座に応答として受け取ります。実行結果は、ステータス照会API(ステップ3)またはコールバック(Callback)URLで受け取れます。

Path Parameters

Headers

Request Body (multipart/form-data)

params_jsonには、アビリティに定義された入力パラメータに合わせたJSONオブジェクトを渡します。フィールドはアビリティごとに異なるため、対象アビリティの入力仕様を事前に確認してください。

{
  "inputData": "分析するテキストです。",
  "option1": "value1",
  "option2": 123
}

{
  "inputData": "分析するテキストです。",
  "option1": "value1",
  "option2": 123
}

{
  "inputData": "分析するテキストです。",
  "option1": "value1",
  "option2": 123
}

external_request_idは、クライアントがリクエスト送信前に自ら発行する識別子で、2つの役割があります。1つ目は、同じexternal_request_idで再リクエストされた場合、サーバーが同一リクエストとみなして409 Conflictで拒否するため、ネットワーク再試行などによる重複実行(冪等性、Idempotency)を防げる点です。2つ目は、クライアントがリクエスト送信時点で既にこの識別子を保持しているため、サーバーがレスポンスでrequest_idを返す前から、この値でリクエストを追跡・照会できる点です。

Response

成功すると、200 OKステータスとともにリクエストID(文字列)を応答として受け取ります。

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Error Responses

リクエスト例

curl -X POST "{host}/api/ability/my-ability" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData": "こんにちは"}' \
  -F 'callback_url=https://my-service.com/webhook' \
  -F 'external_request_id=order-12345' \
  -F 'debug=false'

curl -X POST "{host}/api/ability/my-ability" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData": "こんにちは"}' \
  -F 'callback_url=https://my-service.com/webhook' \
  -F 'external_request_id=order-12345' \
  -F 'debug=false'

curl -X POST "{host}/api/ability/my-ability" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData": "こんにちは"}' \
  -F 'callback_url=https://my-service.com/webhook' \
  -F 'external_request_id=order-12345' \
  -F 'debug=false'

ステップ2：SSEでリアルタイムストリーミングを受け取る

アビリティを実行しながら、SSEを通じて各ノードの実行結果をリアルタイムで受信します。

Path Parameters / Headers

ステップ1と同様に、api_endpointパスパラメータとX-API-KEYヘッダーが必要です。

Request Body (multipart/form-data)

Response

レスポンスのContent-Typeはtext/event-streamです。

レスポンスヘッダーX-Ability-Request-IdにリクエストIDが含まれます。最初のイベントを受信する前に接続が切れても、この値で再照会できます。これは最初のrequest_idイベントと同じ値です。

注意：X-Request-IdヘッダーはHTTPトレース用の別の値のため、X-Ability-Request-Idと混同しないよう注意してください。

各イベントは、標準のEventSource形式と互換性のない独自定義のSSE行形式で配信されます。空行でイベントが区切られます。

event_typeの値とbodyの形

event_typeがrequest_idであればストリーム開始を知らせるメタイベント、nodeであれば中間イベント、responseまたはerrorであれば最終イベントです。あるいは、body JSONのstatus値がCOMPLETED・FAILUREであれば最終イベントと判断できます。ストリームが終了すると接続は閉じられます。

ストリーム消失時の結果再照会

ネットワーク切断などで最終イベントを受け取れなかった場合、同じリクエストを再送信するとアビリティが再実行されてしまうため、再照会を使う必要があります。サーバーはストリームの接続状態に関わらず実行を完了し、結果を記録します。

• request_idイベント(またはX-Ability-Request-Idヘッダー)で受け取ったリクエストIDで、GET /{api_endpoint}/{request_id}/resultをポーリングします(ステップ3参照)。

• external_request_idを付与していた場合は、GET /{api_endpoint}/external/{external_request_id}/resultでも照会できます(ステップ3参照)。

statusがCOMPLETED・FAILURE・CANCELEDになるまでポーリングします。同じexternal_request_idで再送信すると409 Conflictで拒否されるため、外部IDを併用することで誤った重複実行も防げます。

リクエスト例

curl -N -X POST "{host}/api/ability/my-ability/sse" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData":"こんにちは"}' \
  -F 'debug=false'

curl -N -X POST "{host}/api/ability/my-ability/sse" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData":"こんにちは"}' \
  -F 'debug=false'

curl -N -X POST "{host}/api/ability/my-ability/sse" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData":"こんにちは"}' \
  -F 'debug=false'

• N(-no-buffer)オプションは必須です。付けない場合、チャンクがまとめて届いてしまいます。

実際のレスポンス例(ワイヤー形式)

JavaScript クライアント例

const formData = new FormData();
formData.append('params_json', JSON.stringify({ inputData: 'こんにちは' }));
formData.append('debug', 'false');

const response = await fetch(`${host}/api/ability/my-ability/sse`, {
  method: 'POST',
  headers: { 'X-API-KEY': 'your-api-key' },
  body: formData
});

// ストリーム消失時に GET .../{requestId}/result で再照会するために使用。最初の request_id イベントでも更新される。
let requestId = response.headers.get('X-Ability-Request-Id');

// 1回の read() で複数のイベントがまとまって届くことがあるため、行単位でバッファリングして解析する必要がある。
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let currentEvent = null;

const events = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });

  let nl;
  while ((nl = buf.indexOf('\n')) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);

    if (line === '') {
      currentEvent = null; // イベントの区切り
      continue;
    }
    if (line.endsWith(':')) {
      currentEvent = line.slice(0, -1); // "node" | "response" | "error"
      continue;
    }
    // body 行 — JSON.parse を試み、失敗したら raw string として扱う
    let body;
    try { body = JSON.parse(line); } catch { body = line; }

    if (currentEvent === 'request_id') {
      requestId = body; // プレーンな UUID 文字列
    } else if (currentEvent === 'node') {
      console.log('[node]', body.ability_node_id, body.ability_node_name, body.results);
    } else if (currentEvent === 'response' || currentEvent === 'error') {
      events.push(body);
      console.log(`[${currentEvent}] status=${body.status}`, body.results);
    }
  }
}

// 最終結果 = events[events.length - 1]
const final = events[events.length - 1];
if (final?.status === 'FAILURE') {
  console.error('失敗：', final.failure_reason);
}

// 最終イベントを受け取れずにストリームが切れた場合 — 再送信(再実行)ではなく再照会
if (!final && requestId) {
  const res = await fetch(`${host}/api/ability/my-ability/${requestId}/result`, {
    headers: { 'X-API-KEY': 'your-api-key' }
  });
  const result = await res.json(); // status が COMPLETED/FAILURE になるまでポーリング
}

const formData = new FormData();
formData.append('params_json', JSON.stringify({ inputData: 'こんにちは' }));
formData.append('debug', 'false');

const response = await fetch(`${host}/api/ability/my-ability/sse`, {
  method: 'POST',
  headers: { 'X-API-KEY': 'your-api-key' },
  body: formData
});

// ストリーム消失時に GET .../{requestId}/result で再照会するために使用。最初の request_id イベントでも更新される。
let requestId = response.headers.get('X-Ability-Request-Id');

// 1回の read() で複数のイベントがまとまって届くことがあるため、行単位でバッファリングして解析する必要がある。
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let currentEvent = null;

const events = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });

  let nl;
  while ((nl = buf.indexOf('\n')) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);

    if (line === '') {
      currentEvent = null; // イベントの区切り
      continue;
    }
    if (line.endsWith(':')) {
      currentEvent = line.slice(0, -1); // "node" | "response" | "error"
      continue;
    }
    // body 行 — JSON.parse を試み、失敗したら raw string として扱う
    let body;
    try { body = JSON.parse(line); } catch { body = line; }

    if (currentEvent === 'request_id') {
      requestId = body; // プレーンな UUID 文字列
    } else if (currentEvent === 'node') {
      console.log('[node]', body.ability_node_id, body.ability_node_name, body.results);
    } else if (currentEvent === 'response' || currentEvent === 'error') {
      events.push(body);
      console.log(`[${currentEvent}] status=${body.status}`, body.results);
    }
  }
}

// 最終結果 = events[events.length - 1]
const final = events[events.length - 1];
if (final?.status === 'FAILURE') {
  console.error('失敗：', final.failure_reason);
}

// 最終イベントを受け取れずにストリームが切れた場合 — 再送信(再実行)ではなく再照会
if (!final && requestId) {
  const res = await fetch(`${host}/api/ability/my-ability/${requestId}/result`, {
    headers: { 'X-API-KEY': 'your-api-key' }
  });
  const result = await res.json(); // status が COMPLETED/FAILURE になるまでポーリング
}

const formData = new FormData();
formData.append('params_json', JSON.stringify({ inputData: 'こんにちは' }));
formData.append('debug', 'false');

const response = await fetch(`${host}/api/ability/my-ability/sse`, {
  method: 'POST',
  headers: { 'X-API-KEY': 'your-api-key' },
  body: formData
});

// ストリーム消失時に GET .../{requestId}/result で再照会するために使用。最初の request_id イベントでも更新される。
let requestId = response.headers.get('X-Ability-Request-Id');

// 1回の read() で複数のイベントがまとまって届くことがあるため、行単位でバッファリングして解析する必要がある。
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let currentEvent = null;

const events = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });

  let nl;
  while ((nl = buf.indexOf('\n')) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);

    if (line === '') {
      currentEvent = null; // イベントの区切り
      continue;
    }
    if (line.endsWith(':')) {
      currentEvent = line.slice(0, -1); // "node" | "response" | "error"
      continue;
    }
    // body 行 — JSON.parse を試み、失敗したら raw string として扱う
    let body;
    try { body = JSON.parse(line); } catch { body = line; }

    if (currentEvent === 'request_id') {
      requestId = body; // プレーンな UUID 文字列
    } else if (currentEvent === 'node') {
      console.log('[node]', body.ability_node_id, body.ability_node_name, body.results);
    } else if (currentEvent === 'response' || currentEvent === 'error') {
      events.push(body);
      console.log(`[${currentEvent}] status=${body.status}`, body.results);
    }
  }
}

// 最終結果 = events[events.length - 1]
const final = events[events.length - 1];
if (final?.status === 'FAILURE') {
  console.error('失敗：', final.failure_reason);
}

// 最終イベントを受け取れずにストリームが切れた場合 — 再送信(再実行)ではなく再照会
if (!final && requestId) {
  const res = await fetch(`${host}/api/ability/my-ability/${requestId}/result`, {
    headers: { 'X-API-KEY': 'your-api-key' }
  });
  const result = await res.json(); // status が COMPLETED/FAILURE になるまでポーリング
}

参考(Pythonクライアント)： 上記と同様の行バッファリングが必要です。httpx.AsyncClient.stream()のaiter_lines()は1行ずつ値を返すため、node: / response: / error:の接頭行はJSONパースエラーとしてスキップし、JSON行のみパースすれば構いません。ただし、request_idイベントのbody(プレーンなUUID)はJSONではないため、再照会用のIDが必要な場合は直前の行がrequest_id:かどうかを追跡するか、レスポンスヘッダーX-Ability-Request-Idを使用してください。

ステップ3：リクエストのステータス・結果を照会する

非同期実行リクエストの処理ステータスと結果を照会します。

両方のエンドポイントは同じレスポンスを返します。

Path Parameters

Response

成功すると、200 OKステータスとともに以下の形式の結果を応答として受け取ります。

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_request_id": null,
  "chat_room_id": null,
  "status": "COMPLETED",
  "failure_reason": null,
  "results": {
    "output": "アビリティの実行結果"
  },
  "artifact_metadata_json": null,
  "request_params_json": "{\"inputData\":\"こんにちは\"}",
  "result_metadata_json": null,
  "requested_time": "2026-01-15T10:30:00",
  "updated_time": "2026-01-15T10:31:00"
}

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_request_id": null,
  "chat_room_id": null,
  "status": "COMPLETED",
  "failure_reason": null,
  "results": {
    "output": "アビリティの実行結果"
  },
  "artifact_metadata_json": null,
  "request_params_json": "{\"inputData\":\"こんにちは\"}",
  "result_metadata_json": null,
  "requested_time": "2026-01-15T10:30:00",
  "updated_time": "2026-01-15T10:31:00"
}

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_request_id": null,
  "chat_room_id": null,
  "status": "COMPLETED",
  "failure_reason": null,
  "results": {
    "output": "アビリティの実行結果"
  },
  "artifact_metadata_json": null,
  "request_params_json": "{\"inputData\":\"こんにちは\"}",
  "result_metadata_json": null,
  "requested_time": "2026-01-15T10:30:00",
  "updated_time": "2026-01-15T10:31:00"
}

external_request_idは、リクエスト時に外部IDを付与した場合のみ値が入り、それ以外はnullです。

statusの値

リクエスト例

curl -X GET "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status" \
  -H "X-API-KEY: your-api-key"

curl -X GET "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status" \
  -H "X-API-KEY: your-api-key"

curl -X GET "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status" \
  -H "X-API-KEY: your-api-key"

外部リクエストIDで照会する

リクエスト時にexternal_request_idを付与していた場合、その値でも同じレスポンスを照会できます。

curl -X GET "{host}/api/ability/my-ability/external/order-12345/status" \
  -H "X-API-KEY: your-api-key"

curl -X GET "{host}/api/ability/my-ability/external/order-12345/status" \
  -H "X-API-KEY: your-api-key"

curl -X GET "{host}/api/ability/my-ability/external/order-12345/status" \
  -H "X-API-KEY: your-api-key"

ステップ4：リクエストをキャンセルする

進行中の非同期リクエストをキャンセルします。

Path Parameters

Response

成功すると、200 OKステータスとともにtrueを応答として受け取ります。

Error Responses

リクエスト例

curl -X DELETE "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-KEY: your-api-key"

curl -X DELETE "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-KEY: your-api-key"

curl -X DELETE "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-KEY: your-api-key"

複数のリクエストを一括でキャンセルする

複数の非同期リクエストを一度にキャンセルすることもできます。

curl -X DELETE "{host}/api/ability/my-ability?request_ids=id-001&request_ids=id-002&request_ids=id-003" \
  -H "X-API-KEY: your-api-key"

curl -X DELETE "{host}/api/ability/my-ability?request_ids=id-001&request_ids=id-002&request_ids=id-003" \
  -H "X-API-KEY: your-api-key"

curl -X DELETE "{host}/api/ability/my-ability?request_ids=id-001&request_ids=id-002&request_ids=id-003" \
  -H "X-API-KEY: your-api-key"

利用フローの全体像

用途に応じて、以下の4つのフローのいずれかを選んで使用します。

フロー1：非同期実行＋ポーリング(Polling)

フロー2：非同期実行＋コールバック(Callback)

コールバックペイロードの例です。

// external_request_id を付与したリクエストのコールバック — キーを含む
{
  "request_id": "a1b2c3d4-...",
  "external_request_id": "order-12345",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id を付与していないリクエストのコールバック — キー自体が省略される
{
  "request_id": "a1b2c3d4-...",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id を付与したリクエストのコールバック — キーを含む
{
  "request_id": "a1b2c3d4-...",
  "external_request_id": "order-12345",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id を付与していないリクエストのコールバック — キー自体が省略される
{
  "request_id": "a1b2c3d4-...",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id を付与したリクエストのコールバック — キーを含む
{
  "request_id": "a1b2c3d4-...",
  "external_request_id": "order-12345",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id を付与していないリクエストのコールバック — キー自体が省略される
{
  "request_id": "a1b2c3d4-...",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

外部IDがないリクエストは、external_request_idキー自体をコールバックペイロードに含めません。既存の方式がそのまま維持されるため、以前の連携コードとも互換性があります。

フロー3：リアルタイムストリーミング

フロー4：リクエストのキャンセル

次のステップ

Ability APIエンドポイントの使い方を確認しました。

これで、外部サービスからアビリティを直接呼び出し、実行結果を取得できます。

• 🔗 API公開 ガイドで、エンドポイントとAPIキーの発行手順を再確認できます。

よくある質問

Ability APIとは何ですか?

Ability APIは、外部サービスがAgentriaで作成したアビリティ(Ability)をREST API経由で実行できるようにする機能です。非同期実行、SSEストリーミング、ステータス・結果照会、リクエストのキャンセルに対応しており、すべてのリクエストはX-API-KEYヘッダーで認証されます。

Ability APIはどのような時に使いますか?

外部のバックエンドサーバーや別のサービスから、AgentriaのUIを経由せずにアビリティの実行結果を受け取りたい場合に使用します。例えば、自社サービスのイベント発生をきっかけにアビリティをトリガーしたい場合や、実行結果を自社システムに自動で反映したい場合に適しています。

アビリティの実行結果はどのように受け取れますか?

3つの方法があります。GET /{api_endpoint}/{request_id}/status(または/result)でステータスをポーリングする方法、リクエスト時にcallback_urlを指定して完了時にコールバックで結果を受け取る方法、/sseエンドポイントで実行中の各ノードの結果をリアルタイムでストリーミング受信する方法です。

リアルタイムストリーミング(SSE)の途中で接続が切れた場合はどうなりますか?

サーバーはストリームの接続状態に関わらずアビリティの実行を継続して完了させ、結果を記録します。接続が切れて最終イベントを受け取れなかった場合は、同じリクエストを再送信せず、request_id(またはexternal_request_id)でステータス・結果照会APIをポーリングして結果を取得する必要があります。同じリクエストを再送信すると、アビリティが再実行されてしまいます。

Ability APIを使う前に何が必要ですか?

アビリティがAPIとして公開済みである必要があり、公開時に発行されるエンドポイントコード(api_endpoint)とAPIキーが必要です。まだ公開していない場合は、先にAPI公開ガイドで公開手順を完了する必要があります。