Managed AgentsをConsoleで構築しコードベースに持ち帰る手順

Managed AgentsのConsoleは、モデル・システムプロンプト・ツール・MCPサーバー・Skillsをコードを書かずに設定できる画面です。設定した内容はその場でテストでき、動作を確認したエージェントIDと環境IDをコードにそのまま貼り付けて本番の実装に移れます。この記事ではConsoleでの構築からコードベースへの持ち帰りまでを手順順に追います。

対象は、これからManaged Agentsを触り始める開発者と、非エンジニアも含めたチームでエージェント定義を共同で調整したい担当者の双方です。Consoleの画面操作だけで完結する部分と、コード側に持ち帰って初めて必要になる知識(betaヘッダー・環境IDの扱い)を分けて説明します。Anthropicの営業チームが営業・コンテンツ担当にConsoleでシステムプロンプトを直接編集させた事例は、営業の問い合わせ対応をManaged Agentsで再設計した事例にあります。

Consoleで何ができるか

ConsoleはManaged Agentsのエージェント定義を項目ごとに埋めていく画面です。設定できる項目は次の4つです。

設定を進めるあいだ、Console画面には同等のAPIリクエストが常時表示されます。画面上の操作がそのままリクエストのJSONに反映されるため、満足のいく設定ができた時点でそのリクエストをコピーしてコードに組み込めます。設計・配布方針はAgent SDK入門で扱ったSDKの使い方とも接続しており、Consoleは「コードを書く前に手で試す場所」です。

Managed Agents APIの呼び出しにはmanaged-agents-2026-04-01のbetaヘッダーが必要です。SDKを使う場合は自動で付与されるため、Consoleで作った設定をSDK経由のコードに落とし込む限り、ヘッダーを手で意識する場面はほとんどありません。

なぜConsole経由が合理的か

Managed AgentsはAPIとして直接叩くこともできるので、Consoleを経由せずにコードだけでエージェント定義を書くことも技術的には可能です。それでもConsoleから始める価値があるのは、システムプロンプトとツールの組み合わせを1往復ずつ試す作業が、コードのデプロイなしで完結するためです。JSONのペイロードを直接書き換えてAPIを叩き直す場合、1回の試行にコードの修正・保存・実行という手間が挟まります。Consoleなら設定を直したら、そのままテストセッションを開始できます。システムプロンプトの言い回しやツールの組み合わせを何十パターンも試す初期の試行錯誤フェーズでは、Console経由のほうが手数が少なく済みます。

ステップ1 — Consoleでエージェントを設定する

Console画面を開き、モデル・システムプロンプト・MCPサーバー・ツール・Skillsの4項目を埋めていきます。MCPサーバーを追加する場合は、MCPとはで扱った標準プロトコルの理解があると、どのサーバーをどのツール権限で繋ぐかの判断がしやすくなります。

システムプロンプトは全幅エディターで書けるため、長いプロンプトでも折り返しを気にせず一望できます。ツールは組み込みのエージェントツールセット(ファイル操作やWeb検索など)とMCPツールを組み合わせて選択します。組織でSkillsライブラリを運用している場合は、Anthropic製のSkillsだけでなく自社で作ったカスタムSkillsもここでアタッチできます。

この段階で見落としやすいのは、環境側のネットワーク設定です。Consoleの環境作成フォームは、Limitedを選んだ状態で始まり、許可するホストは1つも入っていません。一方、APIで環境を作るときにnetworkingを省くとunrestrictedになります。Consoleで試した環境とコードで作った環境とで、外部への通信範囲が逆になりうる点です。

limitedでパッケージを事前インストールするときは、allow_package_managersもtrueにします。付け忘れると環境作成が400で拒否されます。allow_mcp_serversも既定はfalseなので、allowed_hostsにないホストのMCPサーバーをエージェントに追加していると、セッション作成が400で失敗します。ホストをallowed_hostsに足すか、allow_mcp_serversをtrueにします。ファイル・メモリストア・GitHubリポジトリなど、セッションに添付したものは許可ホストが空でも使えます。

ステップ2 — インラインセッションランナーでテストする

設定が終わったら、画面を離れずにテストセッションを開始できます。Consoleにはインラインのセッションランナーが組み込まれており、メッセージを送ってイベントストリームをその場で確認できます。

システムプロンプトとツール選択の組み合わせが期待通りの挙動を生むかを確かめる最も速い方法がこのテストです。コードを書いてAPIを叩く前にConsole上で何往復か試し、ツールの呼び出され方やレスポンスの質を見てから次のステップに進むと、コード側のデバッグ時間を減らせます。

特に確認しておきたいのは、MCPサーバーを経由したツール呼び出しが期待通りの引数で実行されているかです。システムプロンプトの指示があいまいだと、モデルは想定と違うパラメーターでツールを呼び出すことがあります。イベントストリームでツール呼び出しの様子を見られるので、Console上で挙動を見ながら調整できます。コードを書いてからログを漁るより手数が少なく済みます。

