← claude.dev 日本語訳

· Agents

効果的なエージェント自動化の構築

Building effective agent automations

Lance Martin and CJ Avilla

この記事は 原文 を DeepL で機械翻訳したものである。正確な内容は原文を参照のこと。

AIによって業務が加速するにつれ、そのペースについていくことが難しくなってきています。 Anthropicでは、支援のためにシンプルなエージェントによる自動化が頻繁に活用されています。これらは多くの場合、スケジュールに従って実行され、バックグラウンドでコンテキストを収集し、私たちが知るべき情報を先回りして教えてくれます。しかし、効果的なエージェントによる自動化を構築するのは困難です。誰にも気づかれないうちに情報源へのアクセスを失ったり、私たちの好みに沿わない動作をしたりすることがあるからです。

Claude Managed Agents（ベータ版）を使用して、カスタムソース（SlackやGitHubリポジトリなど）をスケジュールに従って読み込み、前回の実行以降に変更された内容を追跡し、知っておくべき情報（Slackなど）を投稿するリファレンス実装を構築しました。 この記事では、各手順を順を追って解説し、リファレンス実装を公開するとともに、Claude Codeで実行してエージェントの設定を自動で行うコマンドを紹介します。

コードを入手する

リファレンス実装はこちらです。インタラクティブな手順を確認するには、Claude Codeで以下のコマンドを実行してください。 claude-api このスキルは、この記事のガイダンスに従ってエージェントを設定するのに役立ちます：

Text
/claude-api managed-agents-onboard https://claude.dev/blog/building-effective-agent-automations/

このリファレンス実装には、Slackアプリ（マニフェストから作成してください）とGitHubトークンが必要です。以下に示す提供されたファイルは、エージェント、その環境、メモリストア、Vault、デプロイメントなど、Claude APIリソースの設定ファイルです。

Text
daily-brief/
├── agent.md                        model, tools, instructions
├── deployment.md                   schedule, time zone, budget, input message
├── environment.yaml                network allowlist
├── memory_store_preferences.yaml   user preferences
├── memory_store_state.yaml         the agent's bookmarks, ledger, notes, and run records
├── vault.yaml                      the vault that holds the credentials
├── claude-lock.json                resource IDs, written by ant apply
└── slack/manifest.yaml             one bot app

Ant CLI のコマンドである `ant apply` は、これらのファイルを読み込み、Claude API ワークスペース（プラットフォームがリソースを保存・実行する場所）内にリソースを作成し、その ID を claude-lock.json.

以下のセクションでは、このコマンドを使用します。設定が完了すると、自動化処理はAnthropicのインフラ上でスケジュールに従って実行されるため、お使いのマシン上で何かを実行し続ける必要はありません。

概要

これから作成するエージェントは6つのコンポーネントで構成されており、以下の順序で説明します：

  • 出典 - 参考になるサイトの一覧（サイト名付き）
  • 行き先 - エージェントが記入する可能性がある場所の一つ
  • エージェント - agent.md 内のモデル、ツール、および実行手順
  • スケジュール - cronスケジュール
  • 記憶 - ユーザーの設定とエージェント自身の記憶
  • ガードレール - エージェントが読み取りのみを行う場所では読み取り専用アクセスとなり、実行ごとの支出上限が設定されます

出典

このエージェントは、SlackチャンネルとGitHubのプルリクエストという2つのデフォルトの情報源を読み取ります。チャンネルとリポジトリは、 preferences ファイルに一覧表示されています。テンプレートを拡張することで、他のソースを使用することも可能です。

エージェントに、スコープが限定された独自の認証情報を付与する

Managed Agents では、認証情報はボールトに格納されます。エージェントはこれらの認証情報を参照できますが、実際の値は、Claude のコードが実行されるサンドボックスの外にあるボールト内に保持されます（こちらおよびこちらを参照）：

  • MCP サーバー（GitHub）。エージェントは、サンドボックスの外で実行されているプロキシを経由して MCP ツールを呼び出します。プロキシは、サーバーの URL と一致する Vault 認証情報を検索します。
  • シェル（Slack）。エージェントは、サンドボックス内のbashツールを使用してcurlでSlack APIを呼び出します。サンドボックスには不透明なプレースホルダーのみが格納されており、 $SLACK_BOT_TOKEN。リクエストがサンドボックス外へ送信される際、プラットフォームは、ユーザーが許可したホストに対して実際のトークンに置き換えます。

以下の ant CLIとリポジトリ内のテンプレートファイルを使用して、Vaultを作成します：

