ケーパビリティと実行

capability は、特定のユーザー接続に対して返されるアクションです。モデル向けの説明と JSON Schema を、アクションの実行に必要な接続ルートと組み合わせています。

アシスタントが複数のコネクタにまたがって動作できる場合はユーザーの集約メソッドを使用し、1 つの接続アカウントだけがアクションを提供する必要がある場合はコネクタハンドルを使用してください。

1 人のユーザーの capability を集約する

const user = vinkius.user('alice_123');
const capabilities = await user.capabilities();

このメソッドはユーザー capability エンドポイントに 1 回リクエストを送り、返された各項目を実行可能な Capability に変換します。どの接続がアクションを提供するかはエンドポイントが決定します。クライアントが 2 回目の準備状態チェックを行うことはありません。

空の CapabilitySet は有効です。ユーザーに利用可能なアクションがないこと、要求したフィルタに一致する接続がないこと、サービスが何も返さなかったことを意味する場合があります。明示的に処理してください：

if (capabilities.length === 0) {
  return { tools: [], message: 'Connect an account before requesting this action.' };
}

コネクタのスコープを制限する

const selected = await user.capabilities({
  include: ['github', 'slack'],
  exclude: ['slack'],
});

include はコネクタフィルタとしてサーバーに送信されます。exclude はレスポンスの後に SDK によって適用されます。この例では、リクエストは GitHub と Slack を要求し、その後ローカルで Slack を取り除きます。

1 つのコネクタに対しては、そのハンドルを使用します：

const githubCapabilities = await user.connector('github').capabilities();

コネクタスコープのルックアップには既存の接続が必要で、ID を解決するために最初に接続一覧を取得する場合があります。一致するものが存在しない場合は ConnectorNotConnectedError をスローします。

capability のコントラクトを確認する

for (const capability of capabilities) {
  console.log({
    name: capability.name,
    rawName: capability.rawName,
    connector: capability.connector,
    connectionId: capability.connectionId,
    title: capability.title,
    description: capability.description,
    inputSchema: capability.inputSchema,
  });
}

デフォルトでは、name は ${connector}__${rawName} になります（例： github__create_issue）。rawName はコネクタのアクション名で、SDK が実行のために送信する値です。クライアントコンストラクターの namespaceCapability で表示名関数を置き換えることもできますが、アダプターはプロバイダーの命名規則を検証しません。

可用性を前提とせずに選択する

CapabilitySet は Array<Capability> を継承し、2 つのヘルパーを追加します：

const githubOnly = capabilities.forConnector('github');
const createIssue = githubOnly.findCapability('github__create_issue');

forConnector() はコネクタの slug を厳密に比較します。findCapability() は表示名または raw 名を受け取り、最初に一致したものを返します。raw 名は衝突する可能性があります。たとえば、2 つのコネクタがどちらも search を公開することがあります。一意の表示名を優先するか、先にコネクタでフィルタリングしてください。

返されたスキーマで実行する

if (!createIssue) {
  throw new Error('The requested action is not available for this user');
}

const result = await createIssue.execute(
  { owner: 'acme', repo: 'product', title: 'Document retries' },
  {
    idempotencyKey: 'create-issue:operation-8042',
    signal: request.signal,
  },
);

const output = result.content.map((part) => part.text).join('\n');
if (result.isError) {
  console.error(output);
}

引数は Record<string, unknown> です。スキーマは実行時に検出されるためです。アプリケーションにより厳密な保証が必要な場合は、実行前に inputSchema から入力を検証または構築してください。

副作用のある操作には、論理操作から導出した空でないキーを使用してください。そのキーを再利用するのは、同じ操作を再試行する場合のみにしてください。SDK は空のキーを拒否しません。アプリケーション側での検証が必要です。キーがない場合、capability の実行はトランスポートを 1 回だけ試行します。

結果と例外のパスを理解する

execute() は次のように解決されます：

interface CapabilityResult {
  content: Array<{ type: string; text: string }>;
  isError: boolean;
}

isError: true は、capability が失敗したアクション結果を返したことを意味します。HTTP、認証、検証、レート制限、クォータ、タイムアウト、ネットワークの失敗は、通常は代わりに SDK エラーをスローします。

アダプターのディスパッチヘルパーとファクトリーにバインドされた関数は ExecuteOptions を受け付けません。操作にキャンセルやべき等キーが必要な場合は、Capability を解決して execute() を直接呼び出してください。

モデル境界でのみ変換する

アダプターは、表示名、説明、入力スキーマをプロバイダーまたはフレームワークの形式で保持します。ディスパッチ、ユーザースコープ、直接実行には元の CapabilitySet を保持し、変換されたツール定義から capability を再構築しようとしないでください。

次のステップ

• Compare adapter outputs and result handling
• Discover the architecture behind every capability
• Handle retries and both failure channels