プロンプトをやめ、エンジニアリングを開始:あなたのAIエージェントを生産に届けるための15の原則

Introduction

最初は、あなたはただAPIを介してChatGPTとコミュニケーションを試み、文脈のいくつかの行を投げ込んで、それがまったく反応していることに驚きを感じます。

だからこそ、エージェントが生まれる。

もしあなたが過去1年間もスクリプトや包装からエージェントを集め、実験し、トンキングし、それらを構築するよりクリーンで持続可能な方法を探しているとしたら、この記事はあなたのためにあります。

これはマニフェストではありません。それを実用的な詐欺シートとして考える - エージェントをサンドボックスから生産に導くのに役立つエンジニアリング原則のコレクション:シンプルなAPIワラッパーから安定した、制御可能でスケーラブルなシステムへ。

Disclaimer

インこの記事(効果的なエージェントを構築する) Anthropic は、エージェントを、LLM が独自のプロセスとツールの使用をダイナミックに指向し、タスクを達成する方法の制御を維持するシステムとして定義します。

このテキストでは、エージェント=エージェントシステムは、安定性とコントロールのために私はより頻繁にワークフローに向かって傾斜します。私は近い将来、進化の1〜2回が起こり、真のエージェントは普遍的になりますが、今のところこれはそうではありません。

1. Design the Foundation

エージェントの初期バージョンは、通常、いくつかの機能、いくつかのプロンプト - そしてヘイ、それは機能します。

エージェントの初期バージョンは、通常、いくつかの機能、いくつかのプロンプト - そしてヘイ、それは機能します。

“If it works, why make it complicated?”

最初は、すべて見た目エージェントは反応し、コードを実行し、合理的に行動しますが、モデルを切り替え、システムを再起動したり、新しいインターフェイスを接続したりすると、突然不安定になり、予測不可能になり、デバッグが困難になります。

そして、しばしば、根幹の原因は論理やヒントではなく、より以前のもの:メモリ管理の破損、ハードコードのスタッフ、セッションを再開する方法がない、または単一の固い入力ポイントです。

このセクションでは、あなたが堅固な基盤を構築するのに役立つ4つの主要な原則を学びます - 他のすべてが安全に上に成長することができます。

1. Keep State Outside

Problem:

1. エージェントが中断される場合(事故、タイムアウト、何であれ)は、それが停止した場所を正確に拾うことができるはずです。
2. 再生可能性は限られています. You need a way to accurately reproduce what happened - for testing, debugging and other such pleasures. あなたは起こったことを正確に再現する方法が必要です。

これは厳密に問題ではありませんが、それでも:

3. 遅かれ早かれ、あなたはエージェントの論理を並列化したいでしょう もしかしたら、それは対話の真ん中に複数のオプションを比較する必要があります(「これらのどちらがより良いですか?」)。

(メモリは完全に別々の問題です - 私たちはすぐにそれに到達します)

Solution:移動国outsideエージェント - データベース、キャッシュ、ストレージ レイヤーに - たとえ JSON ファイルでも。

Checklist:

• エージェントは任意のステップから起動することができ、session_id(セッション識別子)と外部状態(たとえば、データベースやJSONファイルに保存されたステップ)のみで、いかなるステップでもエージェントの作業を中断し、再起動することができます(キャップの下で何かを変更した後でも)。
• テストケース:中断されたエージェントは文脈を失わない、再起動後、結果は同じです。
• State is serializable at any time without loss of functionality. 状態は、機能を失うことなく随時連続化できます。
• 会話の真ん中に並行して複数のインスタンスに状態を送信できます。

2. Make Knowledge External

Problem: LLMsは覚えていません。たとえ1つのセッションでさえ、モデルはあなたがすでに説明したことを忘れ、段階を混ぜ、会話のトレードを失ったり、そこになかった詳細を「記入」し始めることができます。そして時間が経つように見えます、コンテキストウィンドウはますます大きくなり、新しい可能性で私たちを喜ばせます。LinkedInは、人々がどの本やYouTubeのビデオの何時間が新しいモデルのバージョンに合うかを比較する投稿でいっぱいです。

特に、もし:

• 対話は長い
• 文書は広い
• 指示は複雑
• トークンはまだ無限ではない

コンテキストウィンドウ(8k、16k、128k)の増加にもかかわらず、問題は依然として残っている。

• "Lost in the middle" - モデルは、開始と終了により注意を払う(そして中間から詳細を解き放つことができます)
• コスト - もっとトークン = もっとお金
• つまり、損失、歪み、あるいは幻覚が起こるのである。トランスフォーマーが四角形の複雑さ(O(n2))で自己注意に取り組む限り、この制限は私たちと共にあります。

