CLI Agent Models

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

CLI Agent Models を使用する理由

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

CLI agent models は、すでに使用している同じ 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 models は、vendor models とまったく同じ方法で選択します。upsert()、updateModel()、または model ask option にモデル名を渡します（AI エージェントの構築を参照）。チャット補完 API を呼び出す代わりに、Squid は対応する CLI をサンドボックス化されたセッションで起動し、エージェントの指示とツールを転送して、CLI の最終応答を返します。

利用可能なモデル

Model name	Provider CLI	Runs	Context window
claude-code	Claude Code	CLI のデフォルトモデル tier	200K tokens
claude-code-opus	Claude Code	最新の Opus tier	200K tokens
claude-code-sonnet	Claude Code	最新の Sonnet tier	200K tokens
claude-code-haiku	Claude Code	最新の Haiku tier	200K tokens
codex	Codex	CLI のデフォルトモデル	272K tokens
codex-gpt-5.5	Codex	GPT-5.5	272K tokens
codex-gpt-5.4	Codex	GPT-5.4	272K tokens
codex-gpt-5.4-mini	Codex	GPT-5.4 Mini	272K tokens
codex-gpt-5.3-codex	Codex	GPT-5.3 Codex	272K tokens

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

CLI agent model を使用するタイミング

Use Case	Recommendation
多数のツール呼び出しを連鎖させる複数ステップのタスク	CLI agent model
長時間実行される調査または分析（数分の作業）	askAsync() + jobs を使用した CLI agent model
token streaming を伴う高速な会話応答	vendor chat model（例: 'claude-sonnet-4-6', 'gpt-5.5'）
knowledge base に対する単純な Q&A	knowledge bases を使用した vendor chat model

仕組み

1. エージェントに CLI agent model を選択し、ask を送信します
2. Squid はサーバーサイドで分離された CLI セッションを開始し、エージェントの指示を渡します
3. エージェントの AI functions、connected integrations、および knowledge bases が MCP tools として CLI に公開されます
4. CLI は計画を立て、ツールを呼び出し、タスクが完了するまで反復します。ask は長時間実行される job として実行されます
5. 最終応答が返されます。会話状態は follow-up asks のために CLI セッション内に保持されます

クイックスタート

Step 1: provider API key を追加する

CLI agent models は、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 runs には数分かかることがあるため、単一のリクエストを開いたままにしないようにしてください。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();

コアコンセプト

長時間実行

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

Client code

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

maxRuntimeSeconds は、非 CLI-agent models では無視されます。

セッションと会話メモリ

会話状態は CLI 自身のセッション内に存在し、Squid はエージェントのメモリオプションに従ってそれを保持し、ask 間で再開します。CLI が独自の transcript を管理するため、この会話は Squid の chat history APIs には表示されません。

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

エージェントの会話ごとに、一度に 1 つの ask が実行されます。同じ会話に対する同時 ask は、少し後に再試行するよう求める busy message とともに拒否されます。

共有ワークスペース

デフォルトでは、各会話はそれぞれ独自の分離されたディレクトリで動作します。ask 間、または異なるエージェント間でファイルを共有するには、ask options に sharedWorkspaceId を渡します。同じ workspace ID を持つ ask は、同じ永続的な作業ディレクトリで動作します。

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 文字）。このオプションは、非 CLI-agent models では無視されます。

MCP 経由のツール

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

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

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

制限事項

Limitation	Detail
token streaming なし	応答は run が完了したときに届きます。途中経過には observeStatusUpdates() を使用してください。
file upload なし	file upload APIs は CLI agent models ではサポートされていません
Structured output	responseFormat: 'json_object' はサポートされていますが、JSON schema で保証された output はサポートされていません
Chat history APIs	Transcripts は CLI セッション内に存在し、Squid の chat history methods からは返されません
会話ごとに 1 run	同じ会話での同時 asks は busy error で拒否されます。active run の後に再試行してください

エラーハンドリング

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

ベストプラクティス

1. job ID とともに askAsync() を使用します。 CLI agent runs には通常数分かかります。job を待機することで、アプリの応答性を保ち、ページ再読み込みにも耐えられます（ID を持つ任意の client が待機できます）。
2. 進捗を表示します。 observeStatusUpdates(jobId) を購読して、ユーザーが無音の数分待ちではなくツールのアクティビティを確認できるようにします。
3. インタラクティブなフローでは実行時間を制限します。 ユーザーが能動的に待っている場合は quotas.maxRuntimeSeconds を設定し、完全な 30 分はバックグラウンドタスク用に確保します。
4. 複数ステップのワークフローには共有ワークスペースを使用します。 安定した sharedWorkspaceId により、連続する asks（または協力する agents）が互いのファイルを基に作業できます。
5. 再現性のために Codex variants を固定します。 codex-gpt-5.5 などは正確なモデルに固定されます。claude-code-* tiers は各 tier の最新リリースを追跡します。

次のステップ

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