AIエージェントを自然な英語で任意のAPIに接続する

Piotr Grudzień
公開日 更新日 読了時間：約26分
AIエージェントを自然な英語で任意のAPIに接続します。入力した1文が、レビュー済みで文書化されたAPI Actionになります

Quickchat AIのAPI Action builderは、自然な英語の1文からAIエージェントをREST APIに接続します。呼び出したいAPIを説明します。たとえば「注文の配送状況を調べ、顧客に到着予定を伝える」と入力すると、Web検索付きのLLMがそのAPIのライブドキュメントを読み、メソッド、URL、ヘッダー、パラメータ、そしてエージェントにいつ使うべきかを伝える説明を埋めた、完全に動作するアクションを組み立てます。読み取ったドキュメントを引用し、実在するエンドポイントを確認できない場合は、推測せずにその旨を伝えます。

このガイドでは、無料アカウントで入力した2つの文から2つのライブアクションを作成し、Inboxに記録された実際の呼び出しで両方を確認します。途中で、API呼び出しがエージェントにとって実際に何をするのかと、この機能が動作する仕組みである「function calling」とは何かも説明します。

以下の内容はすべて、実際のエージェントで作成してテストしたものです。すべてのスクリーンショット、生成されたフィールド、API呼び出しはそのビルドからのものであり、同じ手順を再現できます。

旅行者がインターラーケンの天気について質問し、Wanderlarkエージェントがライブ予報の数値で回答している 完成した結果です。旅行者が週末について質問し、エージェントが会話中に天気APIを呼び出して、ライブの数値で回答します。

作成するもの

Wanderlark Toursという架空の少人数アルプスハイキング事業者向けのサポートエージェントを作成します。このエージェントは自身の知識から回答し、会話中に2つの実在するAPIを呼び出します。両方を作成し、テストし、ライブ呼び出しを確認するまでに約15分かかります。

  1. Open-Meteoに対する天気予報の参照を、1文から作成します。キー不要なので、Quickchatアカウントだけで完了できます。
  2. Wanderlarkの星空観察オプション向けに、api.nasa.govに対するNASAのAstronomy Picture of the Dayを作成します。こちらはAPIキーが必要です。そのためここで扱います。有効化がキーを貼り付けるまでブロックされる、[[secret]]プレースホルダーの流れを学ぶためです。

また、builderが意図的に作成を拒否する文も入力します。失敗の仕方を見ることは、いつ信頼できるかを理解する一部だからです。

必要なもの:

  • 無料のQuickchat AIアカウント（こちらから登録）。
  • コードもサーバーも不要です。2つ目のアクションにはNASA APIキーが必要です。NASAは試用向けに共有のレート制限付きDEMO_KEYを運用しており、スクリーンショットではこれを使っています。個人キーはapi.nasa.govで即時発行されます。

AIエージェントがAPIを呼び出すとはどういう意味ですか？

APIを呼び出せるエージェントは、会話中に実際のシステムから情報を取得したり、システム内の情報を変更したりして、その結果で回答できます。チャットボットはビジネスを説明できます。APIを呼び出すエージェントは、ビジネス内で行動できます。

エンドユーザー側では、回答以外に変化はありません。旅行者が「土曜日のインターラーケンの天気はどうなりますか？」と尋ねると、数秒間の入力中インジケータが表示され、その後、実際の気温を含む返信が表示されます。ツール、リクエスト、JSONペイロードは見えません。その間の2秒は次のように動いています。

旅行者に見える内容と見えないステップを示すタイムライン。モデルがアクションを選び、値を埋め、QuickchatがHTTPリクエストを送信し、回答がレスポンスを使う 旅行者に見えるのは質問と回答です。その間に、モデルがアクションを選び、値を埋め、Quickchatが実際のHTTPリクエストを実行しました。約2秒のうち280 msです。

その待ち時間に訪問者へ何を表示するかも設定できます。各アクションにはthinking messageを設定できます。これは、呼び出しの実行中にWebサイトウィジェットが汎用の「Thinking…」の代わりに表示する短い行です。Wanderlarkの予報アクションではこれを設定しているため、その2秒間に旅行者が実際に見る内容は次のとおりです。

Webサイトウィジェットの呼び出し中の画面。訪問者の質問とカスタムthinking message「Checking the live forecast for you...」が表示されている 呼び出し中の旅行者側の表示です。カスタムの思考中メッセージが、返信が表示される場所で揺らぎます。この行は後でアクションエディタで設定します。

これは天気に固有のものではありません。HTTP APIを公開している任意のシステムを、アクションの接続先にできます。注文データベース、予約システム、CRM、チケット管理ツール、メッセージングプラットフォームなどです。参照はライブデータで質問に答え、書き込みは何かを変更して記録を残します。

2行に並んだ12個のアクション例。注文ステータス、在庫水準、天気、為替レート、フライトステータス、配送などの参照と、チケット作成、枠の予約、Slack通知、CRM連絡先、返品開始、人間への呼び出しなどの書き込み 各タイルは、説明された1つのHTTPリクエストです。このガイドでは参照のうち2つを作成します。書き込みパターンは末尾にリンクしたガイドで扱います。

