エージェントを作る — 土台の選択から運用まで
SUMMARY が「AI をどう使うか」を1枚にまとめているのに対して、こちらはエージェントを作る側の判断を作業の流れ順に置く。設計パターンそのものは agent-design、日々の運用は claude-code-workflow にある。
0. まず「エージェントにしない」を検討する
最初の分岐はここで、土台の話はそのあと。
When building applications with LLMs, we recommend finding the simplest solution possible, and only increasing complexity when needed.
LLM でアプリケーションを作るときは、可能な限り単純な解を見つけ、必要になったときにだけ複雑さを増やすことを勧める。 — building-effective-agents
タスクが現在のモデルの単独実行で確実に解ける範囲内なら、harness を置かない。harness-design-long-running-apps の実測では、同じ課題が harness なしで 20分 / $9、3エージェントの harness で 6時間 / $200 だった。構造を足すと桁で高くなる。
Keep in mind, best practices are still developing: dynamic workflows often use more tokens and are best suited for complex, high value tasks.
念頭に置いてほしいが、ベストプラクティスはまだ発展途上である。dynamic workflow はしばしばトークンを多く使い、複雑で価値の高いタスクに最も向いている。 — a-harness-for-every-task
1. 土台を選ぶ — API / Agent SDK / Managed Agents
何を自分で持つかの選択であり、機能の優劣ではない。
| 自分で持つもの | 向くとき | |
|---|---|---|
| API 直 | ループ・ツール実行・インフラの全部（“tokens in, tokens out”） | 全面的なカスタマイズが要るとき（原典が明示） |
| Agent SDK | Claude Code と同じ harness 機構を借りる。ファイルシステム・セッション永続・OpenTelemetry の可観測性が付く | 手元や CI で動かす。claude -p はこの CLI 版 |
| Managed Agents | harness とインフラを Anthropic が運用。タスク・ツール・ガードレールだけ定義する | 予測可能で複雑度の低いエージェント的ワークロード |
判断の材料になるのは「prototype と production を分けるもの」の正体である。
infrastructure is what separates a prototype from a production agent. All too often, teams burn development cycles on security, state management, permissioning, and harness tuning.
prototype と production のエージェントを分けるのはインフラである。往々にして、チームはセキュリティ・状態管理・権限付与・harness チューニングに開発工数を燃やす。 — building-with-claude-managed-agents
原典が production で詰まる箇所として挙げるのは6つ。ホスティングとスケール / セッション管理 / ファイルシステム / 実行の隔離 / 認証情報 / 可観測性。この6つを自分で解く気があるかどうかが、そのまま土台の選択になる。
CI やスクリプトで Agent SDK を使うなら、再現性のために --bare を付ける（hook / skill / カスタムコマンド / subagent / plugin / MCP / auto memory / CLAUDE.md の自動発見をすべて飛ばす）。詳細は headless。
2. 中心にある設計判断 — 脳と手を分ける
土台を選んだあと、アーキテクチャで効くのはこの1点。
Several of these hurdles stem from a common architectural choice: agent harnesses often run inside the same container as the filesystem it works on. A container has to spin up (paying a startup cost) before Claude can think, the agent along with code execution lives right next to your credentials, and when the container dies, the run dies with it.
これらの障害のいくつかは共通のアーキテクチャ選択に由来する。agent harness は、それが作業するファイルシステムと同じコンテナの中で動くことが多い。Claude が考え始める前にコンテナが起動しなければならず（起動コストを払う）、エージェントとコード実行はあなたの認証情報のすぐ隣に置かれ、コンテナが死ねば実行も一緒に死ぬ。 — building-with-claude-managed-agents
Managed Agents solves these problems by decoupling the brain from the hands. The harness that calls Claude runs separately from the sandbox where code executes, and the session–an append-only log of every model call, tool call, and result–connects the two.
Managed Agents は脳と手を分離することでこれらを解く。Claude を呼ぶ harness は、コードが実行されるサンドボックスとは別に動き、セッション —— すべてのモデル呼び出し・ツール呼び出し・結果の追記専用ログ —— が両者を繋ぐ。 — building-with-claude-managed-agents
1つの分離から3つ出る。 コンテナが存在する前に推論を始められる／サンドボックスが認証情報から遠い／実行全体をセッションから再構成できる。
遅延の実測:
In our testing, that cut the time-to-first-token by roughly 60% in the median case (p50) and by over 90% in the slowest cases (p95).
我々のテストでは、それが time-to-first-token を中央値（p50）で約 60%、最も遅い場合（p95）で 90% 超削減した。 — building-with-claude-managed-agents
安全側の理由はより重い。
When everything runs in one container, the code Claude generates sits right next to your credentials, so prompt injections could lead the model to leak a token by convincing the model to read its own environment.
すべてが1つのコンテナで動くと、Claude が生成したコードはあなたの認証情報のすぐ隣に置かれる。だから prompt injection は、自分の環境を読むようモデルを説得することでトークンを漏らさせうる。 — building-with-claude-managed-agents
自前で組む場合でもこの分離は真似できる。managed-agents は同じ構造を brain（Claude と harness）/ hands（サンドボックスとツール）/ session（イベントログ）として述べ、それぞれが独立に落ちたり差し替えられたりできることを設計目標に置いている。
3. harness を自前で持つか
持たない理由は「面倒だから」ではなく「モデルより先に古くなるから」。
When the harness doesn’t evolve alongside model intelligence, the agent breaks down. On Claude Sonnet 4.5, an agent would rush to finish as it neared the end of its context, cutting work short rather than using the room it had left—a pattern called “context anxiety.” Our fix was to add context resets to the harness, baking in an assumption that Claude needed help staying coherent near the limit. That assumption didn’t survive the next model. On Claude Opus 4.5, the behavior was gone, and the resets we’d added were just overhead.
harness がモデルの知能と並んで進化しないと、エージェントは壊れる。 Claude Sonnet 4.5 では、エージェントは context の終わりが近づくと残った余地を使わずに切り上げようと急いだ ——「context 不安」と呼ばれるパターンだ。我々の対処は harness に context リセットを足すことで、上限付近で Claude が一貫性を保つのに助けが要るという前提を焼き込んだ。その前提は次のモデルを生き延びなかった。 Claude Opus 4.5 ではその挙動は消えており、足したリセットは単なるオーバーヘッドだった。 — building-with-claude-managed-agents
For most organizations, maintaining a harness is overhead that doesn’t differentiate their product.
ほとんどの組織にとって、harness の保守は製品を差別化しないオーバーヘッドである。 — building-with-claude-managed-agents
差別化すべき場所は原典が名指ししている —— context 管理とドメインの専門性。
harness を持つと決めたなら、harnessing-claudes-intelligence の3パターンと、「何をやめられるか」を定期的に問う周期が要る。モデルが上がるたびに、足した補助が負債に変わる。
4. 委譲の形を決める
土台の中でどう分けるかは別の軸。詳細は agent-design にあるが、判断の基準は2つだけ。「ワーカー同士が通信する必要があるか」と「計画を誰が持つか」。
- 結果だけが要る → subagent
- 互いの発見を反証し合う必要がある → agent team
- 同じ手順を多数に適用する / 再利用したい → workflow
- 現在のモデルが単独で確実にこなせる → 委譲しない
multi-agent が効く理由は速さではない。
Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause.
逐次的な調査は anchoring（最初の仮説への固着）に陥る。ひとつの仮説を掘ると、以降の調査がそれに引きずられる。独立した複数の調査者が互いを積極的に反証しようとするなら、生き残った仮説が真の根本原因である見込みははるかに高い。 — agent-teams
5. ツールを設計する
エージェントの品質はツールの品質で頭打ちになる。 詳細は tool-design。
- 最小の集合から始める。 ツールが増えるほど選択を誤る
- 新入社員に渡す説明のつもりで書く。 曖昧な名前と説明がそのまま誤用になる
- 返す情報を絞る。 中間結果が context を埋める。大きい出力はファイルへ逃がす
6. 評価を先に作る
エージェントは「動いた」の判定が難しい。 出力が毎回違い、途中の手順も違う。demystifying-evals-for-ai-agents が扱うのは、その状態でどう測るか。
- 少数から始めてよい。完璧な eval セットを待つと何も測れない
- rubric による model-based grading が、自由記述の採点では現実的
- 別 context の採点役を置くと効く（new-in-claude-managed-agents の outcomes）
7. 封じ込めを先に決める
権限は後から絞れない。security に詳細があるが、順序として設計時に決める。
- 封じ込めが先、検出は後（how-we-contain-claude）
- ツールが許されていれば、そこから外へ出る経路が開く。WebFetch のドメイン制限だけではネットワークを塞げない（Bash があれば curl が届く）
- 生成コードと認証情報を同じ場所に置かない（§2 の分離がそのまま安全策になる）
8. 長く走らせる
effective-harnesses-for-long-running-agents と harness-design-long-running-apps の主題。単一 context で長く走らせると必ず出る失敗が3つある（a-harness-for-every-task）。
| 失敗モード | 中身 |
|---|---|
| agentic laziness | 部分的な進捗で「終わった」と宣言して止まる |
| self-preferential bias | 検証を求められたとき、自分の結果を好む |
| goal drift | ターンを跨ぐうちに目的への忠実さが薄れる。特に compaction の後 |
いずれも別 context の検証者を置く構造で緩和できる。セッションを追記専用のイベントログとして持てば、再開・可観測性・メモリはその副産物として付いてくる（§2）。
参照
| agent-design | 設計パターンと委譲の判断 |
| tool-design | ツール設計 |
| evals | 評価 |
| security | 権限と封じ込め |
| SUMMARY | 使う側の1枚まとめ |
| SOURCES | 原典の台帳 |