VPSでClaudeのAIエージェントを構築する方法

Claude でエージェントを構築するとは

Claude でエージェントを構築するとは、Claude を推論の中核として使い、ループ、ツール、データを自分のサーバー上で管理することです。Claude が実行内容を決定し、VPS がそれを実行します。タスクと現在の状態を Claude に送信すると、Claude は回答またはツール使用の要求を返します。コードでツールを実行し、その結果を Claude に返すと、ジョブが完了するまでループが続きます。インターネット経由で呼び出すサービスが推論を担います。それ以外のすべては自分で管理します。

この分離が利点です。モデルを運用せずに最先端レベルの推論を利用でき、ツールは自分が所有するハードウェア上で実行されるため、エージェントがアクセスできる対象を完全に制御できます。すでに最初の Claude プログラムを構築している場合は、VPS 上で最初の Claude アプリを構築するガイドで、このチュートリアルの基礎となる手順を確認できます。

Claude が中核を担う: Messages API

Claude へのすべての呼び出しは、1 つのエンドポイントである Messages API を経由します。これまでの会話と、エージェントが使用できるツールの一覧を送信すると、Claude は次のメッセージを返します。そのメッセージは、最終回答か、ツール呼び出しの要求のいずれかです。自分で構築する方法では、独立した「agent API」はありません。ツールの使用はこの単一エンドポイントの機能であり、その周囲のループは自分で実行します。

Claude は呼び出し間で状態を保持しません。つまり、Claude 自身は何も記憶しません。各リクエストには会話全体を含めます。コードで履歴を保持し、各ターンで送信するため、長いセッションでは各ターンのコストが前のターンより多くのトークンになります。これは単純な制限というより、設計上の選択です。状態が自分のサーバーに保存されるため、Claude に見せる内容を正確に決められます。また、タスクに関する情報が、自分で管理できない場所に保存されることもありません。ただし、プロンプトは増え続けます。Claude のコンテキストウィンドウでは問題なく処理できますが、同じループ内のローカルモデルでは処理できません。そのため、長いプロンプトの切り詰めを止めるには Ollama の num_ctx を増やす必要があります。

Tool use はエージェントループです

Claude を使うエージェントループは、簡単に説明できます。使用するツールを含むリクエストを送信すると、Claude はタスクを読み取り、処理が必要な場合は、ツール名と入力値を指定したツール使用リクエストを返します。コードでそのツールを実行し、次のリクエストで結果を Claude に返します。Claude は結果を読み取り、別のツールを要求するか、最終回答を作成します。ツールの要求を停止した時点で、タスクは完了です。

このループは数行のコードで手作業により記述できます。実際、多くの人がこの方法を使います。処理の流れを把握しやすく、制御もしやすいためです。公式 SDK には、ループを代わりに実行する tool runner も用意されています。ツール関数を渡すと、SDK が Claude の呼び出し、ツールの実行、結果の返却を、Claude が処理を完了するまで繰り返します。どちらの方法でも、基本的な構造は同じです。runner は、ループを自分で記述する手間を省くだけです。ループがまだ抽象的に感じられる場合は、runner を使う前に最小限のループを記述してください。これは、AI エージェントをゼロから学ぶための段階的な学習パスで、他のすべての基礎となる手順です。

ビルド方法は3つ。VPSに適した方法

Claude エージェントの構築方法は3つあります。実行する仕組みをどこまで自分で管理するかが異なります。

1つ目は、自分のコードから Claude API を呼び出し、自分で用意したツールを使う方法です。ループを自分で実装するか、SDK の tool runner を使用し、全体を VPS でホストします。ツール、データ、セキュリティを完全に制御でき、サーバー上の通常のプログラムとして実行できるため、一般的な選択肢です。このガイドの大部分は、この方法を前提にしています。