従来の問題は、これらを接続するにはAPIドキュメントを読み、リクエストを手作業で入力する必要があったことです。その部分をbuilderが取り除きます。

自然な英語のaction builderはどのように動作しますか？

APIを1文で説明すると、ライブWeb検索付きのLLMがその文を完全なアクションに変換します。生成中にAPIドキュメントを検索し、メソッド、URL、ヘッダー、クエリパラメータ、そしてエージェントにいつ呼び出すべきかを伝える説明を下書きし、読み取ったドキュメントページへのリンク付きで結果を返します。生成には約30秒かかり、準備ができると結果がダイアログで開きます。

入力された文からライブドキュメント検索を経て組み立てられたアクションに至る組立ライン。レビューゲートと、APIを確認できない場合のfail-closed出口がある builderはドキュメントで確認できたものだけを出力します。確認できなかったものはプレースホルダーまたは拒否になり、推測にはなりません。

安全に使うための性質が3つあります。

  • 有効化するまで何も実行されません。 生成されたすべてのアクションはオフの状態で届き、確認できます。
  • 不明点は推測ではなくプレースホルダーになります。 モデルが呼び出しごとに埋める値（日付、都市など）は{{param}}の空欄になります。あなただけが知っている定数（APIキーなど）は[[secret]]の空欄になり、置き換えるまで有効化はブロックされます。
  • 作業内容を表示します。 結果には読み取ったドキュメントページが一覧表示され、それぞれにそのページで何を確認したかのメモが付きます。レビューは信頼ではなく根拠から始まります。

結果ダイアログのSourcesセクション。Open-Meteoのドキュメントページとドキュメントセクションが、それぞれ何を確認したかのメモ付きで引用されている このガイドで後ほど使う同じ天気文の2回目の生成からの引用です。ドキュメントページとAPIセクション、それぞれにbuilderがそこで確認した内容が付いています。

ステップ1: 旅行エージェントを作成する

まずエージェントを作成します。アクションには所属先が必要です。登録後、エージェントに名前を付けます（このビルドではWanderlark）。そしてダッシュボードのIdentity配下にあるAI Main Promptフィールドで役割を与えます。

あなたはWanderlark Toursのアシスタントです。Wanderlark Toursは少人数向けのアルプスハイキングツアー運営会社です。Wanderlarkは3つのガイド付きツアー、Interlaken Classic、Zermatt Highline、Dolomites Traverseと、星空観察オプションのDark-Sky Nightsを運営しています。旅行者がツアーを選び、日程、料金、難易度、持ち物を理解できるように支援し、予約とキャンセルに関する質問に答えてください。温かく、実用的で、簡潔にし、回答は短く保ってください。

Wanderlarkについて実際に知っていることだけから回答してください。詳細がない場合は、推測するのではなく、その詳細は持っていないと伝え、Wanderlarkチームにつなぐことを提案してください。

次に、Knowledge Baseにいくつか事実を追加し、回答の元になる情報を持たせます。デモでは5つの短い記事（ツアーと料金、Dark-Sky Nightsオプション、予約とキャンセル、持ち物、集合場所）を使っています。全文は末尾近くのコピーブロックにあります。アクションが存在した後で、このプロンプトにアクション固有の2行を追加します（後述）。プロンプトと知識をゼロから設定する手順が必要な場合は、下でリンクしている基本レシピ記事で順を追って説明しています。

ステップ2: APIを1文で説明する

サイドバーでActions & MCPsを開き、Add Actionをクリックして、メニューの最初の項目であるAPI Actionを選択します。

ActionsページのAdd Actionメニュー。API Actionが最初の項目として表示されている カスタムアクションはActions & MCPs配下にあります。API Action項目を選ぶと、説明用ダイアログが開きます。

開いたダイアログでは、このアクションが呼び出すAPIを説明し、エンドポイント名またはドキュメントへのリンクを指定するよう求められます。天気アクションの正確な文は次のとおりです。

Open-Meteo API（ドキュメント: https://open-meteo.com/en/docs）から場所の日別天気予報を取得し、旅行者が当社の目的地の天気について尋ねたときに、エージェントが尋ねられた日の実際の気温と降雨確率で回答できるようにしてください。

API Actionダイアログ。天気の文がdescriptionフィールドに入力されている 1文です。どのAPIか、ドキュメントリンク、エージェントがいつ使うか、結果で何をするかを含みます。

この文には、良い説明に必要な3つの要素があります。

  1. 具体的なAPI、エンドポイント、またはドキュメントURL。 「Open-Meteo API」とドキュメントリンクにより、builderが読む実体が与えられます。これがない場合、アクションではなく拒否が返ります。
  2. エージェントがいつ使うべきか。 「旅行者が天気について尋ねたとき」という部分は、後でアクションをトリガーする説明に、ほぼそのまま入ります。
  3. 結果で何をするか。 「実際の気温と降雨確率で回答する」が、エージェントのレスポンス利用方法を形作ります。