Solution:従来のコンピューティングシステムと同様に、「ワークメモリ」と「ストレージ」を分離して、エージェントは外部メモリと作業することができるはずです: モデル外の知識をストレージ、リクエスト、概要し、更新する。

Approaches

Memory Buffer

ショッピング The Lastk早速、プロトタイプを作成します。

+シンプル、迅速、短いタスクに十分

-重要な情報を失い、「昨日」を覚えていない

Summarization Memory

ストーリーを圧縮してより適合します。

+トークン節約、メモリ拡張

-distortions, loss of nuances, errors in multi-step compression

RAG (Retrieval-Augmented Generation)

外部データベースから知識を引き出します. ほとんどの時間はここにあります。

+スケーラブル、新鮮、検証可能

-複雑な設定、検出品質に敏感、遅延

Knowledge Graphs

常にエレガントでセクシーでハードで、あなたはとにかくRAGをするようになります。

+論理、説明性、安定性

-入学のための高い障壁、LLM統合の複雑さ

Checklist:

• すべての会話履歴は1つの場所でアクセスできます(プロンプトの外)
• 情報源は記録され、再利用することができる。
• コンテキストウィンドウを超えるリスクのない歴史スケール

3. Model as a Config

Problem:LLMsは急速に進化しています; Google、Anthropic、OpenAIなどは絶えず更新をリリースし、異なるベンチマークで互いに競い合っています。これはエンジニアとしての私たちにとってのパーティーであり、私たちはそれを最大限に活用したいです。

Solution:

1. model_id 構成を実装する: 構成ファイルまたは環境変数に model_id パラメータを使用して、使用されるモデルを指定します。
2. 抽象的なインターフェイスを使用する:統一されたAPIを通じてモデルと相互作用するインターフェイスやクラスを作成します。
3. ミドルウェアソリューションを適用する(慎重に - 後でフレームワークについて話します)

Checklist:

• モデル交換は、コードの残りの部分に影響を与えず、エージェントの機能、オーケストラ、メモリ、またはツールに影響を与えません。
• 新しいモデルを追加するには、構成のみと、オプションとして、アダプター(新しいモデルを必要なインターフェイスに持ち込むシンプルな層)が必要です。
• 簡単かつ迅速にモデルを切り替えることができます. Ideally — any models, at least — switching within a model family

4. One Agent, Many Interfaces: Be Where the Users Are

Problem:最初にエージェントが1つのコミュニケーションインターフェイス(たとえばUI)のみを有することを意図しているとしても、Slack、WhatsApp、またはSMSを介してインタラクションを追加することによってユーザーにより多くの柔軟性と便利性を提供したいでしょう。

Solution: Creating a unified input contract: すべてのチャンネルに普遍的なインターフェイスとして機能するAPIまたはその他のメカニズムを開発します。

Checklist:

• Agent is callable from CLI, API, UI

• All input goes through a single endpoint/parser/schema

• All interfaces use the same input format

• No channel contains business logic

• Adding a new channel = only an adapter, no changes to core

  
  

  

  
  

2.エージェント行動の定義

任務は一つだけですが、すべては単純ですが、AIの福音主義者の投稿のように、ツール、意思決定論理、複数の段階を追加すると、エージェントは混乱に変わります。

任務は一つだけですが、すべては単純ですが、AIの福音主義者の投稿のように、ツール、意思決定論理、複数の段階を追加すると、エージェントは混乱に変わります。

トラックを失い、エラーをどうするか知らない、正しいツールを呼ぶのを忘れてしまい、あなたは再び「うん、すべてがそこに書かれているように見える」ロゴで一人ぼっちに残されています。

これを避けるために、エージェントは明確なbehavioral modelそれは何をしているのか、どのようなツールを持っているのか、誰が意思決定をするのか、人間がどのように介入するのか、そして何かが間違っているときに何をすべきか。

このセクションでは、エージェントに一貫した行動戦略を与えるのに役立つ原則をカバーし、「モデルが何らかの方法でそれを発見する」ことを希望する代わりに。

5. Design for Tool Use

Problem:この点は明らかなように思えるかもしれませんが、あなたはまだ「Plain Prompting + Raw LLM output parsing」に構築されたエージェントに遭遇します。それはランダムシートを引っ張って最善を希望することによって複雑なメカニズムを制御しようとしているのと同じです。

• 脆弱性:LLMの応答文法の最小の変更(単語が追加され、句の順序が変更された)は、パッシング全体を破ることができます。
• 曖昧さ:自然言語は本質的に曖昧である. 人間にとっては明らかに見えるものは、調査者にとってはパズルになるかもしれない. 「ジョン・スミスを呼びなさい」──あなたのデータベースの3人のジョン・スミスはどれですか? 彼の番号は何ですか?
• メンテナンスの複雑さ:パッシングコードは成長し、混乱し、デバッグするのが難しい。
• 限られた機能: モデルが複数のツールを信頼できるように呼び出したり、単純なテキスト出力を通じて複雑なデータ構造を渡したりするのは困難です。

