セルフホスト型サーバーでAPIを呼び出す

セルフホスト型Claude Managed Agentsサーバーは、Anthropicのホスト型Managed Agentsサービスと同じAPIを備えています。コードからは、公式SDK、cURL、またはant CLIで呼び出します。変わる点は2つです。ベースURLはサーバーのアドレスになり、APIキーはClaude APIキーではなくサーバーAPIキーになります。

ブラウザでエージェントを作成してセッションを実行するには、お使いのサーバーでコンソールを使用するを参照してください。

前提条件

• 実行中のサーバー： セルフホスト型Claude Managed Agentsを始めるまたはKubernetesにデプロイするで起動します。
• サーバーへのアクセス： 他の人がサーバーを実行している場合は、そのアドレスと認証方法を問い合わせてください。シングルサインオンを使用している場合は、開発者がターミナルからログインできるようにするを参照してください。
• ant CLI： CLIクイックスタートに示すとおり、最新バージョンをインストールしてください。

クライアントをサーバーに向ける

SDKとant CLIは、サーバーのアドレスをANTHROPIC_BASE_URLから、APIキーをANTHROPIC_API_KEYから読み取ります。このサーバー用に確保しておくターミナルで両方の変数を設定します。

クイックスタートスタックの場合は、.envファイルがあるディレクトリから次のコマンドを実行します。

export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

Kubernetesでは、セッションを実行するに示すとおりに2つの変数を設定し、そのポートフォワードを実行したままにしてください。

そのターミナルでは、ant beta:agents listなどのすべてのantコマンドがサーバーに届きます。Claude Codeやdocker composeは同じ変数を読み取るため、そのターミナルでは実行しないでください。

セッションを開始する

セッションには、エージェントのIDと環境のIDが必要です。

• エージェント： クライアントをサーバーに向けた状態で、エージェントを作成するに示す手順で作成します。生のHTTPリクエストを送信する場合は、URL内のhttps://api.anthropic.comを$ANTHROPIC_BASE_URLに置き換えてください。
• 環境： クイックスタートスタックはcompose-sandboxという名前の環境を作成し、Helmチャートはdefaultという名前の環境を作成します。ant beta:environments listで各環境の名前とIDが出力されます。自分のワーカーの場合は、独自のワーカーを実行するで管理CLIが表示したIDです。

次の例のIDの代わりに、2つのIDをシェルに設定します。

export AGENT_ID=agent_011CYm1BLqPXpQRk5khsSXrs
export ENVIRONMENT_ID=env_01595EKxaaTTGwwY3kyXdtbs

次の例では、セッションを作成し、同じリクエストで最初のメッセージを送信します。

import os

from anthropic import Anthropic

client = Anthropic()

