メインコンテンツまでスキップ

CLI Agent モデル

長時間実行される、ツール駆動のエージェント型タスクのために、Claude Code または Codex をエージェントのモデルとして実行します。​

CLI Agent モデルを使用する理由​

Chat completion は、1 つのプロンプトに 1 回の処理で回答します。一部のタスクには、より多くの処理が必要です。たとえば、knowledge base 全体にわたるトピック調査、生成されたファイルの反復改善、またはツールを何十回も呼び出す複数ステップの計画の実行などです。これを単一の completion に詰め込もうとすると、すべてのステップを自分でオーケストレーションする必要があります。

CLI agent モデルは、すでに使用している同じ agent API の背後で、完全なエージェント型 CLI である Claude Code または Codex を実行します。Squid は分離されたセッション内で CLI をサーバー側で実行します。CLI は計画を立て、エージェントのツールを呼び出し、タスクが完了するまで反復します。

Client code
await squid.ai().agent('research-assistant').updateModel('claude-code');

const jobId = crypto.randomUUID();
await squid.ai().agent('research-assistant').askAsync('Compare our Q1 and Q2 sales data and summarize the trends', jobId);

// An askAsync job resolves with the agent's answer as a plain string.
const answer = await squid.job().awaitJob<string>(jobId);

概要​

CLI agent モデルは、vendor model とまったく同じ方法で選択します。モデル名を upsert()、updateModel()、または model ask option に渡します（AI agent の構築を参照）。Chat completions API を呼び出す代わりに、Squid は対応する CLI を sandboxed session で起動し、エージェントの instructions と tools を転送し、CLI の最終応答を返します。

利用可能なモデル​

モデル名Provider CLI実行対象Context window
claude-codeClaude CodeCLI の default model tier200K tokens
claude-code-opusClaude Code最新の Opus tier200K tokens
claude-code-sonnetClaude Code最新の Sonnet tier200K tokens
claude-code-haikuClaude Code最新の Haiku tier200K tokens
codexCodexCLI の default model272K tokens
codex-gpt-5.5CodexGPT-5.5272K tokens
codex-gpt-5.4CodexGPT-5.4272K tokens
codex-gpt-5.4-miniCodexGPT-5.4 Mini272K tokens
codex-gpt-5.3-codexCodexGPT-5.3 Codex272K tokens

Claude Code tiers は、各 tier の最新モデルを自動的に追跡します。Codex variants は特定のモデルに固定されます。すべての CLI agent モデルは、最大 64K output tokens をサポートします。

CLI agent モデルを使用するタイミング​

ユースケース推奨事項
多数の tool calls を連鎖させる複数ステップのタスクCLI agent モデル
長時間実行される調査や分析（数分の作業）askAsync() + jobs を使用する CLI agent モデル
token streaming を伴う高速な会話応答Vendor chat model（例: 'claude-sonnet-4-6'、'gpt-5.5'）
Knowledge base に対する単純な Q&Aknowledge bases を使用する vendor chat model

仕組み​

  1. エージェント用に CLI agent モデルを選択し、ask を送信します
  2. Squid は、エージェントの instructions を渡して、サーバー側で分離された CLI session を開始します
  3. エージェントの AI functions、connected integrations、および knowledge bases が MCP tools として CLI に公開されます
  4. CLI は計画を立て、tools を呼び出し、タスクが完了するまで反復します。ask は長時間実行される job として実行されます
  5. 最終応答が返されます。conversation state はフォローアップ ask のために CLI session 内に保持されます

Quick Start​

Step 1: provider API key を追加する​

CLI agent モデルは、Squid Console の Settings > AI Settings で設定された、独自の provider API key を使用します。

  • Claude Code models には Anthropic API key が必要です
  • Codex models には OpenAI API key が必要です

Step 2: モデルを選択する​

Client code
await squid.ai().agent('research-assistant').updateModel('claude-code');

または、model ask option を使用してリクエストごとに上書きします。

Step 3: Ask し、実行を job として追跡する​

CLI agent の実行には数分かかる場合があるため、単一の request を開いたままにするのは避けてください。job ID を渡し、jobs API を通じて待機します。

Client code
const jobId = crypto.randomUUID();

await squid.ai().agent('research-assistant').askAsync('Audit our onboarding docs for outdated steps', jobId);

// Optionally, observe interim progress (tool calls, status messages).
const statusSubscription = squid
  .ai()
  .agent('research-assistant')
  .observeStatusUpdates(jobId)
  .subscribe((status) => console.log(status));

// An askAsync job resolves with the agent's answer as a plain string.
const answer = await squid.job().awaitJob<string>(jobId);
statusSubscription.unsubscribe();