Shell
ant apply vault.yaml

これにより、Claude APIワークスペース内にボールトが作成され、プラットフォームがそこにボールトを保存するとともに、そのIDを claude-lock.jsonに記録されます。次に、TypeScript SDK を使用して各認証情報をヴォールトに追加します。以下は、Slackの認証情報を追加する例です：

TypeScript
const vaultId = process.env.VAULT_ID!; // the vault's ID, from claude-lock.json

await client.beta.vaults.credentials.create(vaultId, {
  display_name: "SLACK_BOT_TOKEN",
  auth: {
    type: "environment_variable",
    secret_name: "SLACK_BOT_TOKEN",
    secret_value: process.env.SLACK_BOT_TOKEN!,
    networking: { type: "limited", allowed_hosts: ["slack.com"] },
    injection_location: { header: true },
  },
});

ボールトを作成し、各認証情報を追加したら、そのボールトをデプロイメントに関連付けます。ボールトIDを claude-lock.json を vault_ids にコピーし、 deployment.md.

前回読み止めたところから読み進める

よくある間違いとして、エージェントに「過去24時間」といった固定の期間を読み込むよう指示することが挙げられます。実行が遅れるとデータに空白が生じ、早すぎると項目が重複してしまいます。その代わりに、ソースごとにエージェントにブックマークを指定してください。各実行の終了時に、エージェントは各ソースから読み込んだ最新の項目のタイムスタンプを1つのファイルに書き込み、 bookmarks.json、ソースごとに1つのエントリを含めるようにします： "slack": "2026-09-14T13:02:11Z".

次回の実行はそれらのブックマークから始まるため、ウィンドウは前回の実行以降の内容をすべて表示できるよう、拡大または縮小されます。ブックマークは stateと呼ばれるメモリストアに格納されています。これは、プラットフォームが各実行のサンドボックス内に /mnt/memory/ にマウントし、実行間でも保持されるテキストファイルのフォルダです。エージェントは通常のファイルツールを使ってこれを読み書きし、 agent.md に記述された指示に従って処理を行います。

読み取りに失敗したからといって、その日が何事もない日だと思い込まないでください

MCPサーバーがダウンしている場合や、そのトークンの有効期限が切れている場合でも、実行は開始されますが、そのサーバーのツールは使用されません。セッションにはエラーが記録されますが、エージェントはそのソースからの情報を一切受信しないため、「新しい情報なし」と報告します。

この問題を解決するための agent.md この問題を解決するのに役立ちます。ソースに不具合が生じた場合、エージェントは次の処理を行います：そのソースのブックマークをそのまま保持し、他のソースから要約を作成し、読み取れなかった内容（「今回の実行ではプルリクエストが利用できませんでした」）を1行で明記して要約を締めくくることで、読者にその旨を伝えます。

目的地

このテンプレートは、Slackの1つのチャンネルに投稿を行い、実行されるたびに日付付きの投稿を作成します。

エージェントは、サンドボックス内のbashツールを使用して、読み取りに使用したのと同じボットトークンを用いてSlackに投稿します。

この投稿を承認する必要はありません。エージェントがbashコマンドで送信すると、組み込みのbashツールはデフォルトで承認を求めずに実行されます。 slack.com また、エージェントの環境（エージェントが実行されるサンドボックス）の許可リストにも含まれています。この投稿は1つのリクエストです：

Shell
curl -s https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"channel": "C0123456789", "text": "Daily brief, Tue Sep 15 ..."}'

投稿が正常に送信されたことを確認してから、記録してください

投稿が確認されると、エージェントは報告済み項目の台帳とブックマークを更新します。これらの記録が実際に投稿された内容と一致しない場合、2つの問題が発生する可能性があります。 エージェントが配信されなかった投稿を記録した場合、ブックマークは次の項目に進み、それらのアイテムは報告されません。最初の投稿が配信されたかどうかわからないため、再度投稿すると、読者は同じ要約を2回受け取ることになります。

これを防ぐための agent.md これを防ぐためのルールが3つあります。第一に、エージェントはチャンネルの最近のメッセージの中からその日のタイトルを探し、その記事がすでに存在している場合は投稿しません。第二に、Slackから "ok": true とメッセージのタイムスタンプ（ts）を返した場合にのみ、投稿としてカウントされます。第三に、エージェントはその確認を受けて初めて、台帳を更新し、ブックマークを更新します。結果が不明確な場合は、その実行を「投稿された可能性あり」とマークし、それ以外の変更は行わないため、データが失われることはありません。

