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

CLI Agent Models

長時間実行される tool-driven agentic task に対して、Claude Code または Codex を agent の model として実行します。​

CLI Agent Models を使用する理由​

chat completion は 1 回の pass で 1 つの prompt に回答します。一部の task にはそれ以上の機能が必要です。たとえば、knowledge base を横断した topic の調査、生成された file の反復処理、数十回の tool call を伴う multi-step plan の実行などです。これを単一の completion に収めようとすると、各 step を自身で orchestration する必要があります。

CLI agent model は、すでに使用している同じ agent API の背後に、完全な agentic CLI である Claude Code または Codex を配置します。Squid は isolated session で CLI を server-side 実行します。CLI は agent の tool を plan・invoke し、task が完了するまで反復します。

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 model は vendor model とまったく同様に選択します。Building AI agentsで説明されているように、model 名を upsert()、updateModel()、または model ask option に渡します。Squid は chat completions API を呼び出す代わりに、sandboxed session で対応する CLI を起動し、agent の instructions と tool を転送して、CLI の final response を返します。

利用可能な model​

Model nameProvider CLI実行内容Context window
claude-codeClaude CodeCLI の default model tier200K token
claude-code-opusClaude Code最新の Opus tier200K token
claude-code-sonnetClaude Code最新の Sonnet tier200K token
claude-code-haikuClaude Code最新の Haiku tier200K token
codexCodexCLI の default model272K token
codex-gpt-5.5CodexGPT-5.5272K token
codex-gpt-5.4CodexGPT-5.4272K token
codex-gpt-5.4-miniCodexGPT-5.4 Mini272K token
codex-gpt-5.3-codexCodexGPT-5.3 Codex272K token

Claude Code tier は各 tier の最新 model を自動的に追跡します。Codex variant は特定の model に固定されます。すべての CLI agent model は最大 64K output token をサポートします。

CLI agent model を使用する場合​

ユースケース推奨
多数の tool call を chain する multi-step taskCLI agent model
長時間実行される research または analysis（数分の作業）askAsync() + jobs を使用する CLI agent model
token streaming を伴う高速な conversational responsevendor chat model（例: 'claude-sonnet-4-6'、'gpt-5.5'）
knowledge base に対するシンプルな Q&Aknowledge bases を使用する vendor chat model

仕組み​

  1. agent 用の CLI agent model を選択し、ask を送信します
  2. Squid が agent の instructions を渡して、isolated CLI session を server-side で開始します
  3. agent の AI functions、connected integrations、knowledge base が、MCP tool として CLI に公開されます
  4. CLI は plan の作成、tool の呼び出し、task 完了までの反復を行います。ask は長時間実行の job として実行されます
  5. final response が返されます。follow-up ask 用に conversation state は CLI session 内に保持されます

クイックスタート​

ステップ 1: Provider API key を追加する​

CLI agent model は独自の provider API key を使用します。Squid Console の Settings > AI Settings で設定します。

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

ステップ 2: Model を選択する​

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

または、model ask option で request ごとに override します。

ステップ 3: Ask を送信し、run を job として追跡する​

CLI agent の run には数分かかる場合があるため、単一 request を開いたままにしないでください。job ID を渡し、jobs API を通じて await します。

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();

コアコンセプト​

Long-running execution​

すべての CLI agent ask は、default および最大 wall time が 30 分の長時間実行 job として実行されます。run をより厳密に制限するには、ask option で 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 は non-CLI-agent model では無視されます。

Session と Conversation Memory​

conversation state は CLI 独自の session に存在し、agent の memory option に従って Squid が ask をまたいで保持・resume します。CLI は独自の transcript を管理するため、conversation は Squid の chat history API には表示されません。

同じ provider の variant 間で切り替える場合（たとえば claude-code から claude-code-opus）、同じ session が resume されるため、conversation は model tier をまたいで継続できます。

agent conversation ごとに、一度に実行できる ask は 1 つです。同じ conversation に対する concurrent ask は、間もなく retry するよう求める busy message で拒否されます。

Shared Workspace​

default では、各 conversation は独自の isolated directory で作業します。ask 間または異なる agent 間で file を共有するには、ask option で sharedWorkspaceId を渡します。同じ workspace ID を持つ ask は、同じ persistent working directory で操作します。

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

workspace ID には letter、number、underscore、dash を使用できます（最大 200 character）。この option は non-CLI-agent model では無視されます。

MCP を介した Tool​

CLI agent model は、native function calling ではなく MCP を通じて agent の abilities に access します。

  • AI functions および connected integrations は、CLI が invoke できる MCP tool として公開されます
  • Knowledge bases は search tool として公開されます。CLI は prompt 内で取得された context を受け取るのではなく、必要に応じて query します

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

制限事項​

制限詳細
Token streaming なしresponse は run 完了時に届きます。中間 progress には observeStatusUpdates() を使用します。
File upload なしCLI agent model では file upload API はサポートされません
Structured outputresponseFormat: 'json_object' はサポートされます。json_schema format は STRUCTURED_OUTPUT_NOT_SUPPORTED で拒否されます
Chat history APItranscript は CLI session 内にあり、Squid の chat history method では返されません
Conversation ごとに 1 run同じ conversation への concurrent ask は busy error で拒否されます。active run の後で retry してください

Error Handling​

問題原因解決策
ask が API key 欠落 message で失敗する選択した model 用の provider key が設定されていないSettings > AI Settings に Anthropic（Claude Code）または OpenAI（Codex）の key を追加する
Busy / retry response同じ conversation で別の ask がすでに実行中active run の完了を待ってから retry する
run が time limit で終了するtask が maxRuntimeSeconds（または 30 分の最大値）を超過したtask を小さい ask に分割するか、上限まで maxRuntimeSeconds を増やす

ベストプラクティス​

  1. job ID を指定して askAsync() を使用する。 CLI agent run は通常数分かかります。jobを await することで app の応答性を維持し、page reload 後も継続できます（ID を持つ任意の client が await できます）。
  2. progress を表示する。 observeStatusUpdates(jobId) を subscribe し、無言で数分待機する代わりに user が tool activity を確認できるようにします。
  3. interactive flow の runtime を制限する。 user が能動的に待機している場合は quotas.maxRuntimeSeconds を設定し、background task にのみ 30 分すべてを割り当てます。
  4. multi-step workflow には shared workspace を使用する。 stable な sharedWorkspaceId により、連続する ask（または協調する agent）が互いの file を基に作業できます。
  5. reproducibility のために Codex variant を固定する。 codex-gpt-5.5 などは正確な model に固定されます。claude-code-* tier は、各 tier の最新 release を追跡します。

次のステップ​

  • Building AI agents - agent の作成、instructions の設定、model の管理
  • Asynchronous jobs - awaitJob() と getJob() による長時間実行 ask の追跡
  • AI functions - CLI agent が invoke できる backend tool
  • Abilities - knowledge base、integration、tool を agent に接続する