Core Concepts​

長時間実行​

すべての CLI agent ask は、長時間実行される job として実行され、デフォルトおよび最大の wall time は 30 minutes です。実行をより厳密に制限するには、ask options で quotas.maxRuntimeSeconds を設定します（30 秒から 30 分の間に clamp されます）。

Client code
await squid
  .ai()
  .agent('research-assistant')
  .askAsync('Summarize the support tickets from this week', jobId, {
    quotas: { maxRuntimeSeconds: 300 },
  });

maxRuntimeSeconds は、非 CLI-agent モデルでは無視されます。

Sessions と conversation memory​

Conversation state は CLI 自身の session に存在し、Squid はエージェントの memory options に従ってこれを保持し、ask 間で再開します。CLI が独自の transcript を管理するため、conversation は Squid の chat history APIs には表示されません。

同じ provider の variants 間で切り替える場合（例: claude-code から claude-code-opus）、同じ session が再開されるため、conversation は model tiers をまたいで継続できます。

エージェント conversation ごとに、一度に実行できる ask は 1 つです。同じ conversation に対する concurrent ask は、まもなく再試行するよう求める busy message とともに拒否されます。

Shared workspaces​

デフォルトでは、各 conversation は独自の分離された directory で作業します。ask 間、または異なる agents 間でファイルを共有するには、ask options で sharedWorkspaceId を渡します。同じ workspace ID を持つ ask は、同じ永続的な working directory で動作します。

Client code
await squid.ai().agent('report-writer').askAsync('Draft the quarterly report as report.md', jobId, {
  sharedWorkspaceId: 'q3-reporting',
});

Workspace IDs には、letters、numbers、underscores、dashes を含めることができます（最大 200 文字）。この option は、非 CLI-agent モデルでは無視されます。

MCP 経由の Tools​

CLI agent モデルは、native function calling ではなく MCP を通じてエージェントの能力にアクセスします。

  • AI functions と connected integrations は、CLI が呼び出せる MCP tools として公開されます
  • Knowledge bases は search tools として公開されます。CLI は、取得済み context を prompt で受け取るのではなく、必要に応じてそれらに query します

これにより、CLI はタスク中に各 source をいつ、どの頻度で参照するかを制御できます。

制限事項​

制限事項詳細
Token streaming なし応答は実行が完了したときに届きます。途中経過には observeStatusUpdates() を使用してください。
File upload なしFile upload APIs は CLI agent モデルではサポートされていません
Structured outputresponseFormat: 'json_object' はサポートされています。json_schema format は STRUCTURED_OUTPUT_NOT_SUPPORTED で拒否されます
Chat history APIsTranscripts は CLI session 内に存在し、Squid の chat history methods からは返されません
Conversation ごとに 1 実行同じ conversation での concurrent asks は busy error で拒否されます。active run の後に再試行してください

Error Handling​

問題原因解決策
Ask が missing API key message で失敗する選択したモデルの provider key が設定されていないSettings > AI Settings で Anthropic（Claude Code）または OpenAI（Codex）key を追加します
Busy / retry response同じ conversation ですでに別の ask が実行中active run が完了するまで待ってから再試行します
実行が time limit で終了するタスクが maxRuntimeSeconds（または 30 分の最大値）を超過したタスクをより小さな ask に分割するか、上限まで maxRuntimeSeconds を引き上げます

Best Practices​

  1. job ID とともに askAsync() を使用します。 CLI agent の実行は日常的に数分かかります。job を待機することで、アプリの応答性を保ち、page reload 後も継続できます（ID を持つ任意の client が待機できます）。
  2. 進行状況を表示します。 observeStatusUpdates(jobId) を subscribe して、ユーザーに無音の数分間待機ではなく tool activity を見せます。
  3. Interactive flows では runtime を制限します。 ユーザーが能動的に待っている場合は quotas.maxRuntimeSeconds を設定し、完全な 30 分は background tasks 用に残します。
  4. 複数ステップの workflows には shared workspaces を使用します。 安定した sharedWorkspaceId により、連続する asks（または協調する agents）が互いのファイルをもとに作業できます。
  5. 再現性のために Codex variants を固定します。 codex-gpt-5.5 などは exact models に固定されます。claude-code-* tiers は各 tier の latest release を追跡します。

Next Steps​

  • AI agent の構築 - agents を作成し、instructions を設定し、models を管理します
  • Asynchronous jobs - awaitJob() と getJob() で長時間実行される asks を追跡します
  • AI functions - CLI agent が呼び出せる backend tools
  • Abilities - knowledge bases、integrations、tools をエージェントにアタッチします