フィールドは最大500文字まで入力できます。良い説明に必要な量より十分に余裕があります。このガイドの各文は十分余裕を持って収まります。

Submitをクリックします。ダイアログが閉じ、アクションを準備中であることを通知するトーストが表示され、約30秒後に結果ダイアログが自動的に開きます。

文を入力し、送信し、結果ダイアログが表示されるアニメーション 待ち時間を短縮した実時間のフローです。説明し、送信し、返ってきた内容を確認します。

生成されたアクションの中身

結果ダイアログはレビュー画面です。左側には新しいアクションのプレビューカードがあり、Actionsページで表示される状態と同じです。右側にはDetailsがあります。builderが何を作成したか、実行時にモデルがどの値を埋めるか、文で未指定だった部分について何を仮定したかを説明します。その下にはSourcesがあります。読み取ったドキュメントへのリンクです。

天気アクションの結果ダイアログ。プレビューカードとDetailsの説明が表示されている builderはフィールドごとに作業内容を説明します。ダイアログをスクロールすると、Sourcesセクションにこのアクションで読み取ったものが一覧表示されます。Open-MeteoのドキュメントページとGitHub上のプロジェクトのOpenAPI specが、それぞれ何を確認したかのメモ付きで表示されます。

天気の文に対して、builderはget_open_meteo_daily_forecastという名前のアクションを生成しました（builderの名前はエンジニアが書いたように見えます。エディタで変更できます）。プレビューのEdit Actionをクリックすると、埋められたすべてのフィールドを確認できます。

生成された名前、パラメータテーブル、APIエンドポイントフィールドを表示しているアクションエディタ 手作業で作成するアクションが持つすべての項目が埋まっています。名前、「What to ask the user first」配下のパラメータテーブル、エンドポイントです。

上から順に読むと次のとおりです。

  • API Action Name: モデルがツール名として見るものです。
  • What to ask the user first: パラメータテーブルです。builderは7つのパラメータを宣言しました。それぞれに型と説明があります。latitude、longitude、timezone、start_date、end_date、さらに任意の単位です。これらはモデルが呼び出しごとに埋める{{param}}値です。ここにないものにも注意してください。「city」パラメータはありません。builderはOpen-Meteoが実際に動く方法、つまり座標でエンドポイントを接続し、地理の解釈はモデルに任せました。すぐに、それらの座標を正しく埋める様子を見ます。
  • API Endpoint: GET https://api.open-meteo.com/v1/forecastで、クエリパラメータが接続されています。builderが選んだ予報変数のdailyリストのような固定値はリテラルのままです。モデルが埋める値は色付きの{{...}}チップとして表示されます。

API Endpointセクション。GETメソッド、URL、固定値とパラメータチップが混在するクエリパラメータが表示されている 固定部分は固定のままです。色付きチップはモデルが埋める空欄です。チップは、どこから値が来るかを示すUI自身の凡例です。

エンドポイントエディタの4つ目のタブであるTest Responseは、アクションが訪問者に接する前に実際のリクエストを発行します。各パラメータには「Your test value」フィールドがあります。妥当な値を入力し、再生ボタン（「Test the API」）を押すと、実際のレスポンスがステータスコード付きで返ります。Show cURLトグルを開くと、その言葉どおり、「このAI Actionがこれらのパラメータで実行されるときにトリガーされる正確なHTTPリクエスト」が表示されます。このビルドでのテストは、再びインターラーケンの座標です。

実行後のTest Responseタブ。200 Okバッジ付きのJSONレスポンスと、完全に置換されたリクエストを表示する展開済みcURLブロック エディタ内から発行されたOpen-Meteoからの実際の200です。解決済みリクエストが下に明示されています。確認し、テストし、その後有効化します。

  • API Action Description: エージェントがいつこのアクションを使うかを決める文です。builderはあなたの「旅行者が尋ねたとき」の節からこれを書きました。このフィールドは実行時に最も多くの仕事をします。エージェントが誤ったタイミングでアクションを実行する場合、最初に調整する場所です。
  • Thinking message: 先ほどのタイムラインにある、旅行者側に表示される行です。エディタでは「このアクションが呼び出されたときにユーザーに表示されるthinking preloader」と説明されています。Wanderlarkの予報アクションでは「Checking the live forecast for you…」に設定しています。

アクションはオフの状態で届きました。エディタで開くと、Quickchatはアクションがオフであることを示すバナーとEnableボタンを表示します。またはActionsページのカードでスイッチを切り替えます。このアクションには埋めるものがなかったため、すぐに有効化されます。

このActionがオフであることを示すエディタバナー。Enableボタンがある まず確認し、その後オンにします。これを行うまで、何も呼び出されません。

同じアクションをフィールドごとに手作業で作成し、各ボックスを基礎から理解したい場合は、基礎ガイドであるBuild a Free AI Agent That Takes Actionsを参照してください。builderと手動エディタは同じ種類のアクションを生成します。この記事は生成ルートです。