エージェントは、メモリストアに実行記録を保持しています（runs/<date>.md）。エージェントは、投稿の前にその実行を「投稿予定」とマークし、その後、メッセージIDを付けて「投稿済み」または「投稿済みかもしれない」とマークします。

エージェント

「Claude Managed Agents」において、エージェントとは、バージョン管理された構成（モデル、システムプロンプト、およびツール）のことです。各実行は、その実行手順に従って進行し、完了すると停止します。

当社のリファレンス実装では、エージェントの設定は以下の通りです。 agent.md:

Markdown
---
name: Daily brief
model: claude-sonnet-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_search
        enabled: false
      - name: web_fetch
        enabled: false
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: always_allow
---

[Eight numbered run steps; the full text is in agent.md in the repo.]

フロントマターには、エージェント名、モデル、ツール、およびMCPサーバーが指定されます。本文には、エージェントへの指示が記載されています。MCPツールはデフォルトで承認を求めますが、承認を行う担当者がいないため、GitHubツールセットは always_allow に設定され、GitHubトークンは read-only.

概要は簡潔にまとめる

agent.md Claudeに簡潔さを促す：

Text
4. Decide. An item earns a line when the reader would act on it today, or it changes a decision they are about to make. When unsure, leave it out. Most days that is a few items, sometimes none. A count ("12 open reviews") is not an item; link the ones that are blocked. An item already in the ledger and still open is carried as one marked line ("still waiting, day 3"), not re-reported; a closed item is dropped without comment. Do not bring back a topic the preferences file has retired.

投稿する直前に、まだ未解決の項目がないか再確認してください

エージェントがソースを読み込んだ時点と投稿する時点の間で、アイテムの内容が変更される場合があります。投稿の直前に、 agent.md エージェントに対し、各アイテムのライブステータスを再確認するよう指示します：

Text
5. Verify. The world moved while you read. For every item you will report, re-check its live source just before posting: resolved since you read it, drop it; still open but changed, fix the line; cannot confirm, drop it and list it in the run record's cuts. One stale "still waiting on you" costs more trust than ten missing items, so never hedge an item's status: assert it or drop it. Every link is copied from the source's own link field (a pull request's html_url, a Slack permalink), never assembled by hand.

スケジュール

「Claude Managed Agents」では、エージェントは単なる設定ファイルに過ぎず、デプロイメントによって実行されます。デプロイメントには、エージェント名、環境名、および各実行時の最初のメッセージが指定されます。また、スケジュール、Vault、メモリストア、予算もデプロイメントに含まれます。スケジュールがトリガーされるたびに、プラットフォームは新しいエージェントセッションを開始します。

このテンプレートでは、デプロイの内容は deployment.mdに記録され、最初のメッセージがその本文となります：

Markdown
---
name: Daily brief
agent: ./agent.md
environment_id: ./environment.yaml
schedule:
  type: cron
  expression: "32 7 * * 1-5"
  timezone: America/New_York
vault_ids: [vlt_...]   # the vault you create under Sources
resources:
  - path: ./memory_store_preferences.yaml
    access: read_only
    instructions: The reader's preferences. Re-read them every run. Never write here.
  - path: ./memory_store_state.yaml
    access: read_write
    instructions: Your state. Bookmarks, ledger, notes, proposals, and run records.

---

Write today's brief.
The reader's time zone is America/New_York. Work out every date in that zone.

Follow your run steps in order. Today's edition is titled "Daily brief, <weekday> <month> <day>".

これにより、指定されたパスでエージェント、環境、およびメモリストを指定してデプロイメントが作成されます。

Shell
ant apply deployment.md

