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

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

対象は、これからManaged Agentsを触り始める開発者と、非エンジニアも含めたチームでエージェント定義を共同で調整したい担当者の双方です。Consoleの画面操作だけで完結する部分と、コード側に持ち帰って初めて必要になる知識(betaヘッダー・環境IDの扱い)を分けて説明します。

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もここでアタッチできます。

この段階で決めておく価値があるのは、エージェントに持たせるツールの範囲です。ツールを広く持たせるほどエージェントの守備範囲は広がりますが、その分だけ意図しない操作が起きたときの被害範囲も広がります。まずは最小限のツール構成で動かし始め、実際のタスクで足りない部分が見えてから追加していくほうが、後から権限を絞り込むより安全に運用できます。

ステップ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でも、引数名の書式が変わるだけで渡すものは同じくエージェントID・環境ID・タイトルの3つです。どの言語を選んでも、Consoleで固めた設定を再現するための入力は増えません。Consoleでの試行錯誤とコード側の実装が同じ2つのIDだけで橋渡しされる設計なので、Console上で何度エージェント定義を作り直しても、コード側の変更はIDの差し替えだけで済みます。

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

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

チームでManaged Agentsを初めて導入する場面では、非エンジニアのメンバーがシステムプロンプトの文言を調整し、エンジニアがConsoleの右側に表示されるAPIリクエストを見てコードに落とし込む、という役割分担も成立します。Console画面自体がドキュメントとして機能するため、「このエージェントはどう設定されているか」を口頭やSlackで説明する手間も減らせます。

よくあるつまずき

• environment_idを別途用意し忘れる: Console画面でコピーできるのはエージェントIDと環境IDの2つですが、環境自体はエージェント定義とは別に用意されている前提です。クラウドサンドボックスかself-hosted sandboxかで挙動が変わるため、どちらの環境IDをコピーしたかを意識してください。複数の環境を切り替えて検証する場合は、環境IDをメモに残す運用にしておくと取り違えを防げます
• beta headerを手動で付け忘れる: SDKを使わずにcURLで直接叩く場合、anthropic-beta: managed-agents-2026-04-01を毎回のリクエストに含める必要があります。memory storeエンドポイントだけはagent-memory-2026-07-22という別のbetaヘッダーが必要で、この1点だけ例外です
• Console上のテストと本番コードで別の環境IDを渡してしまう: Consoleのインラインテストは、そのとき選んでいる環境IDのサンドボックスで動きます。本番コードに別の環境ID(ネットワーク制限やパッケージ構成が違うもの)を渡すと、Consoleでは通ったツール呼び出しが本番では失敗することがあるため、コードに渡す環境IDがConsoleでテストしたものと同じかを確認してください
• エージェント定義を更新したのにコード側の挙動が変わらない: Consoleでエージェント定義を編集すると、そのエージェントIDを文字列で渡す新規セッションは作成時点の最新バージョンを参照します。一方、開始済みのセッションは作成時に解決されたエージェントのバージョンを参照し続けるため、「Consoleで直したのに古い挙動のままだ」と感じたら、新しいセッションを作り直しているかをまず確認してください
• チーム内でエージェント定義の変更履歴が追えなくなる: Console上での編集はGUI操作なので、誰がいつどの項目を変えたかはコードのコミット履歴のようには残りません。複数人でエージェント定義を触るチームでは、重要な変更のたびにConsole画面右側のAPIリクエストをコピーしてリポジトリにも残しておくと、後から差分を追いやすくなります

まとめ

• Consoleはモデル・システムプロンプト・MCPサーバー・ツール・Skillsの4項目をコードなしで設定でき、画面には常に同等のAPIリクエストが表示されるため、設定の可視化にもそのまま使える
• インラインセッションランナーを使えば、コードを1行も書く前に動作をその場でテストできる
• 動作確認後はエージェントIDと環境IDの2つをコピーし、cURL・Python・TypeScriptのいずれでもセッション作成時にそのまま渡すだけでコードへ持ち帰れる
• environment_idの取り違えとbetaヘッダーの付け忘れ、Console編集後の反映タイミングの誤解が、つまずきやすいポイントとして残る