ステップ3 — エージェントIDと環境IDをコードに持ち帰る

エージェントが期待通りに動いたら、Console画面からエージェントIDと環境IDをコピーします。環境(environment)はエージェント定義とは別に作成するリソースです。セッションが動くサンドボックスの設定(cloudサンドボックスのネットワーク制限や、self-hosted sandboxを使う構成など)をまとめます。同じ環境IDを複数のセッションで使い回せますが、各セッションには独立したサンドボックスが割り当たり、ファイルシステムの状態は共有されません。この2つのIDをセッション作成時に渡すだけで、Console上で組んだエージェントがそのまま動きます。

session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "agent": "agent_01J8XkN5uT3vHpLqRfWdY2",
    "environment_id": "env_01K2mPsT7hNwR4jXuLvCqD8",
    "title": "My first session"
  }')

Python・TypeScript向けのSDKでも同じ2つのIDを渡すだけで完結します。

session = client.beta.sessions.create(
    agent="agent_01J8XkN5uT3vHpLqRfWdY2",
    environment_id="env_01K2mPsT7hNwR4jXuLvCqD8",
    title="My first session",
)

const session = await client.beta.sessions.create({
  agent: "agent_01J8XkN5uT3vHpLqRfWdY2",
  environment_id: "env_01K2mPsT7hNwR4jXuLvCqD8",
  title: "My first session"
});

Go・Java・PHP・Ruby・C#向けのSDKと、ant beta:sessions createコマンドでも、渡すのはエージェントID・環境ID・タイトルの3つです。Consoleでの試行錯誤とコード側の実装が2つのIDで橋渡しされるので、エージェント定義を作り直したときのコード側の変更はIDの差し替えで済みます。

Consoleで直した定義はどのセッションに反映されるか

エージェントは版を持つリソースです。Consoleで定義を直したあと、本番の挙動をいつ切り替えるかは、agentの渡し方で決まります。

版を固定するときのリクエストは次の形です。

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "agent": {"type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2", "version": 1},
    "environment_id": "env_01K2mPsT7hNwR4jXuLvCqD8"
  }'

上書きは値を丸ごと置き換えます。toolsを上書きするなら、そのセッションで使うツールをすべて書き直す必要があります。modelを上書きすると、エージェント側のeffortも引き継がれません。環境には版がないため、頻繁に更新するなら、どのセッションがどの設定だったかを自分で記録しておく必要があります。

Console経由とAPI直書きの使い分け

Consoleと直接のAPI呼び出しは、どちらか一方を選ぶものではなく、開発の段階によって使い分けるのが実装として自然です。

チームで導入する場面では、非エンジニアのメンバーがシステムプロンプトの文言を調整し、エンジニアがConsoleに表示されるAPIリクエストを見てコードに落とし込む、という役割分担も成立します。

よくあるつまずき

• environment_idを別途用意し忘れる: Console画面でコピーできるのはエージェントIDと環境IDの2つですが、環境自体はエージェント定義とは別に用意されている前提です。クラウドサンドボックスかself-hosted sandboxかで挙動が変わるため、どちらの環境IDをコピーしたかを意識してください。複数の環境を切り替えて検証する場合は、環境IDをメモに残す運用にしておくと取り違えを防げます
• beta headerを手動で付け忘れる: SDKを使わずにcURLで直接叩く場合、anthropic-beta: managed-agents-2026-04-01を毎回のリクエストに含める必要があります。memory storeのリクエストでは、managed-agents-2026-04-01をagent-memory-2026-07-22に置き換えます。両方を送ると400になります。メモリストアをセッションに添付するリクエストは、managed-agents-2026-04-01のままです
• Console上のテストと本番コードで別の環境IDを渡してしまう: テストの環境と本番コードの環境とで、ネットワーク制限やパッケージ構成が違うことがあります。その差で、Consoleで通った呼び出しが本番で失敗します。コードに渡す環境IDが、テストに使った環境のものと同じかを確認してください
• modelを上書きしたら思考量が変わった: agent_with_overridesでmodelを差し替えると、エージェント側のeffortは引き継がれず、そのモデルの既定のeffortで動きます。揃えたいときは、上書きのmodelオブジェクトの中にeffortも書きます
• mcp_serversを空にしたら400になった: セッションのtoolsに、そのエージェントのMCPサーバーを参照するmcp_toolsetが残っていると、mcp_serversのクリアは400で失敗します。同じリクエストでtoolsを上書きしてmcp_toolsetを外してから、mcp_serversを空にします
• チーム内でエージェント定義の変更履歴が追えなくなる: エージェントは版番号で管理されますが、変更の理由までは版に残りません。重要な変更のたびに、Consoleに表示されるAPIリクエストをコピーしてリポジトリにも残すと、後から差分を追いやすくなります

まとめ

Consoleは、システムプロンプトとツールの組み合わせを決める場所です。決まった設定はエージェントIDと環境IDでコードに渡し、本番では版の固定とnetworkingの明示で、Consoleで試した条件との差をなくします。