CallFunc 運用マニュアル

このマニュアルでは、3 つのデモ用 HTTP エンドポイント（get_schedule、 get_speaker、book_meeting）を、Perxona エージェントが呼び出せるツールに変える方法を説明します。そして同じくらい重要なこととして、LLM が「いつ」「どのように」使えばよいのかを実際に理解できるように、それらをどう書くか も解説します。

関連ドキュメント: API（正式なスキーマ）。

1. LLM はツールを「どう見ているか」

エージェントが動作するとき、Perxona はモデルにツールの一覧を渡します。各ツールは本質的に次のようなものです（OpenAI と Anthropic が内部で使っているのと同じ形です）:

{
  "name": "get_schedule",
  "description": "List conference sessions for the 2026-06-24/25 Japan demo. Optionally filter by day, track, or speaker.",
  "parameters": { /* the INPUT JSON Schema */ }
}

毎ターン、モデルはそのテキストだけを使って自問します:

1. そもそもツールを呼ぶべきか? → 名前 ＋ 説明 によって決まります。
2. どれを呼ぶか? → 各説明どうしがどれだけ明確に区別されているか によって決まります。
3. どんな引数で呼ぶか? → 入力スキーマ（フィールド名、型、required、説明、列挙値、デフォルト値）によって決まります。
4. 何が返ってきたか／ユーザーに何を伝えるか? → 出力スキーマ が助けになります（event_link が存在すること、count が数値であること、などをモデルが理解できます）。

ですから、制作者としてのあなたの仕事は、この 4 つを明確に書くことです。それがこの技術のすべてです。

呼び出し時に実際に起きること（内部の流れ）

LLM reads name + description + input schema
        │  decides to call, emits arguments matching the input schema
        ▼
Perxona validates args (JSON Schema → Pydantic), renders any {$context}/{$story}
templates into the URL/headers, injects your secret, and makes the HTTP request
        │
        ▼
Your server runs and returns JSON
        │
        ▼
Perxona feeds the JSON back to the LLM (the output schema helps it interpret),
which then writes the user-facing reply — or calls another tool.

あなたが作るのはサーバーと、4 つのテキスト／形のシグナルだけです。検証、シークレットの注入、HTTP 呼び出し、利用回数の制限、そして（任意で）ユーザー確認は Perxona が行います。

2. Perxona の 2 つの構成要素

ツールのセットアップは常に 2 つのオブジェクト で構成されます:

• デモ用サーバーに対して OutboundAPI を 1 つ 作成します（1 つのベース URL ＋ 1 つの API キー）。
• CallFunc を 3 つ 作成し（関数ごとに 1 つ）、すべてその OutboundAPI を指すようにします。

CallFunc は Storyboard の Panel の内側 に存在するため、ツールは意味をなす会話状態（パネル）でのみ利用可能にできます。

3. セットアップの手順

Step 0 — 公開 URL ＋ API キーを取得する

cd /Users/kilikkuo/Projects/perxona-callfunc-demo
brew install cloudflared  # one-time
./scripts/run.sh        # server on :8090 + prints https://<random>.trycloudflare.com
grep API_KEY .env       # your X-API-Key value

公開 URL の動作確認（ヘルスチェックにはキー不要）:

curl -s https://<random>.trycloudflare.com/health

Step 1 — OutboundAPI を作成する

管理画面（Backend Core / Outbound API）で、エントリを 1 つ作成します:

Step 2 — CallFunc #1 を作成する: get_schedule

入力スキーマ（クエリパラメータ）:

{
  "type": "object",
  "properties": {
    "day":     { "type": "string", "description": "Day label ('Day 1') or ISO date ('2026-06-24')." },
    "track":   { "type": "string", "description": "Track substring, e.g. 'Performance' or 'Workshop'." },
    "speaker": { "type": "string", "description": "Speaker name substring, e.g. 'Ohtani'." }
  }
}