ステップ3: テストして呼び出しを確認する

アクションをトリガーするはずの質問をエージェントにします。ここでのトランスクリプトはQuickchatのテストパイプラインを通じて実行され、通常の会話と同様にInboxに記録されています。自分のアカウントでは、サイドバーのAI Previewペインで同じループをブラウザ内で利用できます。

テストメッセージは次のとおりです。

こんにちは。来週末にInterlaken Classicに参加します。7月25日土曜日と7月26日日曜日のインターラーケンの天気はどうなりますか？

エージェントは実際の予報で回答しました。土曜日は約27.7°Cでほぼ雨なし、日曜日は涼しく最大18 mmの雨が見込まれるという内容と、Knowledge Baseから引いた持ち物の助言です。

証跡はInboxにあります。エージェントの返信の下に**「1 action called」**マーカーがあります。展開すると、何が起きたかの完全な記録が表示されます。

展開されたアクション呼び出しカード。アクション名、HTTP 200、280 ms、モデルが埋めた各パラメータ、JSON結果が表示されている 呼び出し記録です。get_open_meteo_daily_forecast、HTTP 200、280 ms、そしてモデルが埋めたすべての値です。

モデルが選んだパラメータを読んでください。latitude: 46.6863, longitude: 7.8632, timezone: Europe/Zurich, start_date: 2026-07-25, end_date: 2026-07-26です。誰も座標を入力していません。旅行者は「インターラーケン」と言い、モデルはそれをAPIが必要とする値に変換しました。町に到達するのに十分な精度です。これがシステムの判断側が仕事をしている部分です。決定論的な側（URL、メソッド、固定のdaily変数リスト）は、レビュー済みのとおりに送信されました。

AIエージェントにおけるfunction callingとは何ですか？

上の証跡は、業界でfunction callingと呼ばれる仕組みを示しています。言語モデルが会話中に文ではなく、事前定義されたツールへの構造化呼び出しを出力することを選び、プラットフォームがそれを実行し、モデルが結果を手元に置いて続行します。

実際の天気呼び出しにおけるfunction callingを示す3つのゾーン。モデルが判断して値を埋め、Quickchatが固定リクエストを実行し、APIが通常のJSONで回答する このガイドの実際の呼び出しにおけるfunction callingです。モデルが生成するのは構造化された値だけです。リクエストはプラットフォームが管理します。APIは通常のHTTPです。

図からいくつかの点が分かります。

  • モデルが判断し、プラットフォームが実行します。 モデルがOpen-Meteoにバイト列を送ることはありません。{"latitude": 46.6863, ...}を生成し、Quickchatがそれらの値をレビュー済みのリクエストに挿入します。固定した部分、URL、メソッド、シークレットは、モデルが変更できるものではありません。
  • 「Tool calling」は同じものです。 2つの名称は1つの仕組みを表します。tool callingは、より新しく一般的な用語です。AI Actionはツール定義です。名前、説明、パラメータテーブルが、モデルが呼び出すかどうか、どう呼び出すかを判断するときに読むものです。だから説明フィールドが非常に重要です。概念的には、モデルが見る定義全体は次のようなものです。
name:        get_open_meteo_daily_forecast
description: 旅行者が目的地の特定の今後の日の天気について尋ねたときに、このアクションを使用します...
parameters:  latitude (number, required), longitude (number, required), timezone (text, required), start_date (text, required), end_date (text, required), temperature_unit (text), precipitation_unit (text)
  • API側は通常どおりです。 Open-MeteoはこのためにAIサポートを追加していません。HTTPを話しJSONを返す任意のエンドポイントをツールにできます。そのため、1文のレシピは自社バックエンドにも一般化できます。

主要なモデルファミリーはすべてこの仕組みをサポートしています。プラットフォーム間で異なるのは、誰がツール定義を書くかです。開発者プラットフォームやカスタムGPT actionsでは、それをスキーマとして手作業で書くのはあなたです。ステップ2で使ったbuilderは、スキーマを書く作業を取り除いたfunction callingです。あなたの文がツール定義になりました。MCPなどのプロトコルからカスタムエンドポイントまで、この領域のエンジニアリング視点については、APIs for AI Agents: From MCP to Custom Endpointsを参照してください。

ステップ4: キーが必要なAPI

実際のAPIの多くは認証情報を必要とします。ここでbuilderの2つ目のプレースホルダー種別が使われます。Wanderlarkの星空観察オプションは自然な題材です。Dark-Sky Nightsの参加者は、NASAのAstronomy Picture of the Dayについてよく尋ねます。

Add Actionを開き、もう一度API Actionを選択し、今度はキーを自分で提供することを最初からbuilderに伝えて説明します。

NASA APOD API（GET https://api.nasa.gov/planetary/apod）からNASAのAstronomy Picture of the Dayを取得し、Dark-Sky Nightsオプションに関心のあるゲストが今夜の注目天文写真について尋ねたときに、そのタイトルと何が写っているかを聞けるようにしてください。NASA APIキーは自分で提供します。

