API ワークフローを構築する

Build a Monster Query API Workflow that calls the 5e SRD and returns structured monster data.

手順 1 - Monster Query API ワークフローを構築する

An API Workflow is a lightweight workflow published as an API endpoint. You build one that wraps the Open5e 5e SRD monster search: one input, one HTTP request, one output. Once published, it appears in the agent builder as a tool your agent can call.

このステップには 6 つのサブステップがあります。それを完了するのに10〜15分の予算を費やします。

新しい API ワークフロー プロジェクトを作成する

Select Create New from your Cloud Workspace. In the Start building dialog, choose API Workflow under Task automation.

Selecting the type creates the project immediately, with no name prompt, so you rename it in the next step.

ソリューションと既定のワークフローの名前を変更します。プロジェクト エクスプローラーで各名前のコンテキスト メニューを開き、[ 名前を変更] を選択します。

• ソリューション名: Monster Query - 5e SRD
• ワークフロー名: API Query - 5e Monsters

入力と出力を設定する

データ マネージャー (左側のレールのクリップボード アイコン) を選択して、ワークフローのデータ変数にアクセスします。

ワークフローに入力引数を 1 つ追加します。

名前	入力	Required	説明
searchName	文字列	はい	検索するモンスター名または名前の一部

出力引数を 1 つ追加します。

名前	入力	Required	説明
monsterResults	配列	はい	モンスター結果一覧

HTTP 要求を追加する

1. In the workflow canvas, select + between activities to open the activity menu. Select HTTP. The activity appears on the canvas as HTTP Request.
2. アクティビティのコンテキスト メニューを開き、[ 名前を変更] を選択します。と HTTP Request - Open5e Monster Query名前を付けます。
3. In the Properties pane, confirm Authentication is Manual authentication and Method is GET. Both are the defaults on a new activity, so there is normally nothing to change.
4. [ URL ] を https://api.open5e.com/v2/creatures/に設定します。
5. アクティビティの出力の名前を searchResultsに変更します。

Set the Query parameters property:

Open the Query parameters property, which opens a Dictionary editor with Key and Value columns, and add the following fields:

キー	値 (Value)
name__icontains	the searchName input argument - see the warning below
document__key	srd-2014
limit	10
fields	key,name,type,size,challenge_rating,alignment

警告:

name__icontains takes the searchName variable, and you must pick it from the variable picker rather than typing it. In the value field, start by typing @ to open the picker and select searchName - not using the picker will send the input as a literal string, and the API will return HTTP 200 with no results. The field then renders the value as a chip, and the stored value is $input.searchName.

各パラメーターの機能

• name__icontains: 大文字と小文字を区別しない部分一致。 dragon が「大人の赤龍」「若き青龍」他に帰ってくる
• document__key: srd-2014: filters to the official 5e SRD; without it, results include every publisher in the database, third-party content included
• limit: 10: 候補者の上限は 10 人。エージェントがコンテキストを氾濫させることなく推論を行うのに十分である
• fields: limits the response to only the fields the agent needs; the full v2 creature object is much larger and would waste token budget

警告:

Open5e ignores query parameters it does not recognize, and returns HTTP 200 anyway. Misspell document__key, or use the v1 spelling document__slug, and the filter is silently dropped: the call succeeds, the run is green, and the agent receives creatures from every publisher instead of the SRD. A goblin search returns 2 results with the filter applied and 29 without it, so check that the result count looks like a handful rather than a catalogue.

HTTP 要求のプロパティのリファレンス

このアクティビティは、標準の HTTP 構成要素を公開します。ほとんどの場合、呼び出すすべての API に対して構成します。次のようなパブリック API ではスキップするものもあります。

• 認証: OAuth 2.0、API キー、基本認証の事前構築済みオプション。Open5e は何も必要としないため、ここでは「手動認証」に設定します。認証済み API の場合は、適切なオプションを選択し、資格情報を指定します。
• ヘッダー: すべての要求で送信されるキーと値のペア。一般的な用途: トークンベースの API に Authorization: Bearer <token> し、応答形式と API のバージョニング ヘッダーを制御する Accept: application/json 。
• 本文: JSON、フォーム データ、または生のコンテンツを送信するために、POST、PUT、PATCH 要求とともに使用されます。クエリ パラメーターを介して URL にパラメーターを保持する GET 要求には適用されません。
• Query parameters: key/value pairs appended to the URL. To reference a workflow argument, enter @ to open the variable picker and select the argument - the field stores $input.<name> and displays it as a chip. @ is the picker's trigger character, not a reference syntax you can type out. See configuring activities for more on variables and expressions in Studio Web.
• Output (renamed to searchResults): receives the full HTTP response including status code, headers, and body. Renaming from the default keeps the Response expression readable.

応答を追加します。

1. In the workflow canvas, select + after the HTTP Request and select Response.

   The Response activity defines what the API Workflow returns to its caller (in this case, what the agent's tool receives when it invokes the workflow). Whatever you put in the response body here becomes the tool output the agent reasons over.

2. 応答本文を次のように設定します。

   {
     "monsterResults": $context.outputs.searchResults.content.results
   }
   

$context.outputs には、このワークフロー内のアクティビティからの名前付き出力がすべて含まれます。searchResults は、[HTTP 要求] アクティビティで名前を変更した出力変数です。 .content.results は、Open5e がデータをラップする応答エンベロープにナビゲートし、実際のモンスター エントリの配列に至ります。詳しくは、 UiPath のドキュメントの「Using Javascript to access workflow data」をご覧ください。

ワークフローをテストする

1. ツールバーから [ デバッグ ] を選択します。
2. 入力パネルで [ searchName ] を [ dragon ] または [ goblin ] に設定し、ワークフローを実行します。
3. 続行する前に、応答にモンスター エントリを含む monsterResults 配列が含まれていることを確認します。

A successful response contains up to 10 entries, each with key, name, alignment, and challenge_rating, plus nested type and size objects. Searching goblin returns Goblin and Hobgoblin. If you see an empty array, try a different search term; not every creature name has an exact match in the SRD.

フィードにパブリッシュする

パブリッシュすることにより、ワークフローがデプロイ可能なプロセスとして Orchestrator に登録されます。このため、Agent Builder の [利用可能なリソース ] リストで見つけることができます。 ビルダーには、Studio Web にローカルに保存された下書きではなく、ワークスペースからパブリッシュ済みのワークフローが表示されます。

1. ツールバーから [ パブリッシュ ] を選択します。
2. パブリッシュ ダイアログで [ 自分用 ] を選択して、個人用ワークスペース フィードにパブリッシュします。個人用ワークスペース フィードとは、Orchestrator ワークスペースに関連付けられたプライベート パッケージ リポジトリです。「自分の場合」をパブリッシュすると、このワークフローは自分だけに表示されるようになるので、開発やテストに適したスコープです。詳しくは、UiPath ドキュメントの「 個人用ワークスペース 」をご覧ください。
3. [ パブリッシュ ] を選択して確定します。

注:

手順 3 で [利用可能なリソース] にワークフローが表示されない場合 ワークフローは、ツールとして表示される前に、パブリッシュしておく必要があります (保存するだけでなく)。表示されない場合は、ここに戻ってパブリッシュが正常に完了したことを確認してから、Agent Builder を更新します。

---

ワークフローがパブリッシュされると、次のセクションで接続可能なツールとして Agent Builder で利用できるようになります。