session = client.beta.sessions.create(
    agent=os.environ["AGENT_ID"],
    environment_id=os.environ["ENVIRONMENT_ID"],
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
print(session.id)

レスポンスには、sesn_で始まるセッションのIDが含まれます。エージェントはすぐに作業を開始します。bashなどの組み込みツールは、環境を提供する「worker」（ワーカー）上で実行されます。

セッションを監視するには、ブラウザでお使いのサーバー上のコンソールを開き、Sessionsを選択してから、そのセッションを選択します。このページのようにサーバーAPIキーで開始したセッションは、管理者にのみ表示されます。

代わりにターミナルでセッションを追跡するには、そのIDをant beta:sessions connectに渡します。

ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7

エージェントのバージョンの固定など、セッションでできるその他のことについては、セッションを開始するを参照してください。

メッセージを送信して返信を読み取る

次の例のIDの代わりに、セッションのIDをシェルに設定します。

export SESSION_ID=sesn_011CZkZAtmR3yMPDzynEDxu7

次の例を実行する前に、セッションがアイドル状態になるまで待ってください。この例はターンが終了すると読み取りを停止します。以前のターンがまだ実行中の場合、そのターンの終了によって、メッセージへの返信が届く前に例が停止することがあります。セッションのステータスは、コンソールとant beta:sessions connectの両方に表示されます。

次の例では、メッセージを送信し、エージェントの返信を出力します。ストリームは開いた後に発生したイベントのみを配信するため、この例では最初にセッションのイベントストリームを開きます。

import os

from anthropic import Anthropic

client = Anthropic()
session_id = os.environ["SESSION_ID"]

with client.beta.sessions.events.stream(session_id) as stream:
    client.beta.sessions.events.send(
        session_id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {"type": "text", "text": "Summarize what you did in one sentence."}
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.error":
                error_message = event.error.message if event.error else "unknown"
                print(f"\n[Error: {error_message}]")
            case "session.status_idle":
                if event.stop_reason.type != "requires_action":
                    break
            case "session.status_terminated":
                break

agent.messageのテキストを出力するほかに、ループは3つのイベントを処理します。

• session.status_idle： イベントのstop_reason.typeがrequires_actionでない限り、ループは終了します。
• session.status_terminated： ループは終了します。
• session.error： サーバーは失敗したモデル呼び出しを再試行してターンを完了できるため、ループはエラーのメッセージを出力して読み取りを続けます。

requires_actionは、セッションがツール呼び出しのために一時停止したことを意味します。一時停止を終わらせる方法は、呼び出しによって異なります。

• カスタムツールの呼び出し、またはツール呼び出しの確認リクエスト： これに応答できるのはあなたのコードだけです。エージェントがこれらのいずれかを使用する場合は、セッションを一時停止させるツール呼び出しに応答するを参照してください。
• bashなどのワーカーが実行するツールの呼び出し： この呼び出しは、通常はセッションを一時停止させません。約3分間どのワーカーも呼び出しを引き受けない場合、ワーカーが結果を返すまでセッションは一時停止します。その場合、コードが応答するものはありません。ストリームを開いたままにしておくと、ワーカーが呼び出しを実行したときにターンが再開されます。

セッションが送信するその他のイベントと、イベントを見逃さずに再接続する方法については、セッションイベントストリームを参照してください。

セッションとの間でデータをやり取りする

データは、ワーカーの作業ディレクトリを通じてセッションに入り、セッションから出ていきます。

クイックスタートスタックでは、各セッションのコンテナは、セッションのリポジトリのクローンを除いて空の/workspaceディレクトリで起動します。デフォルトでは、ターンが終了してから約1分後にコンテナが終了し、Dockerがそのディレクトリごとコンテナを削除します。セッションが保持する必要のあるものは、それまでにアップロードやgit pushなどのツール呼び出しを通じて外部に出す必要があります。

コンテナは、ターンの途中であっても、起動から約1時間後にも終了します。これを変更する設定はありません。ターンは新しいコンテナで継続され、通常は1〜2分後に再開されます。この切り替えについてクライアントにイベントは届きません。この切り替えには2つのコストがあります。

• コマンド： 古いコンテナで実行されているものはすべて停止します。新しいコンテナは中断されたツール呼び出しを最初から再実行しますが、エージェントがバックグラウンドで実行したままにしていたコマンドは何も再起動されません。
• ファイル： 新しいコンテナの/workspaceは、セッションのリポジトリを新たにクローンしたものを除いて、再び空になります。

長いターンでは、エージェントに作業を進めながらアップロードまたはプッシュさせ、2回実行されると害を及ぼすコマンドは避けてください。

Kubernetesでは、セッションが1つのポッドを保持するのは最大で約1時間であり、ターンは同じ方法で継続されます。異なる点は2つあります。新しいポッドは/workspace内にセッションのファイルを見つけます。また、新しいポッドは古いポッドが停止してから約6分後に起動します。

自分で起動するワーカーの場合は、入力ファイルを、それを必要とするメッセージを送信する前に作業ディレクトリに置いてください。出力ファイルはその後にそこから読み取ります。

セッションごとのコンテナを自分で起動する場合は、セッションの入力ファイルを含むディレクトリをコンテナの作業ディレクトリとしてマウントします。コンテナの終了後に、そこから出力ファイルを回収します。セッション用のファイルをステージングするを参照してください。

ホスト型ガイドでさらに例を見つける

ホスト型サービスのガイドでは、APIのコアコンセプトを説明し、各機能の例を掲載しています。これらのガイドにあるSDKとCLIの例は、ANTHROPIC_BASE_URLとANTHROPIC_API_KEYを設定したターミナルで実行すると、お使いのサーバーを呼び出します。cURLの例ではhttps://api.anthropic.comが指定されているため、実行する前にそのアドレスを$ANTHROPIC_BASE_URLに置き換えてください。

一部の機能では、お使いのサーバーで事前に設定が必要になるか、例に変更が必要になります。

ホスト型サービスとの違いに完全な一覧があります。既存のアプリケーションを移行する前に確認してください。

独自のワーカーを実行する

クイックスタートスタックは環境を作成してそのワーカーを実行します。KubernetesにデプロイするのHelmチャートも同様です。それらのワーカーだけで十分な場合は、このセクションは読み飛ばしてください。

ワーカーは、セルフホスト型サンドボックスの場合と同じように実行します。セルフホストワーカーをデプロイするに示す方法で、同じant beta:workerコマンドとSDKワーカーを使用します。例外はWebhookによってトリガーされるワーカーです。お使いのサーバーはWebhookを送信しないためです。

環境とそのキーを作成する

Claude Consoleではなく、管理CLIで環境と環境キーを作成します。CLIであるcma-server-adminはリリースアーカイブの最上位にあるため、そこからコマンドを実行してください。-base-urlには、ワーカーがサーバーに到達するためのアドレスを渡します。

• クイックスタートスタックを実行しているマシン上のワーカー： http://127.0.0.1:8400
• 別のマシン上のワーカー： サーバーの前段に配置したTLSプロキシのhttpsアドレス

管理CLIは同じアドレスでサーバーを呼び出すため、そのアドレスに到達できるマシンで実行してください。

echo "$ANTHROPIC_API_KEY" | ./cma-server-admin bootstrap \
  -base-url http://127.0.0.1:8400 -name my-env -key-file -

このコマンドは、ワーカーの設定、ワーカーを起動するコマンド、キーのIDと有効期限を表示します。

export ANTHROPIC_BASE_URL='http://127.0.0.1:8400'
export ANTHROPIC_ENVIRONMENT_ID='env_...'
export ANTHROPIC_ENVIRONMENT_KEY='sk-ant-oat01-...'
# then: histchars= HISTFILE=/dev/null ant beta:worker poll --workdir /workspace
# key id: 'etok_...'  expires: '...'

このコマンドはキーを一度しか表示しないため、キー、そのID、有効期限をシークレットマネージャーに保存してください。キーは365日後に機能しなくなります。それまでに、自分のワーカー用の環境キーを置き換えるの手順に従ってください。

ワーカーを実行するマシンにはサーバーAPIキーを置かないでください。保護が必要なものを何も含まないコンテナまたはVMでワーカーを実行してください。その他のセキュリティ上の責務については、お客様のセキュリティ上の責任を参照してください。

ローカルで実験する

ワーカーを起動するシェルで3つのexport行を実行します。次に、表示されたコマンドではなく、以下のコマンドでワーカーを起動します。ワーカーは作業ディレクトリを作成しないため、最初のコマンドでワーカーの作業ディレクトリを作成します。

mkdir -p "$HOME/cma-workspace" "$HOME/.config/cma"
cat > "$HOME/.config/cma/worker.inputrc" <<'EOF'
$include /etc/inputrc
set disable-completion on
EOF
histchars= HISTFILE=/dev/null INPUTRC="$HOME/.config/cma/worker.inputrc" \
  ant beta:worker poll --workdir "$HOME/cma-workspace"

histchars、INPUTRC、HISTFILEは、ワーカーのbashツールの背後にあるシェルを設定し、各コマンドをエージェントが書いたとおりに実行させます。

• histchars=： シェルは!をコマンド履歴への参照として扱いません。
• INPUTRC： このファイルは補完を無効にします。補完が有効なままだと、コマンド内の各タブ文字が消費されてしまいます。エージェントのファイルツールが書き換えられる作業ディレクトリには、このファイルを置かないでください。
• HISTFILE=/dev/null： シェルは履歴ファイルの読み取りも書き込みも行いません。

このワーカーは他の用途には使用しないでください。このワーカーは環境キーを保持し、すべてのセッションのツールを1つのプロセスで実行します。また、セッションのリポジトリもクローンしません。セッションはリポジトリなしで実行され、クライアントにはエラーが返されません。

本番環境でワーカーを実行する

ローカルでの実験以外では、セッションごとに1つのサンドボックスを実行するに示すとおりセッションごとに1つのコンテナを起動し、その中でant beta:worker runを実行します。そのイメージには独自のサンドボックスイメージを構築するに記載されているものを含め、そのセットアップで次の3点を変更します。

• 環境キー： ANTHROPIC_ENVIRONMENT_KEYをセッションのコンテナに渡さないでください。サーバーはそのキーを環境内のすべてのセッションに対して受け付けますが、コンテナが必要とするのは1つのセッションへのアクセスだけです。
• ワークアイテムのシークレット： サーバーはこのシークレットをその1つのセッションに対してのみ受け付けるため、キーの代わりにこのシークレットを渡します。ワークアイテムのシークレットを転送するに、コードがシークレットを受け取る場所が示されています。そのセクションでANTHROPIC_WORK_SECRETを設定している箇所では、コンテナのユーザーだけが読み取れるファイルにシークレットを置きます。たとえば、シークレットをコンテナの標準入力にパイプで渡し、ワーカーを起動する前にコンテナがそのファイルを書き込むようにします。次に、ANTHROPIC_WORK_SECRET_FILEにファイルのパスを設定します。
• サーバーのアドレス： ANTHROPIC_BASE_URLをコンテナから到達できるアドレスに設定します。http://127.0.0.1:8400はそのようなアドレスではありません。

SDKワーカーの場合は、さらに次の2点が当てはまります。

• バージョン： SDK、CLI、ライブラリで説明しているとおり、ワーカーはSDKの最新バージョンで構築してください。そのバージョンのワーカーは、承認が必要なツール呼び出しを実行する前に承認を待ち、ポリシーで拒否された呼び出しは決して実行しません。以前のバージョンで構築したワーカーは、すべてのツール呼び出しを届いた時点ですぐに実行します。
• サンプル： サンドボックス内でSDKワーカーを実行するのサンプルは環境キーを読み取るため、ここではそのままでは動作しません。

独自のサンドボックスイメージを構築する

独自のイメージには、次のパッケージと設定が必要です。

• パッケージ： Git 2.38以降、curl、jq、およびワーカーのgrepツールが検索に使用するripgrep。

• シェル設定： ローカルでの実験と同様のhistchars、HISTFILE、INPUTRC、およびTERMINFO。DockerfileのUSER行より前に、次の行を記述してください。

  ENV histchars=
  RUN printf '\nset disable-completion on\n' >> /etc/inputrc
  ENV INPUTRC=/etc/inputrc TERMINFO=/etc/terminfo HISTFILE=/dev/null
  RUN test -r /etc/terminfo/d/dumb

  

  TERMINFOには、ワーカーのbashが読み取る端末記述であるd/dumbを含むディレクトリを指定する必要があります。bashをインストールしたAlpineでは、例に示すとおり/etc/terminfoです。DebianやUbuntuなどの他のベースでは、/lib/terminfoまたは/usr/share/terminfoのうち、d/dumbを含む方です。そのディレクトリをTERMINFOの設定とRUN test行に記述します。ファイルが存在しない場合、RUN test行によってビルドが停止します。

イメージには、ワーカーの起動前に実行される、アーカイブ内の2つのスクリプトも必要です。

1. image-build/with-repositories.shを/usr/local/bin/cma-with-repositoriesにコピーします。このスクリプトは1つのセッションのリポジトリをクローンします。
2. image-build/with-egress.shを/usr/local/bin/cma-with-egressにコピーします。サーバーが「egress gateway」（エグレスゲートウェイ）を実行している場合、このスクリプトはセッションのツールをそのゲートウェイに向けます。
3. 両方のファイルを実行可能にします。
4. cma-with-egress cma-with-repositories ant beta:worker run ...のように、ワーカーのコマンドの前に両方を付けます。イメージがアーカイブのkubernetes/sandbox/worker.shを実行する場合、そのスクリプトがこの方法でワーカーを起動するため、この手順は省略してください。

cma-with-repositoriesなしで起動したワーカーは、リポジトリなしでセッションを実行します。クライアントにはエラーが返されません。

ホスト型サービスからワーカーを移行する

Anthropicのホスト型サービス用のワーカーをすでに実行している場合は、同じワーカーを代わりにお使いのサーバーで使用できます。次の3つを行います。

• 作業をポーリングするプロセスに、管理CLIが表示した3つのexportの値を渡します。
• ローカルでの実験と同様に、histchars、HISTFILE、INPUTRCを設定してそのプロセスを起動します。
• 本番環境でワーカーを実行するで説明している変更を加え、各セッションのイメージを独自のサンドボックスイメージを構築すると照らし合わせて確認します。

次のステップ

• 開発者がターミナルからログインできるようにする：シングルサインオンを設定し、開発者がANTHROPIC_API_KEYが設定されていないターミナルで、自分のIDでant CLIを使用できるようにします。
• エージェントアイデンティティと認証情報：外部システムがエージェントを信頼できるようにし、ボールトの認証情報をシークレットマネージャーに保管します。
• 推論プロバイダー：モデル呼び出しをクラウドプロバイダーまたは独自のモデルゲートウェイに送信します。