Solution:モデルは JSON (または他の構造化された形式) を返します - システムが実行します。

ここで重要なアイデアは、責任を放棄することである。解釈ユーザーの意図と選択ツールをLLMに割り当てる一方で、処刑この意図から、システム明確に定義されたインターフェイスで

Fortunately, practically all providers (OpenAI, Google, Anthropic, or whoever else you prefer) support so-called "function calling"あるいは、厳密に定義された JSON 形式で出力を生成する能力。

これがどのように機能するかをリフレッシュするために:

1. ツール説明: JSON Schema として機能(ツール)を定義し、名前、説明、パラメータを指定します。
2. LLMへの移行:各呼び出しで、モデルはプロンプトと共にツールスケジュールを受け取ります。
3. Model output: Instead of text, the model returns JSON with:
   • name of the function to call
   • arguments—parameters according to schema
4. 実行:コードはJSONを検証し、パラメータを含む適切な関数を呼び出す。
5. モデル応答(オプション):実行結果は最終応答生成のためにLLMに戻ります。

Important:ツールの記述もお勧めです. Unclear description = wrong function choice.

What to do without function calling?

モデルがツール呼び出しをサポートしていない場合、または何らかの理由でそれらを回避したい場合:

• モデルにJSONを返すように依頼してください. フォーマットを指定するようにしてください. You can add examples.
• 答えを分析し、Pydanticのような何かで検証します。このアプローチの本当のファンがいます。

Checklist:

• 答えは厳格に形式化されている(例えば、JSON)
• スケジュール(JSON Schema or Pydantic)
• 機能呼び出しの前に適用される検証
• 生成エラーは破損を引き起こさない(フォーマットエラー処理が存在する)
• LLM = 機能選択、実行 = コード

6. Own the Control Flow

Problem:通常、エージェントは「対話」として動作します―最初にユーザーが話し、その後エージェントが反応します。

Such an agent cannot:

• 要請なしで自分で何かをする。
• 並行して行う行動
• 事前計画のステップ
• 順番に複数のステップを踏み出す
• 進捗状況をチェックし、失敗したステップに戻る

代わりに、エージェントは独自の「実行フロー」を管理し、次に何をすべきか、どのように行うかを決定する必要があります。

This means the agent:

• いつ自分で何かをするかを決める
• ひとつずつステップを踏み出せる。
• 失敗したステップをリリースできる
• タスクの間を切り替えることができます。
• 直接の要求なしでも働くことができます。

Solution:LLMがすべての論理をコントロールすることを許すのではなく、私たちはその論理を抽出します。control flowモデルはステップ内のみを助けるか、または次のステップを提案する。これは「書き込みプロンプト」から「書き込みプロンプト」への移行です。engineering a systemコントロールされた行動

3つの一般的なアプローチを見てみましょう:

1. FSM (Finite State Machines)

• それは何ですか:タスクは州と明確な移行に分割されています。
• LLM:次のステップを決定するか、州内で行動します。
• 利点:シンプルさ、予測性、線形シナリオに良い。
• Tools: StateFlow, YAML configurations, State Pattern.

2. DAG (Directed Graphs)

• グラフとしての非線形または並列タスク:ノードはアクション、エッジは依存性です。
• LLM:ノードまたは計画構築の助けになることができます。
• 利点:柔軟性、平行性、可視化。
• ツール: LangGraph、Trellis、LLMCompiler、カスタムDAG図

3. Planner + Executor

• それは何ですか:LLMは計画を構築し、コードや他のエージェントがそれを実行します。
• LLM: "Big" one plans, "small" ones execute.
• 利点:懸念の分離、コスト管理、スケーラビリティ。
• ツール: LangChain Plan-and-Execute

Why this matters:

• コントロール性、信頼性、スケーラビリティを向上させる。
• さまざまなモデルを組み合わせ、実行を加速させることができます。
• Task flow becomes visualizable and testable.

Checklist:

• 明示的な移行を含む FSM、DAG、またはシナリオを使用
• Model decides what to do but doesn't control the flow
• 行動は視覚化し、テストすることができる。
• Error handling is built into the flow. エラー処理はフローに組み込まれている。

7. Include the Human in the Loop

Problem:エージェントが構造化されたツールを使用し、明確なコントロールフローを持っているとしても、現実世界におけるLLMエージェントの完全な自主性は、文脈に応じて夢(または悪夢)のほうが多いです。

Main risks of full autonomy:

• 永続的なエラー:エージェントは、深刻な結果をもたらす行動(データを削除し、重要なクライアントに間違ったメッセージを送信し、ロボットの反乱を開始する)を行う可能性があります。
• コンプライアンス違反:エージェントは、内部規制、法的要件を誤って違反したり、ユーザーの感情を傷つけたりする可能性があります(それが計画ではなかった場合は、この点を無視してください)。
• 常識と倫理の欠如:LLMは社会的な色合いを見逃すか、「常識」に反する行動を起こす可能性があります。
• ユーザー信頼の喪失:エージェントが頻繁にミスを犯すと、ユーザーはそれを信頼しなくなります。
• 監査と責任の複雑さ:自律的なエージェントが「スクリューアップする」とき、誰が責任を負うのか?

Solution: Strategic summoning of Carbon-based lifeforms重要な段階で人々を意思決定プロセスに統合する。

HITL Implementation Options

1. Approval Flow

• When: Action is critical, expensive, irreversible. 行動は重要で、高価で、不可逆的である。
• How: agent formulates a proposal and waits for confirmation エージェントが提案を提出し、確認を待つ

2. Confidence-aware Routing

• When: モデルは不確実
• How:
  • self-assessment (logits, LLM-as-a-judge, P(IK))
  • escalation when confidence falls below threshold

3. Human-as-a-Tool

• When: insufficient data or unclear request formulation
• How: Agent asks for clarification (e.g., HumanTool in CrewAI)

4. Fallback Escalation

• When: repeated error or unresolvable situation
• How: task is passed to operator with context. タスクは、コンテキストを持つオペレーターに転送されます。

5. RLHF (Human Feedback)

• いつ:モデル改善のために
• How: human evaluates responses, they go into training. 人間は反応を評価し、訓練に進む。

Checklist:

• 承認を必要とする措置が定められています。
• 信頼評価のためのメカニズム
• エージェントは人間に質問できる
• 批判的行動には確認が必要
• 答えを入力するためのインターフェイスがあります。

8. Compact Errors into Context

Problem:エラーが発生した場合の多くのシステムの標準的な行動は、エラーを「崩壊」するか、または単にエラーを報告して止めることです。

何に直面するか:

• 脆弱性:外部ツールのすべての失敗または予期せぬLLMの反応は、全体のプロセスを停止したり、誤解したりすることができます。
• 非効率性:継続的な再起動と手動介入は時間と資源を消費します。
• 学習能力(広い意味で):エージェントが文脈の中で自分の過ちを「見ない」場合、彼はそれらを修正したり、行動を調整したりすることはできません。
• 幻覚・・・また。

Solution: Errors are included in the prompt or memory. The idea is to try implementing some kind of "self-healing." Agent should at least try to correct its behavior and adapt.

Rough Flow:

• 誤りを理解する
• Self-correction:
  • Self-correction mechanisms: Error Detection, Reflection, Retry Logic, Retry with changes (Agent can modify request parameters, rephrase the task, or try a different tool)
  • Impact of reflection type: More detailed error information (instructions, explanations) usually leads to better self-correction results. Even simple knowledge of previous errors improves performance.
  • Internal Self-Correction: Training LLMs for self-correction by introducing errors and their fixes into training data.
• 人間の助けを求める:自己修正が失敗した場合、エージェントは問題を人間にエスカレートする(原則7参照)。

Checklist:

• 前のステップのエラーが文脈に保存されます
• RETRY LOGIC 存在
• Fallback/human escalation は、繰り返しの失敗に使用される。

9. Break Complexity into Agents

Problem:重要なLLMの制限(そのコンテキストウィンドウの問題)に戻ろうが、この問題を別の角度から見てみましょう。タスクが大きくなり、より複雑になるほど、より多くのステップが取れることになります、これはより長いコンテキストウィンドウを意味します。コンテキストが成長するにつれて、LLMはより迷うか焦点を失う可能性があります。

Solution:1つのエージェント=1つのタスク、上からのオーケストラ。

小さな、集中的なエージェントの利点:

• 管理可能なコンテキスト:より小さなコンテキストウィンドウはより良いLLMパフォーマンスを意味します
• 明確な責任:各エージェントには明確な範囲と目的があります。
• 信頼性の向上:複雑なワークフローで迷う可能性の低下
• よりシンプルなテスト:特定の機能をテストし、検証するのが簡単
• Improved debugging: Easier to identify and fix problems when they arise

Unfortunately, there's no clear heuristic for understanding when a piece of logic is already big enough to split into multiple agents. I'm pretty sure that while you're reading this text, LLMs have gotten smarter somewhere in labs. And they keep getting better and better, so any attempt to formalize this boundary is doomed from the start. Yes, the smaller the task, the simpler it is, but the bigger it gets, the better the potential is realized. The right intuition will only come with experience. But that's not certain.

Checklist:

• Scenario is built from microservice calls

• Agents can be restarted and tested separately