NASAの文が入力されたAPI Actionダイアログ 「APIキーは自分で提供する」と書くことで、builderに認証を推測させず、明確な空欄を残すよう伝えます。

約30秒後に結果ダイアログが開きます。1つ重要な違いがあります。「Replace before activating」という琥珀色のパネルがあり、そこに[[nasa_api_key]]が1つだけ表示されています。プレビューカードには赤いIncompleteバッジがあり、有効化スイッチはオフで、オフのままです。

NASAアクションの結果ダイアログ。APIキープレースホルダーを列挙した琥珀色のReplace before activatingパネルとIncompleteバッジが表示されている builderはアクション全体を接続し、埋められない空欄を1つ残しました。あなたのキーです。置き換えるまで、アクションはオンにできません。

Actionsページでは、スイッチは完全に無効化され、理由を説明するツールチップが表示されます。

無効化されたスイッチと、アクションが有効ではないため不足フィールドを埋めるよう示すツールチップがあるアクションカード [[secret]]が残っている間、有効化はプラットフォームレベルでブロックされます。キーが入る場所にプレースホルダーがあるアクションは、午前3時に失敗できません。実行できないからです。

2種類のプレースホルダーには異なる所有者がいます。

NASA URL上の2種類のプレースホルダー。毎回モデルが埋めるdate paramと、一度貼り付けるapi key secret 1つのURLに両方の種類があります。{{date}}はモデルの空欄で、会話から呼び出しごとに埋められます。[[nasa_api_key]]はあなたのもので、一度貼り付けます。

これを埋めます。NASAは個人キーを即時発行します（api.nasa.govで名前とメールを入力すると、キーがメールで届きます）。試用向けの共有DEMO_KEYもドキュメント化されています。このビルドではそれを使っています。

  1. アクションのカードでEdit Actionをクリックし、API EndpointセクションのQuery Paramsタブを開きます。
  2. api_key行に琥珀色の[[nasa_api_key]]チップがあります。値をクリックし、自分のキーで置き換えます。
  3. Save changesをクリックします。

Query Paramsタブのビフォーアフター。琥珀色のプレースホルダーチップ、その後に実際のキーが貼り付けられている プレースホルダーは通常の編集可能な値です。置き換えて保存します。

次に、不要だった操作に注目してください。スイッチを切り替える必要はありませんでした。保存によって読み取り専用のGETアクションが初めて完全かつ有効になると、Quickchatがそれを自動的に有効化します。書き込みアクション（POST、PUT、PATCH、DELETE）はこれを行いません。明示的な有効化を待ちます。データを変更するものに対しては、それが適切なデフォルトです。

NASAアクションカードのビフォーアフター。無効化されたスイッチ付きのIncomplete、その後スイッチオンでアクティブ 貼り付けて保存すると、読み取り専用の参照は自動的にオンになります。書き込みアクションでは、最終判断は必ずあなたに残されます。

予報と同じ方法でテストします。

Zermatt Highline旅行にDark-Sky Nightsオプションを追加しました。今夜の天文写真は何についてのものですか？

エージェントが今夜のAstronomy Picture of the Dayを説明している会話 エージェントは今夜の写真「Shadow and Rainbow」を取得し、何が写っているかを要約しました。

そしてInboxの証跡です。

NASAアクションの展開済み呼び出しカード。HTTP 200とdateパラメータが表示されている api.nasa.govからのHTTP 200です。モデルが埋めた唯一の値はdateで、空のままにしてNASAが今日をデフォルトにしています。キーはこの記録のどこにもありません。パラメータではないため、モデルが埋めたり明かしたりできるものではありません。

builderがAPIを見つけられない場合はどうなりますか？

builderは常にアクションを生成するわけではありません。それは意図された動作です。API名を指定せずに、動作だけを説明する文を入力します。

天気が悪そうなときに、エージェントが旅行者のツアー日程変更を支援できるようにしてください。

builderは検索しますが、責任を持って選べる単一のAPIを見つけられず、別のダイアログを返します。**「We need a bit more detail」**です。アクションは作成されません。Detailsパネルには、不足しているもの（どの天気プロバイダーか、どの予約システムか）が正確に説明され、具体的なエンドポイントを含む例文まで、言い換え方が示されます。

具体的な天気APIや予約システムが指定されていないことを説明し、具体的な言い換え例を示すneeds-more-detailダイアログ 修正手段付きの拒否です。何が曖昧だったか、推測がなぜ誤りなのか、機能する文の例が示されます。

拒否にはもう1種類あります。Quickchatがすでにネイティブに提供しているものを説明します。

旅行者がいら立っているように見える、または人と話したいと求めたときに、会話を人間のガイドに引き継いでください。

builderはこれを組み込み領域だと認識し、解決済みの問題を外部APIで包むのではなく、その機能を案内します。ダイアログ内にSet up Human Handoffボタンが表示されます。

handoffが組み込み機能であることを説明し、Set up Human Handoffボタンがあるダイアログ すべての機能をカスタムアクションにすべきではありません。人間へのエスカレーションは組み込み機能であり、builderは重複して作成せず、そこへルーティングします。

