cala

Cala — AI エージェントのためのナレッジレイヤー

Cala は、世界中の公開データを対象とするナレッジグラフです。名前付きエンティティ、その属性、エンティティ間の関係、タイムスタンプ付きの観測値を収録し、すべての値にソースと日付が付いています。ウェブをスクレイピングする代わりに、これをクエリしてください。

このスキルは、Cala のツールが読み込まれていることを前提としています（ツールのスキーマにパラメーターと本文の形式が記載されています）。ここでは、スキーマだけではわからない、使うツールの選び方、クエリ言語、読み取り時の原則、失敗した場合の対処方法を説明します。

アクセス

MCP（推奨）： API キーを使って https://api.cala.ai/mcp/ に接続し、ツールを直接呼び出してください。Cala のツールがコンテキストにない場合、サーバーが設定されていません。処理を中止し、ユーザーに https://docs.cala.ai/integrations/mcp を案内してください。

REST（代替）： ベース URL は https://api.cala.ai/v1、ヘッダーは X-API-KEY: <key> です。エンドポイント名はツール名と1対1で対応しています。仕様は https://api.cala.ai/openapi.json にあります。API キーは https://console.cala.ai/api-keys から取得してください。

適切なツールを選ぶ

Filter / list / "find all X where Y"?          → knowledge_query
Open-ended "what", "who", "explain"?           → knowledge_search
Have a name, want the entity (a seed UUID)?    → entity_search
Have a UUID, want a coarse profile?            → entity_retrieval (no body)
Have a UUID, don't know what's queryable?      → entity_introspection
Have a UUID, want specific fields/rels/metrics → entity_introspection → entity_retrieval

構造化された方法を選んでください。 knowledge_query と、フィールドを指定した entity_retrieval は、knowledge_search よりもトークン消費が大幅に少なく、挙動も予測しやすくなります。回答の形式がわかっている場合は、構造化された方法を選んでください。knowledge_search は、本当に自由度の高い質問に限って使います。

knowledge_query — 構造化フィルター

ドット表記のクエリ言語です。. はそれぞれ、グラフ上を進む1つのホップとして読みます。OpenAI.founded.year は、founded エッジをたどってから year を読み取ります。フィールド名の自然な言い換えも解釈されるため、意図したとおりに記述してください。

• 演算子：= 完全一致 · != 等しくない · > < <= >= 数値比較 · , = 同一フィールドに対するAND（investors=Sequoia Capital,Andreessen Horowitz → 両方から支援を受けている。いずれか一方ではありません）。
• 修飾子。句の順序は filters → order_by → limit → return()：
  • order_by=field ASC|DESC — レコードの表示順だけでなく、表示されるレコード自体が変わります（デフォルトの並べ替えは関連度順です）。
  • limit=N — 結果数の上限を設定します。
  • return(f1, f2, ...) — 指定したフィールドのみを返します。トークン消費を抑えられます。
• 数値フィールドは、おおよその文字列（"over 100M"、"~206,753"）を返すことがあります。厳密な値として扱わず、情報を統合してください。

{"input": "OpenAI.founded.year"}
{"input": "startups.location=Spain.funding>10M.order_by=funding DESC.limit=5.return(name, funding, sector)"}
{"input": "companies.investors=Sequoia Capital,Andreessen Horowitz"}
{"input": "companies.sector=climate tech.funding_round.series=A,B.location=Southern Europe.return(name, funding, investors)"}

results（行）と entities（言及されたすべてのもの。場所や人物など。行と1対1で対応するとは限りません）が返されます。エンティティ UUID を entity_retrieval に渡すと、さらに詳しく調べられます。

名前付きエンティティ — entity_search → entity_retrieval

entity_search で名前をシードエンティティに解決します（あいまい検索で名前から UUID を特定します。各検索結果には name、entity_type、description が含まれます。選択には説明を使ってください）。

シード UUID を指定すると、entity_retrieval は次の2つのモードで読み取ります。

• 概要プロフィール — 本文なしで実行します。デフォルトのプロパティのみを返し、関係や数値観測値は含まれません。
• フィールド指定 — 正確な properties、relationships、numerical_observations を本文で指定します。関係や時系列データを取得する唯一の方法であり、最も効率的な読み取り方法です。

スキーマを調べてから、取得するフィールドを指定してください。 クエリ可能なスキーマはエンティティごとに異なるため、まずシードに対して entity_introspection を実行します。これにより、データがある近傍（プロパティ、入力・出力関係、指標 UUID）が返されます。その後、該当するものだけを指定してください。事前に調べずに指定すると、リクエストの往復が無駄になり、空のエッジを要求する可能性があります。

関係の形式。 エッジは方向を持つ UPPER_SNAKE 型で、入力または出力方向にたどります。多数の型があります。たとえば、企業に入る方向には FOUNDED（創業者）、IS_CEO_OF（幹部）、IS_DIRECT_OWNER_OF（投資家）があり、出る方向には IS_ULTIMATE_PARENT_OF（子会社）があります。特定のエンティティが実際に持つエッジについては、イントロスペクション結果を正として扱ってください。

観測値（numerical_observations）は、財務データ、マクロ指標、為替、ポジショニングなどの時系列データです。それぞれ、イントロスペクションで取得した指標 UUID に対応しています。ライブのティックではなく、履歴を含む最新のソース付きの値です。

すべてのプロパティと関係には出典情報（sources：名前、文書 URL、日付）が付いています。これを保持し、事実を提示するときはソースと日付も伝えてください。

knowledge_search — 典拠付きのナラティブ回答

自由形式の質問に使用します。content（Markdown）と、次の典拠チェーンを返します。

• explainability[i] = {content: "claim", references: [ctx-id, ...]} — 各主張はコンテキスト ID に対応します。
• context[j] = ソースドキュメント。各ドキュメントには id と、origins[k].document.url（引用可能なリンク）、origins[k].source.name（発行元）が含まれます。

主張を引用するには、その主張の references を context[j].id に対応付け、そのコンテキストの origins にある URL と発行元を使用します。entities には、詳細を確認するための UUID が格納されています。

失敗時 — 停止し、でっち上げない

失敗した場合は必ず停止し、その旨をユーザーに伝えてください。ウェブ検索、学習済み知識の想起、記憶に暗黙にフォールバックしてはいけません。それは Cala の回答を装ったでっち上げです。ユーザーはフォールバックを明示的に依頼できます。

• 到達不能 → 停止し、https://console.cala.ai/api-keys と https://docs.cala.ai/integrations/mcp を案内します。
• タイムアウト（クエリには最大 180 秒かかることがあります。通常、原因は Cala ではなくホストです）→ 同じ呼び出しを 1 回再試行してから停止し、「MCP クライアントのタイムアウトを約 180 秒に延長して、再試行してください」と案内します。
• データなし → {"results": [], "entities": []}（一致なし／曖昧すぎる）と {"results": [{"error": "...too complex..."}], "entities": null}（複雑すぎる）を区別します。検索範囲を広げるか、質問を簡潔にするか、knowledge_search に切り替えてください。それでも結果が空の場合は停止します。
• レート制限（HTTP 429）→ 停止してユーザーに伝え、再試行しないでください。