なぜたくさんのチュートリアルを見ても、まだ最初のエージェントの書き方がわからないの?

「エージェントエンジニアになる方法」と検索すると、おそらく複数のAIプロジェクトを書いています—APIを調整し、OpenAIを使い、LangChainやSemantic Kernelを使ったことがあるでしょう。 Agent Engineerは一つだけのコンセプトだと思うかもしれませんが、実際にエディタを開くと、最初のコードの行に何を書けばいいのかわかりません。

これはスキルの問題ではなく、出会うチュートリアルでエージェント、ループ、ツールの使用など、すべてのカバーコンセプトがわかります。 しかし、エージェントデモをローカルで実行した後、なぜ翌日に動作しなくなるのかは誰も教えてくれません。それが本当の理由です。

エージェントエンジニアに変身する上で最も重要なステップ:デモから信頼性の高い再利用性へ

ほとんどのチュートリアルでは、チェーンコールの書き方を教えてくれます:

「`python

典型的 Demo 写法，问题很多

agent = Agent(model="gpt-4", tools=[search_tool, calculator_tool]) result = agent.run("计算今天的股票收益") print(result) 」

这段代码能跑，但你在生产环境中绝对不敢部署。为什么？

• 没有重试机制：模型接口超时或返回错误时，整个流程直接崩溃。
• 没有状态持久化：每次运行都从头开始计算 Context，无法支持多轮对话。
• 没有错误隔离：当 search_tool 失效时，calculator_tool 的数据源不对，但错误信息混在一起难以排查。

最关键的一步，不是学会用某个框架，而是学会构建一个带有运行状态管理和错误恢复的 Agent 循环。这才是区分普通开发者和 Agent Engineer 的分水岭。

最容易失败的地方：Context 管理不当导致行为不可控

我见过最多失败案例：Agent 在简单任务上表现完美，但在复杂场景中开始“胡说八道”或“陷入死循环”。

根源在于 Context 没有做分层管理。开发者通常只有一个大 Context Window，把所有历史对话、工具返回、系统指令全部塞进去。当 Token 接近上限时，模型开始忘记早期指令，或者把工具返回的错误结果当成事实。

真实场景： 某开发者用 Agent 自动生成代码 review 报告。Agent 先调用 git 获取 diff，再调用静态分析工具，最后生成建议。起初 3 次以内都能正确执行，但第 4 次任务时，Agent 把前一次 review 的结论错误地当成了当前 diff 的一部分。

为什么？因为 Context 没有做 session 隔离。历史 Session 的 tool return 被当作当前 Session 的输入。

排查方法：

1. 在 Agent 循环的每一步注入日志，打印当前 Context 中的关键字段（比如 system_prompt、tool_result、last_action）。
2. 检查每次 Loop 开始前是否清理了不属于本 Session 的历史记录。
3. 设置 Max Loop 次数上限，并记录触达上限时的 Context 内容——看是重复相同 Action，还是在不同 Action 间循环。

一条最小可执行路径：从今天开始

不要追求完美，先跑通一个带错误处理的最小 Agent。

第一步：选择基础层

• 如果你熟悉 Python，直接用 OpenAI 的 Responses API（或 Anthropic 的 Messages API），不要一开始就上框架。
• 如果你喜欢代码可读性，用 LangChain 的 AgentExecutor 但关闭自动重试，自己写重试逻辑。

第二步：写一个带状态管理的 Agent 循环

`」 OpenAIインポートよりOpenAI import JSON

クラス MinimalAgent: def init(self, model="GPT-4o", max_loops=10): self.client = OpenAI() self.model = model self.maxループ = max_loops self.history = [] # アシスタントとユーザーメッセージだけを保存し、完全な返却ツールは保存しない?

def run(self, user_input, tools=[]): self.history.append({"role": "user", "content": user_input}) loop_count = 0 loop_count < self.max_loops: response = self.client.chat.completions.create( model=self.model, メッセージ=self.history、 tools=tools、 tool_choice=「オート」 ) msg = response.choices[0].message もしmsg.tool_callsなら: # ツールコールを処理し、例外キャプチャに注意 msg.tool_callsのコールイン: function_name = call.function.name 試してみて: function_args = json.loads(call.function.arguments) 結果 = self.call_tool(function_name, function_args) 例外はe: result = f"エラー呼び出し {function_name}: {str(e)}" self.history.append({ 「role」:「tool」、 「tool_call_id」:call.id、 「内容」:結果 }) loop_count += 1 その他: self.history.付加記(msg) 返却 msg.content raise TimeoutError(f"Max loops {self.max_loops} reached without final answer") 「`

注意上面代码里的陷阱：`self.history」はユーザーおよびアシスタントのメッセージのみを保存しますが、ツールの返却は直接添付されます。 これにより文脈内で無限の成長が生まれます。 正しい方法は、各ループの最後に古いツールのリターン値を圧縮またはクリーンアップし、直近2ラウンドの結果だけを残すことです。

ステップ3:境界チェックを追加する

run法では、次のように追加します:

• 同じ工具が連続して3回呼び出されると、ループは強制的に終了し、「ツール呼び出しがループに詰まった」と返されます。
• ツールがエラーを返した場合、再試行せず、モデルが正しい結果を「推測」するのではなく、直接ユーザーにエラーを報告します。

失敗しやすい詳細:すべての問題を手書きしなければならないのか?

いいえ。 ツール統合の作業量を減らすために、MCP(モデルコンテキストプロトコル)を使うことができます。 MCPは、エージェントがローカルまたはリモートサービスを直接利用できる標準インターフェースを提供します。 ただし注意:MCPはコンテキスト管理、エラー回復、ループ制限には役立たず、これらはすべて自分で実装する必要があります。

故障シナリオ: あるチームはMCPを使って5つの外部ツールに接続し、エージェントが自動的に調整すると想定していました。 その結果、ユーザーが「2つのプロジェクトのコード複雑さを比較してください」と尋ねた際、エージェントは複数のツールを呼び出しましたが、それぞれ異なるデータ形式を返すため一貫性のないデータを返しました。エージェントは標準化せずに出力を混同しました。

次のステップ:最低限の可用性からエンジニアリングへ

上記の最小エージェントを習得したら、次のステップはフレームワークの概念を学ぶことではなく、次のステップです:

1. 記録の導入:各ループの行動、観察、思考を構造的に記録する。
2. キャッシュの導入:計算やAPIクエリなどのツール呼び出しの結果をキャッシュすること。
3. テスト導入:「ツール呼び出し失敗」「ループオーバーリミット」「コンテキストオーバーフロー」の3つのシナリオをカバーするユニットテストを書きます。
4. 続いて、エージェントの観察可能性、マルチエージェント協働、長期記憶などの高度なトピックの体系的な研究を全コースで履修します。

準備ができているなら、より体系的な学習パスに進むことも検討してください。