コピーする正確な文と設定

デモで使ったものを1か所にまとめます。アクションを生成した2つの文です。

Open-Meteo API（ドキュメント: https://open-meteo.com/en/docs）から場所の日別天気予報を取得し、旅行者が当社の目的地の天気について尋ねたときに、エージェントが尋ねられた日の実際の気温と降雨確率で回答できるようにしてください。
NASA APOD API（GET https://api.nasa.gov/planetary/apod）からNASAのAstronomy Picture of the Dayを取得し、Dark-Sky Nightsオプションに関心のあるゲストが今夜の注目天文写真について尋ねたときに、そのタイトルと何が写っているかを聞けるようにしてください。NASA APIキーは自分で提供します。

AI Main Promptです。アクションが存在した後に追加した2つのアクション行を含みます。プロンプト内でアクション名とトリガーの瞬間を指定すると、実行の信頼性が明らかに上がります。使うアクション名は、エディタで確認した生成済みのものです。

あなたはWanderlark Toursのアシスタントです。Wanderlark Toursは少人数向けのアルプスハイキングツアー運営会社です。Wanderlarkは3つのガイド付きツアー、Interlaken Classic、Zermatt Highline、Dolomites Traverseと、星空観察オプションのDark-Sky Nightsを運営しています。旅行者がツアーを選び、日程、料金、難易度、持ち物を理解できるように支援し、予約とキャンセルに関する質問に答えてください。温かく、実用的で、簡潔にし、回答は短く保ってください。

旅行者が目的地の今後の日の天気について尋ねたら、get_open_meteo_daily_forecastを呼び出し、尋ねられた日の実際の数値で回答してください。ゲストが今夜の天文写真について、またはDark-Sky Nightで見られる可能性のあるものについて尋ねたら、get_tonights_nasa_apodを呼び出し、写真のタイトルと何が写っているかを説明してください。

Wanderlarkについて実際に知っていることだけから回答してください。詳細がない場合は、推測するのではなく、その詳細は持っていないと伝え、Wanderlarkチームにつなぐことを提案してください。

生成されたAPI Action Descriptionsです。builderが書いたとおりです（実行挙動の調整が必要な場合は、URLではなくこれらを調整します）。

旅行者が目的地の特定の今後の日の天気について尋ね、Open-Meteo APIから実際の日別予報データ（最高/最低気温と降雨確率）が必要なときに、このアクションを使用します。アシスタントは目的地の緯度/経度、日付範囲、希望する単位を指定してこれを呼び出し、その後JSONレスポンスを使って、リクエストされた日の予報気温と降水確率を自然な言葉で説明する必要があります。
ゲストがDark-Sky Nightsオプションに関連して今夜のAstronomy Picture of the Dayについて尋ねたときに、このアクションを使用します。NASAの公式APODメタデータを取得し、タイトルと写真に何が写っているかを説明できます。このアクションは指定日（dateが指定されない場合は今日がデフォルト）についてNASAのAPOD APIを呼び出し、画像または動画URL、タイトル、説明、メディアタイプを含むJSONを返します。アシスタントはそれをゲスト向けに会話調で要約する必要があります。

予報アクションに設定したThinking messageです（呼び出し中にウィジェットが表示する行）。

ライブ予報を確認しています...

5つのKnowledge Base記事です。事実に要約しています。

ツアー: Interlaken Classic、3日間、初級から中級、890ユーロ、最大10名、5月から10月。Zermatt Highline、4日間、中級から上級、1,290ユーロ、最大8名、6月から9月。Dolomites Traverse、5日間、上級、1,590ユーロ、最大8名、6月下旬から9月中旬、小屋から小屋へ移動。料金にはガイド、宿泊、朝食が含まれます。

Dark-Sky Nights: Zermatt HighlineとDolomites Traverseの星空観察オプション、1人120ユーロ、望遠鏡を使うガイド付き夜間ウォーク、新月の時期に合わせて実施。曇天で中止になったセッションは日程変更または返金されます。

予約: 予約金200ユーロ、残金は開始30日前まで。30日前まで無料キャンセル可。29日前から14日前は50パーセント返金。14日以内は返金なし。ただし12か月以内に1回無料で再予約できます。

持ち物: 重ね着、防水シェル、履き慣らしたブーツ、30リットルの日帰り用バックパック。ポールとクランポンは提供されます。夏でも夜は寒くなります。

集合場所: Interlaken Ost駅。Zermatt駅（車両乗り入れ不可、Taeschからシャトル）。Cortina d'Ampezzo、Venice空港送迎は片道45ユーロ。

builderに正しく理解させるには、APIをどう説明すればよいですか？

このビルドで扱った内容は3つのルールで十分です。失敗ダイアログも、反対側から同じ教訓を示します。