出力スキーマ（「Output data」フィールド） — 全ブロックは API §1 を参照:

{
  "type": "object",
  "properties": {
    "count": { "type": "integer", "description": "Number of sessions returned." },
    "sessions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type":"string"}, "title": {"type":"string"}, "speaker": {"type":"string"},
          "track": {"type":"string"}, "room": {"type":"string"}, "day": {"type":"string"},
          "date": {"type":"string"}, "start": {"type":"string"}, "end": {"type":"string"}
        }
      }
    }
  }
}

Step 3 — CallFunc #2 を作成する: get_speaker

入力スキーマ:

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "description": "Speaker name to search for (substring)." },
    "id":   { "type": "string", "description": "Exact speaker id, e.g. 'spk_ohtani'." }
  }
}

出力スキーマ → API §2 を参照: count ＋ speakers[]（要素は id, name, title, company, bio, topics[], sessions[]）。

Step 4 — CallFunc #3 を作成する: book_meeting

入力スキーマ（ペイロード）:

{
  "type": "object",
  "required": ["attendee_name", "speaker", "date", "start_time"],
  "properties": {
    "attendee_name":    { "type": "string", "description": "Name of the person requesting the meeting." },
    "speaker":          { "type": "string", "description": "Name of the speaker to meet, e.g. 'Shohei Ohtani'." },
    "date":             { "type": "string", "description": "Meeting date, YYYY-MM-DD (for the demo, usually 2026-06-24 or 2026-06-25)." },
    "start_time":       { "type": "string", "description": "Local start time, 24h HH:MM." },
    "duration_minutes": { "type": "integer", "minimum": 5, "maximum": 240, "default": 30 },
    "attendee_email":   { "type": "string", "description": "Optional attendee email." },
    "topic":            { "type": "string", "description": "Optional meeting topic." }
  }
}

出力スキーマ → API §3 を参照: booking_id, status, mode, summary, speaker, start, end, timezone, event_link, message。

Step 5 — テストする

パネルでの会話の中で、次を試してみてください:

• 「Day 1 にある Performance のトークは何ですか?」 → get_schedule(day:"Day 1", track:"Performance") を呼ぶはずです。
• 「Shohei Ohtani とは誰で、何を発表するのですか?」 → get_speaker(name:"ohtani")。
• 「6 月 24 日の午後 2 時に Tanjiro Kamado とインシデント対応について 30 分の打ち合わせを予約して。」 → book_meeting(...) → 確認プロンプト（require_confirmation:true のため） → イベント作成。

4. 技術: LLM が理解できる説明とスキーマを書く

ここが、エージェントが賢く感じられるか、間抜けに感じられるかを決める部分です。いくつかの経験則を、ビフォー／アフター付きで紹介します。

4.1 名前 = モデルがマッチングする「動詞」

明確な verb_noun を使ってください: get_schedule、book_meeting。3 つの名前を区別しやすく保ち、モデルが似たツールの間で迷わなくて済むようにします。

4.2 説明 = 「何であるか」だけでなく「いつ使うか」

説明は、モデルが呼び出すかどうかを判断する 毎ターン に読まれます。何をするのかに加えて、トリガー（「use this when…」）と、あらゆる制限を記述してください。

ヒント: - 何を返すか を書いておくと（”returns title, company, bio, topics”）、そのツールでその質問に答えられるとモデルが理解できます。 - やらないこと（ネガティブスペース） を明記すると（”only when the user explicitly wants to book”）、早すぎる呼び出しや誤った呼び出しを防げます。特に書き込み操作では重要です。 - 実装の詳細（DB、フレームワーク）を詰め込まないでください。モデルはそれを必要とせず、モデルが推論に使うコンテキストを無駄に消費するだけです。

4.3 入力スキーマ = 引数の契約

各プロパティの説明は、モデルがそのフィールドを埋めるために使うヒントです。フォーマット について具体的に書いてください。モデルはあなたの書きぶりをそのまま真似します。