スケジュールを待たずにテストを行うには、 ant beta:deployments run --deployment-id <id>、[ここに](https://example.com)のIDを使用して、手動で実行を開始してください。 claude-lock.json.

自分のタイムゾーンで日付を計算する

よくある不具合として、エージェントが日付をサーバーのタイムゾーンに基づいて計算するため、今朝を「昨日」と表示してしまうことがあります。 deployment.md、 timezone フィールドで実行のトリガー時刻を設定し、本文の2行目でエージェントに日付の計算に使用するタイムゾーンを指定します。

MEMORY

各実行は、前回の実行の記憶が一切ない、新しいサンドボックスから開始されます。記憶がないため、フィードバックは定着しません。しかし、古い記憶があるとエージェントが混乱する可能性があります。たとえば、解決済みの項目をまだ待機中であると報告したり、「すでに報告済み」という理由で、まだ未解決の項目を無視したりすることがあります。

このテンプレートでは、2つのメモリストレージを保持しており、これらは /mnt/memory/ の下にマウントされたフォルダです（「ソース」を参照）：

  • 設定（ユーザー側、エージェントからは読み取り専用）：読み込むチャネルとリポジトリ、除外する項目、長さの上限、送信先、および停止するタイミング。
  • 状態（エージェントの、読み書き可能）：ブックマーク、報告内容の記録（実行ごとに1件）、設定への変更提案、および各ソースの動作に関するメモ（「最新の50件のみを返す」など）。

ant apply deployment.md 設定ストアは作成されますが、その中のファイルは作成されません。初回実行の前に、リポジトリの scripts/seed-preferences.sh.

実行のたびに、最初に設定情報を再読み込みする

よく起こる問題として、設定のコピーがプロンプトに組み込まれてしまい、すでに変更したルールが引き続き適用されてしまうことがあります。エージェントには、実行のたびにファイルを新たに読み込ませるようにしてください。ファイルを読み込めない場合は、デフォルト設定で実行するのではなく、処理を中止してその旨を伝えるようにすべきです。

すでに報告した内容について台帳をつけておき、変更点を報告してください

エージェントは、 ledger.md、報告済みのすべての項目について台帳を管理しているため、ブリーフに重複した内容が記載されることはありません。各行には、その項目が報告された日時、情報源、変更されないID（Slackメッセージのタイムスタンプまたはプルリクエスト番号）、および最後に確認されたステータスが記録されます：

Text
2026-09-09 slack:C0123456789 1788963600.000100 refund thread: customer waiting on a decision
2026-09-11 github 481 review blocked, day 2 (still waiting)
2026-09-11 slack:C0234567891 1789117333.000300 enterprise escalation: owner named, in progress

ガードレール

当社の自動化システムはスケジュールに従って「バックグラウンド」で動作するため、エージェントが実行できる操作や支出できる金額に制限を設けています。

その機能の限界

エージェントは、他の人が書いたメッセージや課題を読み取り、そのテキストを指示として解釈することがあります。エージェントがそれらに従った場合に実行できる動作を制限してください。この例では、GitHubトークンと preferences ストアは読み取り専用であり、環境は許可リストに登録されたホストにしかアクセスできません。仕込まれた指示は、エージェントが実行の合間に記録するメモを通じて含め、ブリーフの内容を変更することは依然として可能です。ただし、GitHubへの書き込みやルールの編集はできません。

Slackは例外です。同じトークンで投稿が行われるため、ボットが読み取りや投稿を行う必要がある場合のみ、そのボットを招待してください。

実際の走行データに基づいて支出上限を設定する

支出上限を設定することで、コストの暴走を防ぐことができます。まずは通常のランのコストの3～5倍から始め、実際の数値を確認しながら徐々に引き締めていきましょう。上限に達したランは失敗するのではなく一時停止するため、上限を低く設定しすぎると、そのランが途絶えたように見えてしまいます。この上限こそが、budgetの deployment.md。すべての実行には全額が割り当てられ、上限に達した実行は一時停止し、 budget_reached 停止理由：

YAML
budget:
  type: limit
  max_list_cost:
    amount: "500" # a string, in cents: "500" is $5.00
    currency: USD

はじめに

当社のリファレンス実装は、以下の6つのルールに集約されます：

  • 各情報源は、決まった時間枠ではなく、ブックマークから順に読んでください。
  • 読み取りに失敗した場合は「読み取り不可」として報告し、「静かな日」として報告してはならない。
  • 投稿する直前に、すべての項目をもう一度確認してください。
  • Slackが投稿の送信を確認した時点で初めてその投稿を送信済みとしてカウントし、その後、ブックマークと台帳を更新する。
  • 実行のたびに、エージェントが編集できないストアから設定を再読み込みします。
  • エージェントが読み取りのみを行う箇所では、読み取り専用アクセス権を付与し、各実行で消費できるリソースに上限を設ける。

Claude Code を使えば、この記事で紹介されている手順を順を追って実行できます。まず、更新を行ってください：

Shell
claude update

次に、claude-api スキルを使用します：

Text
/claude-api managed-agents-onboard https://claude.dev/blog/building-effective-agent-automations/

claude-api スキルはこの投稿を読み取り、設定案を提案し、プロジェクト内の agents/ フォルダにファイルを書き出し、ant apply コマンドでリソースを作成します。これを起点として、ソース、宛先、またはメモリ設定に合わせてエージェントをカスタマイズしてください。