2つの文の書き換え。曖昧な動作はガイダンス付きで拒否され、具体的なエンドポイント文は動作するアクションを生成した このガイドのすべての結果に共通するパターンです。具体的なAPIを入れると動作するアクションが出ます。動作だけを入れるとガイダンスが返ります。

  1. API名、エンドポイント、またはドキュメントURLを指定します。 「Open-Meteo API（docs: …）」は、2つの引用ソースに基づく正しいアクションを生成しました。「天気が悪そうなときにツアー日程を変更する」は拒否されました。APIではなく希望を指定しているためです。builderには読める具体物が必要であり、他の2つのルールもこれに依存します。
  2. エージェントがいつ使うべきか、次に何を言うべきかを指定します。 トリガー節はほぼそのままアクション説明になります。そして説明は実行時にアクションを発火させるものです。「旅行者が天気について尋ねたとき」は、モデルが会話中に認識できる信号です。
  3. 認証情報がある場合は、その扱い方を指定します。 「NASA APIキーは自分で提供します」により、認証は明確な[[secret]]としてモデル化されました。builder自身もこの方向に寄ります。短命のOAuthトークンより、キーやwebhook URLのような静的で長期の認証情報を好みます。アクションはトークン更新機構なしで、毎回そのまま実行されるためです。

そして、ルールではないことが1つあります。パラメータ、形式、レスポンスフィールドを指定する必要はありません。builderはOpen-Meteoのドキュメントを読み、頼まれなくても7つのパラメータ、妥当なデフォルト、適切な日別変数を選びました。最初から細かく指示しようとするのではなく、エディタで選択内容を確認します。

反復自体は軽い作業です。再生成ボタンはありません。下書きが誤っている場合は削除し、より明確な文で再送信します。1回あたり約30秒です。アカウントは最大15個の作成済みアクションを保持できるため、下書きは進めながら整理してください。

本番公開

有効化した時点で完了しています。アクションはチャネルではなくエージェントに属するため、作成した2つの参照は、Webサイトウィジェット、WhatsApp、Messenger、Slack、Telegram、Discord、またはエージェントがデプロイされているその他の場所から同じように実行されます。すべての呼び出しはInboxに記録されます。Webサイトウィジェットが主チャネルの場合、アクションを変更せずにAI chatbotをホワイトラベル化できます。回答できないことについても同じです。冬のスノーシューツアーについて尋ねられた場合、Wanderlarkは即興で答えるのではなく、運営していないと伝えます。

Wanderlarkが冬のツアーを運営していないことを正直に回答し、夏の代替案を提示しているエージェント 知識外のことを尋ねられると、エージェントは即興で答えず、その旨を伝えます。同じ抑制はAPI呼び出しにも引き継がれます。

最初のアクションを公開した後の自然な次のステップは2つです。

  • 重要な場面では実行を決定論的にします。 アクション説明がモデルの呼び出しタイミングを決めます。特定条件でのみ実行すべきアクションには、サーバー側の実行条件とメモリキャプチャを追加します。How to Make Your AI Agent’s Actions Reliableを参照してください。
  • 用意されているツールにはワンクリック統合を使います。 同じAdd Actionメニューには他の経路もあります。HubSpot Action、Discord Action、Google Sheetsは既製のギャラリーとして提供されます。Shopify MCPはストアのカタログに接続します。MCPは、240以上のカタログまたは貼り付けたURLから、任意のリモートMCP serverに接続し、そのサーバーのツールをインポートします。以下のガイドでギャラリーの手順を説明しています。

同じ場所に到達する3つの道と、1つの目安です。

ワンクリック統合とMCP自然な英語のbuilder手動エディタ
最適な用途ギャラリーがある一般的なツール、または任意のMCP server長いテールを含む、ドキュメント化された任意のREST API内部API、またはすべてのフィールドを完全に制御したい場合
提供するものアカウント接続またはサーバーURL1文、APIに必要ならキーすべてのフィールドを自分で入力
エージェントが得るものキュレーション済みの既製ツールセット文ごとに1つの、レビュー済みで引用付きのアクション入力した内容そのもの
扱っている場所下記のガイドこのガイド上の構造説明と、そこからリンクしている基本レシピ

関連ガイド

よくある質問

コードを書かずにAIエージェントをAPIに接続するにはどうすればよいですか？

Quickchat AIでActions & MCPsを開き、Add Actionをクリックし、API Actionを選択して、APIを自然な英語の1文で説明します。ライブWeb検索を使うLLMがAPIのドキュメントを読み、メソッド、URL、パラメータ、説明を含む完全なアクションを生成します。内容を確認し、APIキーなどのプレースホルダー値を入力して、有効化します。

AIエージェントにおけるfunction callingとは何ですか？

Function callingは、言語モデルが会話中に通常のテキストではなく、事前定義されたツールを実行するための構造化リクエストを出力する仕組みです。プラットフォームがツール、この場合はHTTPリクエストを実行し、その結果をモデルに返します。モデルは実データを使って返信を書きます。このガイドの各AI Action呼び出しは、1回のfunction callです。

function callingとtool callingは同じですか？