2つ目は Claude Agent SDK です。これは、コーディングエージェントである Claude Code を、拡張可能なライブラリとしてパッケージ化したものです。ファイルの読み書き、シェルコマンドの実行、検索に対応する完全なエージェントループと組み込みツールが含まれているため、それらを最初から組み立てる必要はありません。これも自分のサーバーで実行できるため、エージェントの実行基盤を自作せずに、ファイル操作とシェル操作に対応する高機能なエージェントを使いたい場合に VPS とよく適合します。ファイルを読み取り、シェルコマンドを実行するエージェントを無人で動かすには、事前に隔離が必要です。サーバー上で Claude Code を安全に実行する方法では、権限システム、サンドボックス、隔離の選択肢を説明しています。

3つ目は Managed Agents です。Anthropic がループを実行し、エージェントのツールを実行するサンドボックスをホストします。これは運用を任せられる方法です。管理する対象は大幅に減りますが、エージェントのワークスペースは VPS ではなく Anthropic のインフラストラクチャ上に置かれます。運用作業を最小限に抑えたい場合や、ツールを自分のマシンで実行する必要がない場合に適しています。残りの2つの方法では、エージェントは自分のサーバーを拠点として動作します。このガイドでは、その構成を扱います。

MCP でツールを接続する

どの方法を選んでも、エージェントを実際のシステムに接続する必要があります。そのための整理された方法が Model Context Protocol です。MCP は、ツールとデータをエージェントに公開するためのオープン標準です。サービスごとに連携処理を手作業で実装するのではなく、必要な機能をすでにツールとして提供している MCP server を Claude に指定します。MCP server は、同じ VPS 上で小規模なサービスとして実行できます。各 server には必要なアクセス権だけを与えます。詳しくは VPS 上で MCP server を実行する で説明します。

モデルの選択

Claude には複数のモデルがあり、能力、速度、コストのバランスを考えて選ぶ必要があります。本稿執筆時点で主な選択肢は Claude Opus 4.8 (claude-opus-4-8)、難しい推論や長時間のエージェント実行に適した、十分な能力を持つデフォルトモデルです。Claude Sonnet 5 (claude-sonnet-5) は、コストと速度を抑えながら、多くのタスクで Opus に近い性能を維持するバランスのよい選択肢です。Claude Haiku 4.5 (claude-haiku-4-5) は最も高速かつ低コストで、単純な大量処理に適しています。これらの上位には Claude Fable 5 (claude-fable-5) があり、最も高い能力を持つモデルとして、特に難しい処理に使用します。コードでは正確なモデル識別子を使用し、日付は付けません。

実用上は、これらを組み合わせる方法が有効です。定型的なツール呼び出しは低コストのモデルに任せ、難しい判断はより高性能なモデルに処理させます。リクエスト内でモデルは単なる文字列として指定されるため、切り替えは1行の変更で済みます。まず十分な能力を持つデフォルトモデルから始め、品質のわずかな差より速度やコストを優先する処理では、より低コストのモデルに調整します。

VPS 上で強化されたサービスとして実行する

エージェントは稼働し続けて初めて役に立ち、隔離されて初めて安全になります。VPS では、端末で手動起動したプログラムではなく、強化された systemd サービスとしてエージェントを実行することで、これらを実現できます。サービスとして実行すると、ブート時に起動し、クラッシュ時に再起動し、journal にログを記録します。強化されたサービスでは、必要なアクセスだけを持つ非特権ユーザーとして実行するため、バグや不正な指示が発生しても影響範囲を制限できます。サービス unit で制限できるのは、プロセスがアクセスできる対象だけです。その他の制御はエージェントのハーネス自体に組み込む必要があります。別のスタックで 導入する価値のある DeepSeek Harness プラグイン が担うのは、利用上限、ツールごとの権限ルール、プロンプトインジェクションのスキャンです。