• Agent = minimal autonomous logic. You can explain what it does in 1-2 sentences.

  
  

  

  
  

3.コントロール・インタラクション・モデル

モデルは世代を扱います. 他のすべてはあなた次第です。

モデルは世代を扱います. 他のすべてはあなた次第です。

あなたが要求をどのように表現したか、文脈の中で何を伝えたか、どのような指示を与えたか、これらはすべて、結果が一貫性あるいは「創造性」であるかどうかを決定します。

LLMs don't read minds. 彼らはトークンを読む。

つまり、すべての入力エラーが出力バグに変わる――ただちに顕著ではない。

このセクションは、すべてを動かすことを許さないことについてです: prompts = コード、明示的な文脈管理、限界内のモデルを制限します。

10. Treat Prompts as Code

Problem:非常に一般的なパターン、特にMLやSEの背景を持たない人々の間では、プロンプトをコードに直接保存するか、最善の場合には、外部ファイルの非体系的なストレージです。

このアプローチは、いくつかのメンテナンスとスケーリングの困難につながります:

• ナビゲーション、理解、変更は、プロジェクトの複雑さとプロンプトの数が増加するにつれて複雑になります。
• 明示的なバージョニングがなければ、迅速な進化、変更の理由を追跡し、パフォーマンスの悪化の場合に以前の安定したバージョンに戻ることは非常に困難です。
• Inefficient improvement and debugging process: Prompt optimization without objective metrics and testing becomes a subjective and labor-intensive process with unstable results.
• 他のチームメンバーの認識は、将来のあなたを含む(そして特に)複雑になります。

Solution:この文脈におけるプロンプトは、コードとはあまり異なるものではなく、同じ基本的なエンジニアリング慣行を適用すべきである。

This implies:

• 特別なファイル( .txt、 .md、 .yaml、 .json など)またはテンプレート管理システム( Jinja2, Handlebars など、BAML などの専門ツール)を使用して、別途、体系的に保存します。
• Explicit prompt versioning. You can even do A/B tests with different versions after this. この後、異なるバージョンでA/Bテストもできます。
• Testing. You heard that right.
  • This could be something like unit tests, where you compare LLM responses to specific inputs against reference answers or expected characteristics depending on the prompt
  • Evaluation datasets
  • Format compliance checks and presence/absence of key elements - For example, if a prompt should return JSON, the test can validate its structure
  • Even LLM-as-a-judge if your project and design justify it.

We'll talk about testing in more detail in the principe 14.

Checklist:

• プロンプトは、ビジネス論理から別々のファイルに保存されます。
• DIFF&HISTORYの変化
• テスト(必要に応じて)
• (オプション) コードレビューの一部としての迅速なレビューはどうですか?

11.文脈エンジニアリング

Problem:私たちはすでにLLMの「忘却性」について話し合っており、これを部分的に外部メモリに履歴をダウンロードし、異なるタスクのための異なるエージェントを使用することによって解決しましたが、それだけではありません。

Standard formats aren't always optimal:シンプルなリストのメッセージの「役割コンテンツ」 (system/user/assistant) フォーマットはベースラインですが、トークン重く、十分な情報性がなく、またはエージェントの複雑な状態を伝達するのに不十分です。

ほとんどのLLMクライアントは、標準メッセージ形式(オブジェクトのリスト)を使用します。role「システム」、「ユーザー」、「アシスタント」contentそして、時々tool_callsフィールド)

これが「ほとんどの場合にうまく機能する」にもかかわらず、maximum efficiency(トークンとモデルの関心の両方に関して)、私たちはより創造的にコンテキスト形成に近づくことができます。

Solution:エンジニアリングするには、LLMに渡された情報パッケージ全体の作成を、"Context Engineering."これは、

1. 完全なコントロール:どの情報がLLMのコンテキストウィンドウに入るか、どのような形、量、順序で完全な所有権を取る。
2. Custom Formats を作成する: 標準的なメッセージリストに限定されない. 自分のタスク最適化されたコンテキストを表現する方法を開発する. たとえば、XML のような構造を使用して、さまざまな種類の情報(メッセージ、ツール呼び出し、その結果、エラーなど)を一つまたは複数のメッセージに密接にパッケージすることを検討するかもしれません。
3. 全体的なアプローチ:コンテキストを単なる対話履歴としてではなく、モデルに必要なすべての総合として見る:即時プロンプト、指示、RAGシステムからのデータ、ツール呼び出しの履歴、エージェントの状態、他の相互作用からのメモリ、そして望ましい出力形式に関する指示さえ。

(Instead of a checklist) How do you know when this makes sense?

もしあなたが以下のいずれかに興味があるなら:

• 情報密度:最大の意味と最小の騒音。
• コスト効率:比較可能な品質を低価格で手に入れることができるトークンの数を減らす。
• エラー操作の改善
• セキュリティ: 機密情報の含有を処理し、コントロールし、それをフィルタリングし、すべてを「すみません、私は小さな大きな言語モデルだけです」というクラシックな答えを出すことによって終わります。

12. Constrain the Chaos: Secure Inputs, Guarded Actions, and Grounded Outputs

Problem:我々は既に安定の名のもとで多くのことをしたが、何も銀の弾ではないということは、最も重要な潜在的な問題を別々に見る価値があり、明示的にいくつかの「保険」を取る価値があることを意味する。

この原則から、私たちは考える:

• 可能なプロンプトインジェクション. あなたのエージェントがユーザーと直接コミュニケーションをとる場合、あなたは入力として供給されるものを制御する必要があります. ユーザの種類に応じて、あなたはあなたのフローを破壊し、エージェントが最初の目標を無視し、間違った情報を提供し、有害なアクションを実行したり、悪意のあるコンテンツを生成することを望むものを得るかもしれません。
• 上記の理由、または「頭の中の声」によって導かれるため、エージェントは、ユーザーの個人データ、企業の秘密など、重要な情報を開示する可能性があります。
• 毒性あるいは悪意のあるコンテンツを生成する場合、この点を無視してください。
• 情報が欠けているときに物事を作り上げる 永遠の痛み
• 許容範囲を超えて行きます。機械の昇格、覚えておいてください? しかし、真剣に、その推論のプロセスで、エージェントは非常に非微妙なソリューションに到達することができ、すべてが正常な行動の範囲内ではありません。

LLMエージェントのセキュリティと地盤化は単一の措置ではなく、相互作用の全生命周期をカバーする複数の層の保護システム(「防衛の深さ」)です。脅威は多様で、保護の1つの方法はパナセイアではありません。効果的な保護には技術の組み合わせが必要です。

Solution:我々は多層防衛システムにコミットし、あらゆる角度のケースと潜在的なシナリオを検討し、明確に処理し、何が起きても明確な対応を準備しなければならない。

基本的な設定では、あなたは考慮すべきです:

1. Secure Inputs.

   1. Check for known attack-indicator phrases (e.g., "ignore all previous instructions"). It sometimes makes sense to combat potential obfuscation.
   2. Try to determine the user's intent separately. You can use another LLM for this, to analyze the input for the current one.
   3. Control input from external sources, even if they are your own tools.

2. Guarded Actions. Control the privileges of both the agent and its tools (granting the minimum necessary), clearly define and limit the list of available tools, validate parameters at the input to tools, and enable Principle #7 (Human in the Loop).

3. Output Moderation. Design a system of checks for what the model outputs, especially if it goes directly to the user. These can be checks for relevance (ensuring the model uses what's in the RAG and doesn't just make things up) as well as checks for general appropriateness. There are also ready-made solutions (e.g., the OpenAI Moderation API).

しかし、最終的なシステムは、あなたの課題とリスク評価に依存します。チェックリストでは、いくつかのオプションをスケッチしようとします。

Checklist:

• User input validation is in place.

• For tasks requiring factual information, the data within the RAG is used.

• The prompt for the LLM in a RAG system explicitly instructs the model to base its answer on the retrieved context.

• LLM output filtering is implemented to prevent PII (Personally Identifiable Information) leakage.

• The response includes a link or reference to the source.

• LLM output moderation for undesirable content is implemented.

• The agent and its tools operate following the principle of least privilege.

• The agent's actions are monitored, with HITL (Human-in-the-Loop) for critical operations.

  
  

  

  
  

IV. Keep It Alive

「Kinda works」というエージェントは、遅延効果のバグです。

「Kinda works」というエージェントは、遅延効果のバグです。

プロデュースでは、すべてが一度に壊れるのではなく、あなたはすぐにそれについて知ることはできません。

このセクションはエンジニアリングの習慣についてです。seeing what's happeningそしてchecking that everything is still working. Logs, tracing, tests—everything that makes an agent's behavior transparent and reliable, even when you're sleeping or developing your next agent.

13. Trace Everything

Problem:あるいは別の方法で、エージェントが予想通りに動作しない状況に常に直面するでしょう 開発、テスト、変更、または正常な運用中に これは避けられないこと、そして現在、ある程度は正常です。これはあなたが何時間も何日もデバッグを費やし、何が間違っているかを理解し、問題を再現し、それを修正しようとしていることを意味します。 私は、この時点であなたがすでに原則#1 (コンパクトエラー)と#8 (コンパクトエラーを文脈に置く)を実行していると考えたいです。ほとんどの場合、それはあなたの人生をより簡単にするのに十分です。

それにもかかわらず(特に今はそれらに悩まないことを決めた場合)、事前にデバッグについて考えて、この原則に従って将来に時間を節約し、神経を節約することは非常に有意義です。