• フォーマット: "Meeting date, YYYY-MM-DD." や "Local start time, 24h HH:MM." と書くと、モデルは "next Tuesday" や "4 PM" ではなく 2026-06-24 や 16:00 を出力します。
• required: その呼び出しが成立しないフィールドを列挙します（attendee_name, speaker, date, start_time）。モデルはそれらが揃うまでユーザーに尋ね続けます。
• デフォルトと境界値: duration_minutes には default: 30、minimum: 5、maximum: 240 があるため、モデルはそれを省略でき、不正な値はサーバーに到達する前に拒否されます。
• 列挙値（enum）（このデモにはありませんが強力です）: {"type":"string","enum":["confirmed","tentative"]} は、モデルを有効な選択肢に制約します。
• フラットで小さく保つこと。 深くネストした入力は、モデルが確実に埋めるのが難しくなります。

4.4 出力スキーマ = モデルが結果をどう読むか（そしてなぜ追加を求められたか）

呼び出しの後、モデルはあなたの JSON レスポンスを読みます。出力スキーマは どんなフィールドが存在し、それが何を意味するか をモデルに伝え、次のことを可能にします:

• 適切な値を返答に取り込む（例: event_link をクリック可能なリンクとして提示する、message をそのまま読み返す）;
• 型を理解する（count は数値、topics はリスト、と分かる）;
• 存在しないフィールドを幻覚（ハルシネーション）しないようにする。

各出力フィールドは、入力を説明するのと同じように記述してください。book_meeting では、event_link が string | null であること（モックモードでは null）や、mode が "google_calendar" か "mock" かを示すことを記しておくと、エージェントが確認内容を正直に伝えられるようになります。

4.5 黄金律

5. テンプレート変数（任意・知っておくと便利）

Perxona は、URL／ヘッダー／固定パラメータ内の {$context.x} や {$story.x} プレースホルダーを使って、LLM に要求することなく会話コンテキストをリクエストへ 注入 できます。例: ログイン中ユーザーの id をヘッダーに {$context.user_id} として入れておけば、book_meeting はモデルにそれを渡させる必要がなくなります。このデモでは必須ではありませんが、シークレットや既知のコンテキストをモデルの手の届かないところに保つための方法です。

6. 安全性と UX のつまみ

このデモでは: book_meeting → require_confirmation: true; 2 つの get_* 読み取りは → false。

7. トラブルシューティング

8. Perxona CallFunc と MCP およびその他のエージェント型ツール設計の比較

最新のツールシステムはすべて、あなたが今使ったのと同じ中核的な考え方を共有しています。ツールとは、名前 ＋ 説明 ＋ JSON スキーマ であり、モデルはその契約の上で推論します。違いは 誰がツールをホストするか、どう転送するか、プラットフォームが何を肩代わりしてくれるか にあります。

早見比較

Perxona CallFunc 方式の長所

• ノーコード／ローコード。 URL ＋ JSON スキーマを貼り付けるだけで、任意の HTTP API がツールになります。バイブコーダーにとって、また既存のバックエンドを数分でエージェントツールに変えるのに最適です。書いて運用するアダプターサーバーは不要です（MCP 連携はサーバーを 構築し、かつ運用する ことを意味します）。
• 全部入り。 暗号化されたシークレット、ツールごとの利用回数制限、require_confirmation によるヒューマン・イン・ザ・ループ、コンテキストのテンプレート化（{$context}/{$story}）、text-to-SQL の安全性、ロギング、マルチテナントのスコープ化 — これらすべてが提供されます。MCP やネイティブ関数呼び出しでは、これらをすべて自分で構築します。
• 製品との緊密な統合。 ツールはペルソナ／ストーリーボードのフローの内側に存在し、パネルスコープにできます（適切な会話状態でのみ利用可能）。さらに、メモリ、ガードレール、会話トランスクリプトと同じパイプラインに乗ります。
• 出力スキーマがファーストクラスのフィールド。 何が返ってくるかを宣言できるため、モデルが結果を解釈しやすくなり、レスポンスが正直に保たれます（例: mock か本物の event_link か）。