最も重要なルールは、Claude API key をサーバー側だけに置くことです。この key はすべての呼び出しの料金支払いと認証に使用されるため、エージェントのユーザーだけが読み取れるファイルに保存し、サービスの環境変数として読み込ませます。コード、repository、ブラウザーからアクセスできる場所には、決して配置しないでください。ここでエージェント用の完全に強化されたサービス unit を生成します。

続いて、サーバー自体も設定します。VPS の SSH 強化 と同様に、SSH は key 認証だけにし、管理に使用するアカウントへのアクセスを制限します。構築中に対話的なセッションからエージェントを操作したい場合は、tmux を使って VPS 上で Claude Code を実行する 方法が役立ちます。同じホストで 2 つ目のセッションを開けば、2 つのセッション間で作業を受け渡せる ため、各ペイン間ですべての指示を手動で伝える必要がなくなります。これらの仕組みの背景にある概念を、特定の model に依存せずに理解したい場合は、姉妹ガイドの VPS 上で独自の AI エージェントを構築する で基礎を説明しています。

端末で動作するコーディングアシスタントを求めている場合は、VPS 上でコーディング AI エージェントを実行する で Aider と Goose を取り上げています。

FAQ

エージェントの構築にはどの Claude モデルを使うべきですか？

まず、性能の高い標準モデルである Claude Opus 4.8（claude-opus-4-8）から始めて、必要に応じて調整します。Claude Sonnet 5（claude-sonnet-5）は多くの処理でより安価かつ高速です。Claude Haiku 4.5（claude-haiku-4-5）は、単純な処理を大量に実行する場合に適しています。Claude Fable 5（claude-fable-5）は、最も難しいタスクに適した、最も高性能なモデルです。一般的には、定型処理に安価なモデルを使い、難しい判断には高性能なモデルを使います。切り替えは 1 行の変更で済むためです。

エージェント全体を自分の VPS で実行しますか、それとも Anthropic が実行しますか？

方法によって異なります。Claude API を使って独自のループを実装する場合や、Claude Agent SDK を使う場合、エージェントはすべて自分の VPS で実行され、Anthropic へ送られるのはモデル呼び出しだけです。Managed Agents を使う場合は、Anthropic がループを実行し、ツールが動作する sandbox もホストするため、自分のサーバー上で実行する部分が少なくなります。自分のマシンでエージェントを実行する場合は、最初の 2 つの方法のいずれかを使います。

Claude API と Claude Agent SDK の違いは何ですか？

Claude API は、生の Messages endpoint です。会話とツールを送信し、その周囲にエージェントループを自分で実装するか、SDK の tool runner を使って実行します。Claude Agent SDK は、構築用にパッケージ化された Claude Code を基盤とする、より高水準のライブラリです。完全なループと、ファイル、shell、search 用の組み込みツールが含まれています。すべてを自分で定義する場合は API を使い、実行基盤を組み立てずに高性能なエージェントを使いたい場合は Agent SDK を使います。

サーバー上で Claude API key を安全に管理するにはどうすればよいですか？

サーバー側で管理し、コードから分離します。エージェントの実行アカウントだけが読み取れるファイルに保存し、環境変数としてサービスに読み込ませます。リポジトリに commit したり、ブラウザーに公開したりしてはいけません。Claude へのすべてのリクエストはサーバーから送信されるため、key をユーザーのデバイスへ渡す必要はありません。この点により、サーバーで実行するエージェントは、クライアントアプリに組み込んだエージェントより安全に保護しやすくなります。

Claude でエージェントを構築するには、モデルを自分でホストする必要がありますか？

いいえ。Claude では、API 経由で呼び出すホスト型サービスとしてモデルが提供されるため、GPU 上で実行するものはありません。VPS ではエージェントループ、ツール、データを実行し、推論は Anthropic 側で行われます。そのため、比較的小規模なサーバーでも高性能なエージェントを実行できます。完全にローカルなモデルを使いたい場合は、独自の AI エージェントを構築する関連ガイドで説明している self-hosted の方法を使います。