Solution:リクエストからアクションに至るまでの全パスをログする。すでに個々のコンポーネントのログを持っている場合でも、全体のチェーンを追跡することは困難です。たとえあなたがパズルやレゴの大ファンであるとしても、ある時点で、それは面白くなくなります。したがって、ログは存在する必要があります、それらは端から端にあり、それらはすべてをカバーする必要があります。

Why it's needed:

• デバッグ - 物事がどこで間違ったのかをすぐに見つける。
• アナリティクス — ボトルネックがどこにあるか、どのように改善するかを見る。
• 品質評価 - 変化が行動にどのように影響するかを見る。
• 再生可能 - ステップを正確に再構築できます。
• 監査 - エージェントのすべての決定と行動のログ。

基本的な「紳士のセット」はこんな感じです。

• 入力:最初のユーザーリクエスト、前のステップから受信したパラメータ。
• エージェントステータス:ステップを実行する前にエージェントのキーステータス変数。
• プロンプト:LLMに送信されたプロンプトの完全なテキスト、システム指示、対話履歴、取得したRAG文脈、ツール説明など。
• LLMの出力:あらゆる解析または処理の前に、LLMからの完全な、原始的な応答。
• ツール呼び出し:LLMがツールを呼び出すことを決定した場合 - ツールの名前と呼び出された正確なパラメータ(構造出力によると)。
• ツール 結果:ツールが返した応答、成功結果とエラー メッセージの両方を含む。
• エージェントの決定:エージェントがLLMの反応やツールの結果に基づいて下した決定(例えば、次にどのようなステップを実行するか、ユーザーにどのような答えを与えるか)
• メタデータ:ステップ実行時間、LLMモデル、通話費用(利用可能な場合)、コード/プロンプトバージョン。

Note:既存のトラッキングツールを調べてみて、一定の条件下で生活を楽にすることができます。例えば、LangSmithは、通話チェーン、プロンプト、応答、ツール使用の詳細な視覚化を提供します。あなたはまた、Arize、Weights & Biases、OpenTelemetryなどのツールをあなたのニーズに合わせて調整することができます。しかし、まず、原則 #15 を参照してください。

Checklist:

• すべてのエージェントステップがログされている(あなたの「紳士のセット」のバージョン)。
• ステップは session_id と step_id でリンクされます。
• チェーンの全体を見るためのインターフェイスがあります。
• LLMに送信されたプロンプトは、どの段階でも再生することができます。

14. Test Before You Ship

Problem:この時点で、おそらくあなたは実質的に完成したソリューションのいくつかの種類を持っています。それは機能し、おそらくあなたが望んだ方法でさえも機能します。それをプロデュースに送信しますか? しかし、私たちはそれをどのように確保しますか?続く次の小さい更新の後でさえ? はい、私はテストの話題に私たちを導きます。

明らかに、LLMシステムのアップデートは、他のすべてのシステムと同様に、アプリケーションコードの変更、細かい調整やRAGのためのデータセットのアップデート、ベースLLMの新しいバージョン、あるいは小さなプロンプトの調整であろうと、しばしば既存の論理や予期せぬ、時には劣化するエージェントの行動の意図的な破損につながります。

• Model Drift. You have not done anything, but performance has dropped over time. もしかしたらプロバイダーがモデルを更新し、入力データの性質が変わったのかもしれない(データドリフ)―昨日機能したものは今日機能しなくなるかもしれない。
• Prompt Brittleness. Even a small change to a prompt can break the established logic and distort the output. プロンプトの小さな変更でさえ、既存の論理を破り、出力を歪曲することができます。
• Non-determinism of LLMs: As you know, many LLMs are non-deterministic (especially with temperature > 0), meaning they will generate different responses to the same input on each call. This complicates the creation of traditional tests that expect an exact match and makes reproducing errors more difficult.
• 最初の原則を実装した場合に簡単になりますが、デバッグのための特定のエラーを再現することは、固定データと状態でさえ困難です。
• 複雑なシステムでは、単一の要素(モデルやプロンプトなど)の更新は、API、データベース、ツールなどの連鎖を通過し、他の場所での行動の変化につながる可能性があります。
• 幻覚

しかし、我々はすでに、明確なコード論理を検証することに焦点を当てた伝統的なテストが、これらの問題を完全にカバーできないことを理解している。

Solution:私たちは複雑で包括的なアプローチを策定し、多くのことをカバーし、古典的なソリューションとドメイン特有のソリューションを組み合わせなければなりません。