短所／制限

• プロプライエタリでプラットフォームに固定される。 ツールは Perxona の中に存在し、他のホストへ移植できません。MCP の最大の利点は再利用 です。ツールサーバーを一度書けば、Claude Desktop、IDE、あらゆる MCP 互換クライアントから使えます。CallFunc は Perxona の外では再利用できません。
• HTTP のリクエスト／レスポンスのみ。 ローカル／stdio のツールはなく、ストリーミングや長時間ジョブもなく、ステートフルなツールセッションもなく、MCP の リソース／プロンプト／サンプリング プリミティブもありません。（現在のバックエンドでは DATA_VALIDATION の CallFunc タイプは未実装で、ツール結果のキャッシュ、バッチ処理、サーキットブレーカーもありません。1 回のきれいなラウンドトリップです。）
• 静的な構成。 ツールは UI で事前にセットアップされ、MCP の tools/list のような実行時の発見はありません。ツールを変更するには管理画面で編集します。
• 公開エンドポイントを自分でホストする必要がある。 Perxona から到達可能でなければならず（だから cloudflared トンネルを使います）、その稼働時間、レイテンシ、タイムアウト、TLS はあなたが所有します。MCP サーバーはクライアントの隣でローカルに動かせ、ネイティブ関数はあなた自身のアプリ内で動きます。
• スキーマ方言の結合。 入力／出力には JSON Schema（Draft 2020-12）を使い、jambo 経由で Pydantic に変換します。非常に特殊なスキーマ機能はきれいに変換されない場合があります。スキーマはシンプルかつフラットに保ってください（いずれにせよモデルにとっても良い習慣です）。

考え方の整理

• これらの方式は 精神においては相互排他的ではありません — すべてが 名前 ＋ 説明 ＋ スキーマ に立脚しています。ここで学んだことは、MCP にもネイティブ関数呼び出しにもそのまま転用できます。
• Perxona CallFunc を使う のは、Perxona の中で出荷していて、「HTTP API が存在する」から「エージェントがそれを使える」までの最速の道を、確認／制限／シークレットを肩代わりしてもらいながら進みたいときです — まさにこのデモです。
• MCP に手を伸ばす のは、多数の AI クライアントにわたって再利用可能な ツール／データサーバーが欲しいとき、ローカルまたはステートフルなアクセスが必要なとき、あるいは単なる関数呼び出しを超えたリソース／プロンプトが欲しいときです。
• ネイティブ関数呼び出しを使う のは、LLM API の上に 自分自身の エージェントアプリケーションを直接構築していて、実行のエンドツーエンドの制御が欲しいときです。

9. 1 ページの総まとめ

1. 2 つのオブジェクト: OutboundAPI を 1 つ（URL ＋ API キー）＋ 関数ごとに CallFunc を 1 つ（名前、説明、メソッド、パス、入力スキーマ、出力スキーマ、確認）。
2. モデルが見るのは 名前 ＋ 説明 ＋ 入力スキーマ ＋ 出力スキーマ だけです — 賢い見知らぬ人に向けて書きましょう。
3. 説明 = 何をするか ＋ いつ使うか（＋ 何を返すか、＋ 何をしてはいけないか）。
4. 入力スキーマ = フィールド名、型、required、フォーマット、デフォルト値、列挙値。
5. 出力スキーマ = 何が返ってくるか。モデルが結果を正しく読めるようにするため。
6. 書き込みには require_confirmation: true を付ける。 読み取りには付けない。
7. HTTP ＋ マネージドなガードレール、コード不要 — Perxona の中ではスピードに優れます; MCP は再利用性／移植性とより豊富なプリミティブで勝り; ネイティブ関数呼び出し は自分のアプリでの完全な制御で勝ります。