はい。Function callingとtool callingは同じ仕組みを指します。tool callingは、より新しく一般的な用語です。AI Actionはこれらのツールの1つです。会話中にモデルが呼び出すことを選べる、説明付きのHTTPリクエストです。

builderはAPIの形をどのように把握しますか？

生成中にAPIドキュメントに対してライブWeb検索を行い、そこで確認できた内容だけからアクションを組み立てます。結果ダイアログには読み取ったソースが一覧表示されるため、アクションを有効化する前に確認できます。

{{param}}と[[secret]]プレースホルダーの違いは何ですか？

{{param}}値は、毎回の呼び出しでモデルが会話から埋めます。たとえば日付や都市です。[[secret]]値は、有効化前に一度だけ貼り付ける定数です。たとえばAPIキーです。モデルがシークレットを選択したり編集したりすることはなく、モデルが埋められるパラメータでもありません。

APIキーはどこに入れますか。また、訪問者がエージェントから取り出せますか？

有効化する前に、エディタ内のアクションで[[secret]]プレースホルダーを置き換えます。キーはQuickchatが送信する固定リクエストの一部になります。これはパラメータではないため、モデルは変更できません。また、会話のアクション呼び出し記録にも表示されません。

builderが作成するのはGETの参照だけですか。それともエージェントはデータを書き込むこともできますか？

両方です。同じ1文のフローで、POST、PUT、PATCH、DELETEアクションを生成できます。読み取り専用のGETアクションは、完全かつ有効になると自動的にオンになります。書き込みアクションは、必ず明示的な有効化を待ちます。

プライベートAPIや内部APIに接続できますか？

はい。エンドポイントがQuickchat側からHTTPSで到達可能であれば接続できます。builderは公開ドキュメントを根拠にするため、内部APIの場合は文の中でエンドポイントを明示的に説明するか、近いテンプレートを生成してエディタでURLとフィールドを調整します。

特定のAPIではなく動作を説明した場合はどうなりますか？

builderは安全側に倒れます。エンドポイントを作り上げるのではなく、不足している情報を説明し、通常は具体的なベンダー、エンドポイント、またはドキュメントURLを指定する形で言い換え方を示します。リクエストがHuman Handoffなどの組み込み機能に一致する場合は、カスタムアクションを作成するのではなく、その機能を案内します。

会話中にAPI呼び出しが失敗した場合はどうなりますか？

エージェントはエラーを認識し、回答を作り上げるのではなく、参照を完了できなかったことをユーザーに伝えます。すべての呼び出しは、パラメータとHTTPステータスコードとともにInboxの会話に記録されるため、何が送信され、何が返ってきたかを正確に確認できます。

ChatGPT、Claude、GeminiもこのようにAPIに接続できますか？

これらのモデルはいずれもfunction callingをサポートしていますが、接続作業は開発者の作業です。カスタムGPT actionsと同様に、関数スキーマまたはOpenAPI specを自分で書きます。ここでは1文を入力すると、APIのライブドキュメントからアクションが生成され、エージェントのすべてのチャネルで実行されます。完成したQuickchatエージェントをMCP serverとしてChatGPT、Claude、Cursorに公開することもできます。

エージェントはどのチャネルからAPIを呼び出せますか？

すべてです。アクションはチャネルではなくエージェントに属するため、同じアクションがWebサイトウィジェット、WhatsApp、Messenger、Slack、Telegram、Discord、およびエージェントがデプロイされているその他の場所から実行されます。

自然な英語のaction builderは無料ですか？

はい。API Actionsの生成、確認、有効化は無料プランで動作します。このガイドの2つのアクションも無料アカウントで作成しました。有料プランで追加されるのは、より高い利用上限とより高度なモデルであり、builderへのアクセスではありません。

エージェントは複数のアクションからどのように選びますか？

各アクションの名前と説明を読み、会話のその時点に一致するものを選びます。デモエージェントには2つあります。天気の質問は予報アクションに、天文の質問はNASAのアクションにルーティングされます。説明にそれらのトリガーが記載されているためです。明確で区別しやすい説明が、選択を信頼できるものにします。

API呼び出しは返信にどの程度のレイテンシを追加しますか？

想像より少ないはずです。このガイドの実際の予報呼び出しは280 msで返り、全体で約2秒かかった返信の中に収まりました。訪問者には短い思考インジケータが表示されます。これはカスタムのthinking messageに置き換えられ、その後ライブデータに基づく回答が表示されます。

まとめ

入力した2つの文が、2つのライブで文書化されレビュー済みのAPI Actionsになりました。キー不要の天気参照と、キー付きのNASA参照です。それぞれ、モデルが埋めた値の横にInboxで記録されたHTTP 200によって確認されています。信頼できるものにするルールは3行に収まります。実在するAPIを指定すると、builderはそのドキュメントを根拠にアクションを作成し、引用します。あなただけが知っているものは[[secret]]として届き、埋めるまで有効化をブロックします。builderが確認できないものは、説明と推奨される言い換えになり、推測にはなりません。

API Actionsの全フィールド一覧、実行条件、レスポンス処理については、構築中にAI Actions docsを参照してください。