Claude Managed Agents(beta)— サーバー管理型エージェントの実践入門

{
  "envId": "env_abc123example",
  "agentId": "agent_abc123example",
  "agentVersion": 1
}

# .env にコピーして値を入れる (.env は gitignore 対象)

# https://console.anthropic.com/settings/keys
ANTHROPIC_API_KEY=

# setup 後に src/setup.ts が .agent-ids.json を生成する。
# 別の方法で保存したいならここに入れても良い。
# AGENT_ID=
# ENV_ID=

# managed-agents-starter

Claude **Managed Agents**(beta `managed-agents-2026-04-01`)の最小スターター。
[記事本文](https://r43lab.com/blog/claude-managed-agents-intro) と対になる実動コードです。

## Quick start

```bash
bun install
cp .env.example .env    # ANTHROPIC_API_KEY を入れる

# 1) Setup を 1 度だけ走らせて Agent / Environment を作る
bun run src/setup.ts    # → .agent-ids.json に ID が書き出される

# 2) Runtime — user message を投げて stream を読む
bun run src/run.ts "Claude Code の最小構成を 300 字で教えて"

# 3) tool 確認ゲートつきのパターン
bun run src/tool-confirmation.ts "cat ./README.md"
```

## ファイル構成

- `src/setup.ts` — **1 度だけ** 実行。`environments.create` + `agents.create` を行い、返ってきた ID を `.agent-ids.json` に保存する
- `src/run.ts` — **毎回** 実行。保存された ID を読んで session を起動、イベントストリームを読み終える
- `src/tool-confirmation.ts` — `permission_policy: "always_ask"` を bash だけ効かせる例。`user.tool_confirmation` で承認する
- `.env.example` — ANTHROPIC_API_KEY のテンプレ
- `.agent-ids.example.json` — setup 後に作られる `.agent-ids.json` の形

## 守るべきパターン

- **Agent は 1 度作って ID を保存**。runtime で `agents.create()` を呼ばない
- `sessions.create({ agent: AGENT_ID, environment_id: ENV_ID })` だけで毎回のセッションが起動
- `session.status_idle` は一時停止でも発火。**終了判定は `session.status_terminated` または `idle && stop_reason.type !== "requires_action"`**
- **stream 先 → send 後**(逆にすると最初のイベントを取りこぼす)

## 依存バージョン

`package.json` は **2026-04 時点のスナップショット** です。clone 後は最新化を推奨。

```bash
bun outdated
bun update
```

## Stack

`@anthropic-ai/sdk` v0.90 · Managed Agents beta `managed-agents-2026-04-01`

{
  "name": "managed-agents-starter",
  "private": true,
  "type": "module",
  "scripts": {
    "setup": "bun src/setup.ts",
    "run": "bun src/run.ts",
    "tool": "bun src/tool-confirmation.ts"
  },
  "dependencies": {
    "@anthropic-ai/sdk": "^0.90.0"
  },
  "devDependencies": {
    "@types/bun": "^1.3.0",
    "typescript": "^6.0.3"
  }
}

/**
 * run.ts — 保存済みの AGENT_ID / ENV_ID で Session を 1 つ起動する例
 *
 * CLI: bun run src/run.ts "質問文"
 *
 * 守るべきポイント:
 *   - stream 先, send 後
 *   - status_idle 単独で break しない(stop_reason を見る)
 */
import Anthropic from "@anthropic-ai/sdk";
import { readFileSync } from "node:fs";

const client = new Anthropic();

function loadIds() {
  const raw = readFileSync(".agent-ids.json", "utf8");
  const { agentId, envId } = JSON.parse(raw) as {
    agentId: string;
    envId: string;
  };
  return { agentId, envId };
}

async function main() {
  const userText = process.argv.slice(2).join(" ") || "Hello, who are you?";
  const { agentId, envId } = loadIds();

  // 1) Session を起動
  const session = await client.beta.sessions.create({
    agent: agentId, // 文字列で渡すと常に latest version
    environment_id: envId,
    title: `run ${new Date().toISOString()}`,
  });
  console.log(`[session] ${session.id} (status=${session.status})`);

  // 2) stream を **先に** 開いてから send する
  const stream = await client.beta.sessions.events.stream(session.id);
  await client.beta.sessions.events.send(session.id, {
    events: [
      { type: "user.message", content: [{ type: "text", text: userText }] },
    ],
  });

  // 3) イベントを読み進める
  for await (const event of stream) {
    if (event.type === "agent.message") {
      for (const b of event.content) {
        if (b.type === "text") process.stdout.write(b.text);
      }
    }

    if (event.type === "session.status_terminated") {
      console.log("\n[terminated]");
      break;
    }

    if (event.type === "session.status_idle") {
      // requires_action → tool 確認や custom_tool_result を待っている
      // end_turn / retries_exhausted → 終了と見做す
      if (event.stop_reason.type === "requires_action") continue;
      console.log(`\n[idle: ${event.stop_reason.type}]`);
      break;
    }
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * setup.ts — Managed Agents の 1 回だけの初期化
 *
 * 実行後、.agent-ids.json に ID が書き出される。
 * 以降の run.ts / tool-confirmation.ts はこのファイルを読む。
 *
 * **毎回 setup を走らせると孤児 Agent が累積する**ので、リクエスト経路には
 * 絶対入れないこと。CI / 初回デプロイ時のみ走る運用が正解。
 */
import Anthropic from "@anthropic-ai/sdk";
import { writeFileSync } from "node:fs";

const client = new Anthropic();

async function main() {
  // 1) Environment
  const env = await client.beta.environments.create({
    name: `r43lab-starter-${Date.now().toString(36)}`,
    config: { type: "cloud", networking: { type: "unrestricted" } },
  });

  // 2) Agent: model / system / tools はここに乗せる(session に書かないこと)
  const agent = await client.beta.agents.create({
    name: "r43lab-starter-agent",
    model: "claude-opus-4-7",
    system: [
      "You are a concise assistant. Keep answers short (<=300 chars) unless asked otherwise.",
      "When using tools, prefer `read` over `bash` for file contents.",
    ].join("\n"),
    tools: [
      {
        type: "agent_toolset_20260401",
        default_config: { enabled: true },
      },
    ],
  });

  const out = {
    envId: env.id,
    agentId: agent.id,
    agentVersion: agent.version,
  };
  writeFileSync(".agent-ids.json", JSON.stringify(out, null, 2));
  console.log("wrote .agent-ids.json\n", out);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * tool-confirmation.ts — permission_policy: "always_ask" を bash だけに効かせる例
 *
 * この構成を使うには setup 側で tools 設定を以下のように変える必要がある:
 *
 *   tools: [
 *     {
 *       type: "agent_toolset_20260401",
 *       default_config: {
 *         enabled: true,
 *         permission_policy: { type: "always_allow" },
 *       },
 *       configs: [
 *         { name: "bash", permission_policy: { type: "always_ask" } },
 *       ],
 *     },
 *   ],
 *
 * 本ファイルは「その Agent を使って bash 呼び出しに承認を差し挟む」側の実装。
 */
import Anthropic from "@anthropic-ai/sdk";
import { readFileSync } from "node:fs";
import { createInterface } from "node:readline/promises";

const client = new Anthropic();

function loadIds() {
  const raw = readFileSync(".agent-ids.json", "utf8");
  const { agentId, envId } = JSON.parse(raw) as {
    agentId: string;
    envId: string;
  };
  return { agentId, envId };
}

async function confirm(cmd: string): Promise<boolean> {
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  const ans = (await rl.question(`\n> allow bash \`${cmd}\`? [y/N] `)).trim().toLowerCase();
  rl.close();
  return ans === "y" || ans === "yes";
}

async function main() {
  const userText = process.argv.slice(2).join(" ") || "List files in the working directory.";
  const { agentId, envId } = loadIds();

  const session = await client.beta.sessions.create({
    agent: agentId,
    environment_id: envId,
    title: `gated ${new Date().toISOString()}`,
  });
  console.log(`[session] ${session.id}`);

  const stream = await client.beta.sessions.events.stream(session.id);
  await client.beta.sessions.events.send(session.id, {
    events: [{ type: "user.message", content: [{ type: "text", text: userText }] }],
  });

  for await (const event of stream) {
    if (event.type === "agent.message") {
      for (const b of event.content) if (b.type === "text") process.stdout.write(b.text);
    }

    // tool gate
    if (event.type === "agent.tool_use" && event.evaluated_permission === "ask") {
      const input = JSON.stringify(event.input).slice(0, 200);
      console.log(`\n[ask] ${event.tool_name} ${input}`);

      const ok = await confirm(event.tool_name);

      await client.beta.sessions.events.send(session.id, {
        events: [{
          type: "user.tool_confirmation",
          tool_use_id: event.id,                  // ← event.id を渡す (toolu_ ではない)
          result: ok ? "allow" : "deny",
          ...(ok ? {} : { deny_message: "User denied this call. Try a safer approach." }),
        }],
      });
    }

    if (event.type === "session.status_terminated") break;
    if (event.type === "session.status_idle") {
      if (event.stop_reason.type === "requires_action") continue;
      break;
    }
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022"],
    "types": ["bun"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src/**/*"]
}