• 複数のレベルのテスト:システムのさまざまな側面をターゲットとする異なるテストタイプの組み合わせ:個々の機能とプロンプトの低レベルのユニットテストから、エージェントのエンド-to-エンドワークフローとユーザーの相互作用を検証する複雑なシナリオまで。
• LLMの行動と品質に焦点を当てる:テストは、有害または偏見のあるコンテンツの欠如、関連性、正確性、一貫性、指示や特定のスタイルへの遵守などのLLMの反応の機能的正確性だけでなく、質的特徴を評価する必要があります。
• さまざまな入力例と参照(または許容範囲の)出力を含む「ゴールデンデータセット」を含む回帰および品質テスト。
• 自動化とCI/CDへの統合
• Human-in-the-loop 評価: LLM-evalの特定の段階では、メトリックをカリブレートし、複雑なまたは重要なケースをレビューするための人間を含むべきです。
• prompt development and testing: prompt engineering は、プロンプトの各バージョンが実装前に徹底的にテストされ、評価される iterative process として扱われるべきである。
• Testing at different levels of abstraction:
  • Component testing: Individual modules (parsers, validators, API calls) and their integration.
  • Prompt testing: Isolated testing of prompts on various inputs.
  • Chain/Agent testing: Verifying the logic and interaction of components within an agent.
  • End-to-end system testing: Evaluating the completion of full user tasks.

Checklist:

• Logic is broken down into modules: functions, prompts, APIs—everything is tested separately and in combination.

• Response quality is checked against benchmark data, evaluating meaning, style, and correctness.

• Scenarios cover typical and edge cases: from normal dialogues to failures and provocative inputs.

• The agent must not fail due to noise, erroneous input, or prompt injections—all of this is tested.

• Any updates are run through CI and monitored in prod—the agent's behavior must not change unnoticed.

  

Principle 15: Own the Execution Path

これはメタ原則であり、上記のすべてを通して実行されます。

幸いなことに、今日私たちは任意のタスクのために何十ものツールとフレームワークを持っています。これは素晴らしい、それは便利で、それはです。

ほとんどの場合、準備済みのソリューションを選ぶことは、trade-offあなたはスピードと簡単なスタートを得るが、あなたは負ける。flexibility, control, and, potentially, security.

これは、管理することが重要なエージェント開発において特に重要です:

• LLMの予測不可能さは、
• 過渡期と自己修正のための複雑な論理
• システムの適応と進化に備え、そのコアの任務が変わらなかったとしても。

フレームワーク bringinversion of control:彼らは、エージェントがどのように働くべきかをあなたのために決定します。これはプロトタイプを簡素化するが、長期的な開発を複雑にすることができます。

上記の原則の多くは、オフ・ザ・シェルフ・ソリューションを使用して実施することができるが、これはしばしば正当化される。explicit implementation of the core logic takes a comparable amount of time比較的多く提供するtransparency, manageability, and adaptability.

反対の極端も存在する――。over-engineering何もかもをゼロから書くという欲求、これは間違いでもある。

This is why the key is balance.エンジニアは自分で選択する:フレームワークに頼るのが合理的で、コントロールを維持することが重要な場所。

あなたは覚えておかなければなりません:業界はまだ形をとっている。現在の基準が現れる前に多くのツールが作られました。明日には、それらは時代遅れになる可能性がありますが、今日のあなたのアーキテクチャに埋め込まれた制限は残ります。

Conclusion

Okay, we have gone over 15 principles that, experience shows, help turn the initial excitement of "it's alive!" into confidence that your LLM agent will work in a stable, predictable, and useful way under real-world conditions. あなたのLLMエージェントは、現実世界の条件下で安定した、予測可能な、有用な方法で働くことを確信しています。

それぞれを考慮して、プロジェクトに適用する意味があるかどうかを確認する必要があります. 結局、それはあなたのプロジェクト、あなたのタスク、あなたの創造です。

Key takeaways to carry with you:

1. エンジニアリングのアプローチは重要です:LLMの「魔法」に頼らないでください 構造、予測性、管理性、およびテスト可能性はあなたの親友です。
2. LLMは強力なコンポーネントですが、まだ単なるコンポーネントです:あなたのシステムの非常にスマートで、しかし、単一のコンポーネントとしてLLMを扱う。
3. イテレーションとフィードバックは成功の鍵です:最初の試みで完璧なエージェントを作成することは稀です. 実験、測定、エラー分析、およびエージェント自体とあなたの開発プロセスの継続的な改善のための準備をしてください. HITL (Human in the loop) を含むことは、セキュリティだけでなく、学習のための貴重なフィードバック源をもつことでもあります。
4. コミュニティとオープン性:LLMエージェントの分野は急速に進化しています。新しい研究、ツール、および最良の実践を注視し、独自の経験を共有します。あなたが直面する問題の多くは、すでに誰かが解決しているか、または今解決しています。

私はあなたがここで新しい役に立つ何かを見つけたことを願っていますし、もしかしたらあなたはあなたの次のエージェントを設計するときにこれに戻りたいかもしれません。