---
title: セルフホスト型サーバーでAPIを呼び出す
url: https://platform.claude.com/docs/ja/managed-agents/self-hosted/call-the-api
description: 公式SDK、cURL、またはant CLIをセルフホスト型Claude Managed Agentsサーバーに向け、セッションを開始して、エージェントの返信を読み取ります。その後、必要に応じて独自のワーカーを接続します。
---

<Note>
  セルフホスト型Claude Managed Agentsへのアクセスをリクエストするには、Anthropicのアカウントチームにお問い合わせください。
</Note>

セルフホスト型Claude Managed Agentsサーバーは、Anthropicのホスト型[Managed Agents](https://platform.claude.com/docs/ja/managed-agents/overview)サービスと同じAPIを備えています。コードからは、公式SDK、cURL、または`ant` CLIで呼び出します。変わる点は2つです。ベースURLはサーバーのアドレスになり、APIキーはClaude APIキーではなく[サーバーAPIキー](https://platform.claude.com/docs/ja/managed-agents/self-hosted#the-three-credentials)になります。

ブラウザでエージェントを作成してセッションを実行するには、[お使いのサーバーでコンソールを使用する](https://platform.claude.com/docs/ja/managed-agents/self-hosted/console)を参照してください。

## 前提条件

* **実行中のサーバー：** [セルフホスト型Claude Managed Agentsを始める](https://platform.claude.com/docs/ja/managed-agents/self-hosted/quickstart)または[Kubernetesにデプロイする](https://platform.claude.com/docs/ja/managed-agents/self-hosted/kubernetes)で起動します。
* **サーバーへのアクセス：** 他の人がサーバーを実行している場合は、そのアドレスと認証方法を問い合わせてください。シングルサインオンを使用している場合は、[開発者がターミナルからログインできるようにする](https://platform.claude.com/docs/ja/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal)を参照してください。
* **`ant` CLI：** [CLIクイックスタート](https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/quickstart#installation)に示すとおり、最新バージョンをインストールしてください。

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

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

[クイックスタートスタック](https://platform.claude.com/docs/ja/managed-agents/self-hosted/quickstart)の場合は、`.env`ファイルがあるディレクトリから次のコマンドを実行します。

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

Kubernetesでは、[セッションを実行する](https://platform.claude.com/docs/ja/managed-agents/self-hosted/kubernetes#run-a-session)に示すとおりに2つの変数を設定し、そのポートフォワードを実行したままにしてください。

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

## セッションを開始する

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

* **エージェント：** クライアントをサーバーに向けた状態で、[エージェントを作成する](https://platform.claude.com/docs/ja/managed-agents/agent-setup#create-an-agent)に示す手順で作成します。生のHTTPリクエストを送信する場合は、URL内の`https://api.anthropic.com`を`$ANTHROPIC_BASE_URL`に置き換えてください。
* **環境：** クイックスタートスタックは`compose-sandbox`という名前の環境を作成し、Helmチャートは`default`という名前の環境を作成します。`ant beta:environments list`で各環境の名前とIDが出力されます。自分のワーカーの場合は、[独自のワーカーを実行する](https://platform.claude.com/docs/ja/managed-agents/self-hosted/call-the-api#point-a-worker-at-your-server)で管理CLIが表示したIDです。

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

```bash
export AGENT_ID=agent_011CYm1BLqPXpQRk5khsSXrs
export ENVIRONMENT_ID=env_01595EKxaaTTGwwY3kyXdtbs
```

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

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body "$ANTHROPIC_BASE_URL/v1/sessions" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "initial_events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENVIRONMENT_ID" \
    --initial-event '{type: user.message, content: [{type: text, text: "List the files in the working directory."}]}'
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";

  const client = new Anthropic();

  const session = await client.beta.sessions.create({
    agent: process.env["AGENT_ID"]!,
    environment_id: process.env["ENVIRONMENT_ID"]!,
    initial_events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });
  console.log(session.id);
  ```

  ```csharp C#
  using System;
  using Anthropic;
  using Anthropic.Models.Beta.Agents;
  using Anthropic.Models.Beta.Sessions;
  using Anthropic.Models.Beta.Sessions.Events;

  AnthropicClient client = new();

  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = Environment.GetEnvironmentVariable("AGENT_ID")!,
      EnvironmentID = Environment.GetEnvironmentVariable("ENVIRONMENT_ID")!,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  Console.WriteLine(session.ID);
  ```

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  )

  func main() {
  	client := anthropic.NewClient()

  	session, err := client.Beta.Sessions.New(context.Background(), anthropic.BetaSessionNewParams{
  		Agent: anthropic.BetaSessionNewParamsAgentUnion{
  			OfString: anthropic.String(os.Getenv("AGENT_ID")),
  		},
  		EnvironmentID: os.Getenv("ENVIRONMENT_ID"),
  		InitialEvents: []anthropic.BetaSessionNewParamsInitialEventUnion{{
  			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  					OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  						Text: "List the files in the working directory.",
  					},
  				}},
  			},
  		}},
  	})
  	if err != nil {
  		panic(err)
  	}
  	fmt.Println(session.ID)
  }
  ```

  ```java Java
  import com.anthropic.client.AnthropicClient;
  import com.anthropic.client.okhttp.AnthropicOkHttpClient;
  import com.anthropic.models.beta.sessions.SessionCreateParams;
  import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var session = client.beta().sessions().create(SessionCreateParams.builder()
          .agent(System.getenv("AGENT_ID"))
          .environmentId(System.getenv("ENVIRONMENT_ID"))
          .addInitialEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .addTextContent("List the files in the working directory.")
              .build())
          .build());
      IO.println(session.id());
  }
  ```

  ```php PHP
  <?php

  use Anthropic\Client;

  $client = new Client();

  $session = $client->beta->sessions->create(
      agent: (string) getenv('AGENT_ID'),
      environmentID: (string) getenv('ENVIRONMENT_ID'),
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );
  echo $session->id, "\n";
  ```

  ```ruby Ruby
  require "anthropic"

  client = Anthropic::Client.new

  session = client.beta.sessions.create(
    agent: ENV.fetch("AGENT_ID"),
    environment_id: ENV.fetch("ENVIRONMENT_ID"),
    initial_events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )
  puts session.id
  ```
</CodeGroup>

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

セッションを監視するには、ブラウザで[お使いのサーバー上のコンソール](https://platform.claude.com/docs/ja/managed-agents/self-hosted/console)を開き、**Sessions**を選択してから、そのセッションを選択します。このページのようにサーバーAPIキーで開始したセッションは、管理者にのみ表示されます。

代わりにターミナルでセッションを追跡するには、そのIDを[`ant beta:sessions connect`](https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/sessions-connect)に渡します。

```bash
ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7
```

エージェントのバージョンの固定など、セッションでできるその他のことについては、[セッションを開始する](https://platform.claude.com/docs/ja/managed-agents/sessions)を参照してください。

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

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

```bash
export SESSION_ID=sesn_011CZkZAtmR3yMPDzynEDxu7
```

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

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

<CodeGroup exclude="shell">
  <CodeGroupItem language="cURL">
    このワークフローには、単一のシェルコマンドよりも多くのロジックが必要です。実行するには、[Anthropic SDK](https://platform.claude.com/docs/ja/cli-sdks-libraries/overview)を使用してください。
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    このワークフローには、単一のシェルコマンドよりも多くのロジックが必要です。ターミナルでメッセージを送信して返信を読むには、[`ant beta:sessions connect`](https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/sessions-connect)を使用してください。
  </CodeGroupItem>

  ```python Python
  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
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";

  const client = new Anthropic();
  const sessionId = process.env["SESSION_ID"]!;

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

  events: for await (const event of stream) {
    switch (event.type) {
      case "agent.message":
        for (const block of event.content) {
          if (block.type === "text") {
            process.stdout.write(block.text);
          }
        }
        break;
      case "session.error":
        console.log(`\n[Error: ${event.error?.message ?? "unknown"}]`);
        break;
      case "session.status_idle":
        if (event.stop_reason.type !== "requires_action") {
          break events;
        }
        break;
      case "session.status_terminated":
        break events;
    }
  }
  ```

  ```csharp C#
  using System;
  using Anthropic;
  using Anthropic.Models.Beta.Sessions.Events;

  AnthropicClient client = new();
  var sessionId = Environment.GetEnvironmentVariable("SESSION_ID")!;

  using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(sessionId);
  await client.Beta.Sessions.Events.Send(sessionId, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Content = [new BetaManagedAgentsTextBlock { Text = "Summarize what you did in one sentence." }],
          },
      ],
  });

  await foreach (var streamEvent in stream.Enumerate())
  {
      if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
      {
          foreach (var block in message.Content)
          {
              if (block.Value is BetaManagedAgentsTextBlock textBlock)
              {
                  Console.Write(textBlock.Text);
              }
          }
      }
      else if (streamEvent.Value is BetaManagedAgentsSessionErrorEvent error)
      {
          Console.WriteLine($"\n[Error: {error.Error?.Message ?? "unknown"}]");
      }
      else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent idle
          && idle.StopReason?.Value is not BetaManagedAgentsSessionRequiresAction)
      {
          break;
      }
      else if (streamEvent.Value is BetaManagedAgentsSessionStatusTerminatedEvent)
      {
          break;
      }
  }
  ```

  ```go Go
  package main

  import (
  	"cmp"
  	"context"
  	"fmt"
  	"os"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  )

  func main() {
  	client := anthropic.NewClient()
  	ctx := context.Background()
  	sessionID := os.Getenv("SESSION_ID")

  	stream := client.Beta.Sessions.Events.StreamEvents(ctx, sessionID, anthropic.BetaSessionEventStreamParams{})
  	defer stream.Close()

  	if _, err := client.Beta.Sessions.Events.Send(ctx, sessionID, anthropic.BetaSessionEventSendParams{
  		Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  					OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  						Text: "Summarize what you did in one sentence.",
  					},
  				}},
  			},
  		}},
  	}); err != nil {
  		panic(err)
  	}

  events:
  	for stream.Next() {
  		switch event := stream.Current().AsAny().(type) {
  		case anthropic.BetaManagedAgentsAgentMessageEvent:
  			for _, block := range event.Content {
  				if block.Type == "text" {
  					fmt.Print(block.Text)
  				}
  			}
  		case anthropic.BetaManagedAgentsSessionErrorEvent:
  			fmt.Printf("\n[Error: %s]\n", cmp.Or(event.Error.Message, "unknown"))
  		case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
  			if _, paused := event.StopReason.AsAny().(anthropic.BetaManagedAgentsSessionRequiresAction); !paused {
  				break events
  			}
  		case anthropic.BetaManagedAgentsSessionStatusTerminatedEvent:
  			break events
  		}
  	}
  	if err := stream.Err(); err != nil {
  		panic(err)
  	}
  }
  ```

  ```java Java
  import com.anthropic.client.AnthropicClient;
  import com.anthropic.client.okhttp.AnthropicOkHttpClient;
  import com.anthropic.core.JsonObject;
  import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams;
  import com.anthropic.models.beta.sessions.events.EventSendParams;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();
      var sessionId = System.getenv("SESSION_ID");

      try (var stream = client.beta().sessions().events().streamStreaming(sessionId)) {
          client.beta().sessions().events().send(
              sessionId,
              EventSendParams.builder()
                  .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
                      .addTextContent("Summarize what you did in one sentence.")
                      .build())
                  .build()
          );

          events:
          for (var event : stream) {
              switch (event.type().value()) {
                  case AGENT_MESSAGE -> {
                      for (var block : event.asAgentMessage().content()) {
                          block.text().ifPresent(textBlock -> IO.print(textBlock.text()));
                      }
                  }
                  case SESSION_ERROR -> {
                      var errorMessage =
                          event.asSessionError().error()._json().orElse(null) instanceof JsonObject json
                              ? json.values().get("message").asStringOrThrow()
                              : "unknown";
                      IO.println("\n[Error: " + errorMessage + "]");
                  }
                  case SESSION_STATUS_IDLE -> {
                      if (!event.asSessionStatusIdle().stopReason().isRequiresAction()) {
                          break events;
                      }
                  }
                  case SESSION_STATUS_TERMINATED -> {
                      break events;
                  }
                  default -> {}
              }
          }
      }
  }
  ```

  ```php PHP
  <?php

  use Anthropic\Beta\Sessions\Events\ManagedAgentsAgentMessageEvent;
  use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionErrorEvent;
  use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionRequiresAction;
  use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent;
  use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusTerminatedEvent;
  use Anthropic\Beta\Sessions\Events\ManagedAgentsTextBlock;
  use Anthropic\Client;

  $client = new Client();
  $sessionId = (string) getenv('SESSION_ID');

  $stream = $client->beta->sessions->events->streamStream($sessionId);
  $client->beta->sessions->events->send(
      $sessionId,
      events: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'Summarize what you did in one sentence.']],
          ],
      ],
  );

  foreach ($stream as $event) {
      switch (true) {
          case $event instanceof ManagedAgentsAgentMessageEvent:
              foreach ($event->content as $block) {
                  if ($block instanceof ManagedAgentsTextBlock) {
                      echo $block->text;
                  }
              }
              break;
          case $event instanceof ManagedAgentsSessionErrorEvent:
              printf("\n[Error: %s]\n", $event->error->message);
              break;
          case $event instanceof ManagedAgentsSessionStatusIdleEvent:
              if (!($event->stopReason instanceof ManagedAgentsSessionRequiresAction)) {
                  break 2; // Break foreach loop
              }
              break;
          case $event instanceof ManagedAgentsSessionStatusTerminatedEvent:
              break 2; // Break foreach loop
      }
  }
  $stream->close();
  ```

  ```ruby Ruby
  require "anthropic"

  client = Anthropic::Client.new
  session_id = ENV.fetch("SESSION_ID")

  stream = client.beta.sessions.events.stream_events(session_id)

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

  stream.each do |event|
    case event
    when Anthropic::Beta::Sessions::BetaManagedAgentsAgentMessageEvent
      event.content.each do |block|
        print block.text if block.is_a?(Anthropic::Beta::Sessions::BetaManagedAgentsTextBlock)
      end
    when Anthropic::Beta::Sessions::BetaManagedAgentsSessionErrorEvent
      puts "\n[Error: #{event.error&.message || "unknown"}]"
    when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
      break unless event.stop_reason.is_a?(Anthropic::Beta::Sessions::BetaManagedAgentsSessionRequiresAction)
    when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusTerminatedEvent
      break
    else
      # その他のイベントタイプは無視します
    end
  end
  ```
</CodeGroup>

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

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

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

* **カスタムツールの呼び出し、またはツール呼び出しの確認リクエスト：** これに応答できるのはあなたのコードだけです。エージェントがこれらのいずれかを使用する場合は、[セッションを一時停止させるツール呼び出しに応答する](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session)を参照してください。
* **`bash`などのワーカーが実行するツールの呼び出し：** この呼び出しは、通常はセッションを一時停止させません。約3分間どのワーカーも呼び出しを引き受けない場合、ワーカーが結果を返すまでセッションは一時停止します。その場合、コードが応答するものはありません。ストリームを開いたままにしておくと、ワーカーが呼び出しを実行したときにターンが再開されます。

セッションが送信するその他のイベントと、イベントを見逃さずに再接続する方法については、[セッションイベントストリーム](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming)を参照してください。

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

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

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

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

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

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

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

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

セッションごとのコンテナを自分で起動する場合は、セッションの入力ファイルを含むディレクトリをコンテナの作業ディレクトリとしてマウントします。コンテナの終了後に、そこから出力ファイルを回収します。[セッション用のファイルをステージングする](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-workers#stage-files-for-a-session)を参照してください。

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

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

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

| タスク                             | ホスト型ガイド                                                                                                                                                | お使いのサーバーでは                                                                                                                                                                                                                                   |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| エージェントのモデル、システムプロンプト、バージョンを設定する | [エージェントを定義する](https://platform.claude.com/docs/ja/managed-agents/agent-setup)                                                                          | 一部のフィールドは[推論プロバイダーによって異なります](https://platform.claude.com/docs/ja/managed-agents/self-hosted/differences#differences-that-depend-on-your-inference-provider)。                                                                                 |
| 組み込みツールを選択する、またはカスタムツールを追加する    | [ツール](https://platform.claude.com/docs/ja/managed-agents/tools)                                                                                        | ウェブツールを使用するには、[ウェブツールにはサーバー設定が必要](https://platform.claude.com/docs/ja/managed-agents/self-hosted/differences#web-tools-need-a-server-setting)で説明しているとおり、まず有効にしてください。どのツールが存在するかは推論プロバイダーによって異なります。                                           |
| MCPサーバーを接続してそのトークンを保存する         | [MCPコネクター](https://platform.claude.com/docs/ja/managed-agents/mcp-connector)および[Vaultで認証する](https://platform.claude.com/docs/ja/managed-agents/vaults) | MCPサーバーのホストを[MCPサーバーの許可リスト](https://platform.claude.com/docs/ja/managed-agents/self-hosted/differences#mcp-servers-need-an-allowlist-entry)に追加します。トークンは`static_bearer`認証情報として保存します。                                                          |
| エージェントにスキルを与える                  | [スキル](https://platform.claude.com/docs/ja/managed-agents/skills)                                                                                       | サーバーはzipアーカイブを拒否するため、各スキルを個別のファイルとしてアップロードします。そのガイドの例にある[構築済みスキル](https://platform.claude.com/docs/ja/managed-agents/self-hosted/differences#features-that-arent-available)は利用できません。                                                         |
| セッション間でメモリを保持する                 | [エージェントメモリの使用](https://platform.claude.com/docs/ja/managed-agents/memory)                                                                              | 自分のワーカーを実行する場合は、[セルフホスト型サンドボックスのメモリストア](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-memory)のように、書き込み可能な`/mnt/memory`ディレクトリをワーカーに与えます。                                                                           |
| 他のエージェントに作業を引き渡す                | [マルチエージェントオーケストレーション](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration)                                                     | そのガイドの例にある`multiagent_20261001`ブロックを[`coordinator`ブロック](https://platform.claude.com/docs/ja/managed-agents/self-hosted/differences#features-that-behave-differently)に置き換えます。                                                                 |
| Gitリポジトリで作業する                   | [GitHubへのアクセス](https://platform.claude.com/docs/ja/managed-agents/github)                                                                              | [Gitリポジトリには許可リストのエントリが必要](https://platform.claude.com/docs/ja/managed-agents/self-hosted/differences#git-repositories-need-an-allowlist-entry)で説明しているとおり、サーバーの設定でGitホストを登録します。そのガイドのサンプルエージェントには、MCPサーバーの許可リストに`api.githubcopilot.com`も必要です。 |
| 採点者にルーブリックに照らして作業を確認させる         | [成果を定義する](https://platform.claude.com/docs/ja/managed-agents/define-outcomes)                                                                          | ルーブリックはテキストとして送信します。Files APIは利用できないため、作業ディレクトリから[出力ファイルを回収します](https://platform.claude.com/docs/ja/managed-agents/self-hosted/call-the-api#move-data-in-and-out-of-a-session)。                                                              |
| セッションを追跡してそのツール呼び出しに応答する        | [セッションイベントストリーム](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming)                                                              | そのガイドの最初の例は一時停止のたびにストリームを閉じるため、代わりに[メッセージを送信して返信を読み取る](https://platform.claude.com/docs/ja/managed-agents/self-hosted/call-the-api#send-a-message-and-read-the-reply)のループから始めてください。                                                          |

[ホスト型サービスとの違い](https://platform.claude.com/docs/ja/managed-agents/self-hosted/differences)に完全な一覧があります。既存のアプリケーションを移行する前に確認してください。

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

[クイックスタートスタック](https://platform.claude.com/docs/ja/managed-agents/self-hosted/quickstart)は環境を作成してそのワーカーを実行します。[Kubernetesにデプロイする](https://platform.claude.com/docs/ja/managed-agents/self-hosted/kubernetes)のHelmチャートも同様です。それらのワーカーだけで十分な場合は、このセクションは読み飛ばしてください。

ワーカーは、[セルフホスト型サンドボックス](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes)の場合と同じように実行します。[セルフホストワーカーをデプロイする](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-workers)に示す方法で、同じ`ant beta:worker`コマンドとSDKワーカーを使用します。例外はWebhookによってトリガーされるワーカーです。お使いのサーバーはWebhookを送信しないためです。

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

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

* **クイックスタートスタックを実行しているマシン上のワーカー：** `http://127.0.0.1:8400`
* **別のマシン上のワーカー：** [サーバーの前段に配置したTLSプロキシ](https://platform.claude.com/docs/ja/managed-agents/self-hosted/kubernetes#put-tls-in-front-of-the-server)の`https`アドレス

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

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

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

```text wrap
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日後に機能しなくなります。それまでに、[自分のワーカー用の環境キーを置き換える](https://platform.claude.com/docs/ja/managed-agents/self-hosted/kubernetes#replace-an-environment-key-for-your-own-workers)の手順に従ってください。

ワーカーを実行するマシンにはサーバーAPIキーを置かないでください。保護が必要なものを何も含まないコンテナまたはVMでワーカーを実行してください。その他のセキュリティ上の責務については、[お客様のセキュリティ上の責任](https://platform.claude.com/docs/ja/managed-agents/self-hosted#your-security-responsibilities)を参照してください。

### ローカルで実験する

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

```bash
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つのサンドボックスを実行する](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session)に示すとおりセッションごとに1つのコンテナを起動し、その中で`ant beta:worker run`を実行します。そのイメージには[独自のサンドボックスイメージを構築する](https://platform.claude.com/docs/ja/managed-agents/self-hosted/call-the-api#build-your-own-sandbox-image)に記載されているものを含め、そのセットアップで次の3点を変更します。

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

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

* **バージョン：** [SDK、CLI、ライブラリ](https://platform.claude.com/docs/ja/cli-sdks-libraries/overview)で説明しているとおり、ワーカーはSDKの最新バージョンで構築してください。そのバージョンのワーカーは、承認が必要なツール呼び出しを実行する前に承認を待ち、ポリシーで拒否された呼び出しは決して実行しません。以前のバージョンで構築したワーカーは、すべてのツール呼び出しを届いた時点ですぐに実行します。
* **サンプル：** [サンドボックス内でSDKワーカーを実行する](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-workers#run-the-sdk-worker-inside-the-sandbox)のサンプルは環境キーを読み取るため、ここではそのままでは動作しません。

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

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

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

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

  ```dockerfile
  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」（エグレスゲートウェイ）](https://platform.claude.com/docs/ja/managed-agents/self-hosted/agent-identity#environment-variable-credentials)を実行している場合、このスクリプトはセッションのツールをそのゲートウェイに向けます。
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`を設定してそのプロセスを起動します。
* [本番環境でワーカーを実行する](https://platform.claude.com/docs/ja/managed-agents/self-hosted/call-the-api#run-workers-in-production)で説明している変更を加え、各セッションのイメージを[独自のサンドボックスイメージを構築する](https://platform.claude.com/docs/ja/managed-agents/self-hosted/call-the-api#build-your-own-sandbox-image)と照らし合わせて確認します。

## 次のステップ

* [開発者がターミナルからログインできるようにする](https://platform.claude.com/docs/ja/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal)：シングルサインオンを設定し、開発者が`ANTHROPIC_API_KEY`が設定されていないターミナルで、自分のIDで`ant` CLIを使用できるようにします。
* [エージェントアイデンティティと認証情報](https://platform.claude.com/docs/ja/managed-agents/self-hosted/agent-identity)：外部システムがエージェントを信頼できるようにし、ボールトの認証情報をシークレットマネージャーに保管します。
* [推論プロバイダー](https://platform.claude.com/docs/ja/managed-agents/self-hosted/inference-provider)：モデル呼び出しをクラウドプロバイダーまたは独自のモデルゲートウェイに送信します。