SKILLOfficialdevelopment

troubleshoot

プラグイン: atomic-agents
ソース: GitHub で見る ↗

説明

失敗したり動作がおかしくなったりしているAtomicエージェント（AIスキル）アプリを診断して修正します。インポート関連のエラー、スキーマ検証失敗、LLMの出力が空または形式が不正である問題、プロバイダー（AIサービス提供者）のロール・モード関連エラー、履歴やコンテキスト（会話の背景情報）の問題、MCPの通信エラーなど、様々な問題に対応できます。次のような場合に使用: - ユーザーがエラー情報やエラー追跡ログ、またはAtomicエージェントコード内の不正な動作を報告している - 「なぜエージェントが動作しない／クラッシュする／ゴミのような結果を返すのか」と質問がある - `ValidationError`（検証エラー）、`ImportError`（インポートエラー）、またはAtomicエージェントプロジェクトのプロバイダーAPI関連エラーが貼り付けられている

原文を表示

Diagnose and fix a failing or misbehaving Atomic Agents app — import errors, schema validation failures, empty or malformed LLM output, provider role/mode errors, history and context problems, MCP transport errors. Use when the user reports an error, traceback, or wrong behavior in atomic-agents code, asks "why is my agent not working / crashing / returning garbage", or pastes a `ValidationError`, `ImportError`, or provider API error from an atomic-agents project.

ユースケース

エージェントアプリが動作しない・クラッシュするとき
エラー情報やログが報告されたとき
インポート関連のエラーが発生したとき
LLMの出力が空または形式不正なとき
プロバイダーのロール・モード関連エラー時

本文（日本語訳）

Atomic Agentsアプリのトラブルシューティング

「動かない」という瞬間のための診断ワークフロー。Atomic Agentsの大半の不具合は、既知の十数種類の原因のいずれかで、それぞれ解決方法が決まっています。症状を特定して対策を実施し、再実行で確認します。

ワークフロー

失敗の内容を把握する。 正確なエラー表示（スタックトレース）または誤った出力サンプルと、それを起こしたコード（エージェントの構築、スキーマ、クライアント接続部分）を集めます。ユーザーがエラーの一部だけを貼り付けている場合は、推測する前に完全なエラー表示を求めてください。
下の症状表と照らし合わせる。 引用されている文字列はフレームワークが実際に表示するメッセージです。その文言で判定します。
対策を実施して再実行する。 再実行で成功を確認するまでは、問題が解決したと宣言しないでください。
該当する症状がない場合は、 下部の参照表で該当する領域のドキュメントを確認し、そこから推論してください。1つのエラーではなくコード全体の監査が必要な場合は、atomic-reviewerサブエージェントに委譲してください。

症状表

インポートと定義のエラー

症状	原因	対策
`atomic_agents.lib.*`、`atomic_agents.agents.base_agent`、または `BaseAgent` での `ImportError`/`ModuleNotFoundError`	v1時代のインポート経路。v2では削除された	トップレベルからインポート: `from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema, BaseTool`; 文脈情報は `atomic_agents.context` から
インポート時の `ValueError: <Name> must have a non-empty docstring to serve as its description`	`BaseIOSchema`のサブクラスにドキュメント文字列がない	スキーマを説明するドキュメント文字列を追加してください。LLMのプロンプトに含まれるため、AIモデル向けに書いてください
`AgentConfig`構築時の `ValidationError`で`client`について苦情がある	provider SDKの生のクライアントが渡されている。`AgentConfig.client`はInstructor（出力形式の構造化ツール）でラップされたクライアントが必要	ラップする: `instructor.from_openai(...)`、`instructor.from_anthropic(...)`、`instructor.from_genai(...)`
型パラメータ欠落についての `TypeError`、またはカスタムスキーマが期待されているのに`BasicChatOutputSchema`で出力される	`AtomicAgent`がジェネリクス（型パラメータ）なしでインスタンス化された	`AtomicAgent[InputSchema, OutputSchema](config=...)` と書く。型パラメータは実行時の情報を持ち、Instructorの`response_model`を駆動します

実行時のプロバイダー（API提供者）エラー

症状	原因	対策
`max_tokens`が必須という内容のAnthropicエラー	Anthropropicはリクエスト毎に必須	`AgentConfig`で`model_api_parameters={"max_tokens": 4096}`を設定
ロール名またはロール順序が無効というGeminiエラー	Geminiはアシスタントロールを`model`と呼ぶ	`AgentConfig`で`assistant_role="model"`を設定; `instructor.from_genai(...)`を`mode=Mode.GENAI_TOOLS`で使用し、`AgentConfig.mode`を合わせる
Groq / Ollama / MiniMaxで出力が空、`None`フィールド、またはJSON解析エラー	プロバイダーがJSONモード（厳密な出力形式）を必要とする; ファクトリとコンフィグのモード設定が一致していない	クライアント作成時に`Mode.JSON`で設定し、`AgentConfig`でも`mode=Mode.JSON`に統一。2つは常に一致する必要があります
OpenAIでは動くが、別のプロバイダーではコード変更なしに動かない	プロバイダー毎の癖は、エージェント側ではなく`AgentConfig`に含まれている	framework/references/providers.mdの「プロバイダー別対応表」を確認してください

動作が誤っている、または劣化している（例外なし）

症状	原因	対策
再試行後の`run()`内から発生するPydanticの`ValidationError`	モデルが出力スキーマを満たすことができない	まずフィールドの`description=`とスキーマのドキュメント文字列を改善し、制約が厳しすぎないか緩和します。その後で強力なモデルへの変更を検討してください。`parse:error`フックで試行内容を検査可能
エージェントが前のやり取りを「忘れている」	呼び出し毎に新しい`ChatHistory`が作られている、または何も渡されていない	1つの`ChatHistory`を作り、複数の`run()`呼び出しで使い回す
長いセッションで、文脈や利用コストが限度なく増え続ける	会話履歴に制限がない	`AgentConfig`で`max_context_tokens`を設定。古いやり取りは自動的にトリム（削除）されます
LLMの呼び出しさえ始まる前に、すべての`run()`が遅い	文脈プロバイダーの`get_info()`に、待機を伴う処理がある	`get_info()`は`run()`のたび実行されます。データ取得を外に出す、キャッシュする、またはプロバイダーが事前計算済みの状態を保持するように変更してください
`history.load(...)`が「動かない」	クラスメソッド（クラス全体で共有する方法）として呼ばれている	`load`はインスタンスメソッド（個別オブジェクトへの操作）で、その場で内容を変更します: `history = ChatHistory(); history.load(saved)`。`dump()`はJSON文字列を返します

MCPの相互運用

症状	原因	対策
`AttributeError: STREAMABLE_HTTP`	そのようなメンバーは存在しない	`MCPTransportType.HTTP_STREAM` (他: `SSE`、`STDIO`)
MCPツールは読み込まれるが呼び出しが失敗	通信方式またはエンドポイントのミスマッチ	framework/references/tools.mdのMCPセクションと`mcp-agent`の例を参照

エスカレーション（問題の段階的対応）マップ

該当する領域	確認先
スキーマ設計、バリデーション（入力値の検証）	framework/references/schemas.md
エージェント設定、実行モード、ストリーミング（段階的送信）	framework/references/agents.md
プロバイダー接続、ロール、モード	framework/references/providers.md
会話履歴、保存、マルチエージェント間の記憶管理	framework/references/memory.md
フック（処理の割り込み）、再試行、計測・監視	framework/references/hooks.md
ツール、MCP	framework/references/tools.md
エージェント間の統合・調整	framework/references/orchestration.md

関連スキル: framework（一般的な指針・自動起動）、create-atomic-agent / create-atomic-schema / create-atomic-tool / create-atomic-context-provider（修正ではなく新規構築用）。現在は動いているが内容を確認してほしいコードについては、atomic-reviewerサブエージェントをご利用ください。

原文（English）を表示

Troubleshoot an Atomic Agents App

Diagnostic workflow for the "it's broken" moment. Most atomic-agents failures are one of a dozen known causes with mechanical fixes. Match the symptom, apply the fix, verify by re-running.

Workflow

Capture the failure. Get the exact traceback or wrong-output sample plus the code that produces it (agent construction, schemas, client wiring). If the user pasted only a fragment of the error, ask for the full traceback before guessing.
Match against the symptom table below. The quoted strings are the framework's real messages — match on them.
Apply the fix and re-run the failing snippet. Do not declare the problem solved without a passing re-run.
No match? Load the reference for the failing area (table at the bottom) and reason from there. For a whole-codebase audit rather than one failure, delegate to the atomic-reviewer subagent instead.

Symptom table

Import and definition errors

Symptom	Cause	Fix
`ImportError`/`ModuleNotFoundError` on `atomic_agents.lib.*`, `atomic_agents.agents.base_agent`, or `BaseAgent`	v1 import paths, removed in v2	Import from the top level: `from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema, BaseTool`; context pieces from `atomic_agents.context`
`ValueError: <Name> must have a non-empty docstring to serve as its description` at import time	`BaseIOSchema` subclass without a docstring	Add a docstring describing the schema — it flows into the LLM prompt, so write it for the model
`ValidationError` when constructing `AgentConfig`, complaining about `client`	Raw provider SDK client passed; `AgentConfig.client` requires an Instructor-wrapped client	Wrap it: `instructor.from_openai(...)`, `instructor.from_anthropic(...)`, `instructor.from_genai(...)`
`TypeError` about missing type parameters, or output typed as `BasicChatOutputSchema` when a custom schema was expected	`AtomicAgent` instantiated without generics	Write `AtomicAgent[InputSchema, OutputSchema](config=...)` — the type parameters carry runtime information (they drive Instructor's `response_model`)

Provider errors at run time

Symptom	Cause	Fix
Anthropic error mentioning `max_tokens` is required	Anthropic requires it per request	`model_api_parameters={"max_tokens": 4096}` on `AgentConfig`
Gemini error about invalid role / role ordering	Gemini names the assistant role `model`	`assistant_role="model"` on `AgentConfig`; use `instructor.from_genai(...)` with `mode=Mode.GENAI_TOOLS` and match `AgentConfig.mode`
Empty output, `None` fields, or JSON-parse noise on Groq / Ollama / MiniMax	Provider needs JSON mode; factory and config modes disagree	Create the client with `Mode.JSON` and set `mode=Mode.JSON` on `AgentConfig` — the two must always match
Works on OpenAI, breaks on another provider with no code change	Provider quirks live in `AgentConfig`, not the agent	Check the per-provider matrix in framework/references/providers.md

Wrong or degraded behavior (no exception)

Symptom	Cause	Fix
Pydantic `ValidationError` from inside `run()` after retries	Model can't satisfy the output schema	Improve field `description=`s and the schema docstring first; loosen over-tight constraints; only then consider a stronger model. Inspect attempts via the `parse:error` hook
Agent "forgets" earlier turns	Fresh `ChatHistory` created per call, or none passed	Create one `ChatHistory` and reuse it across `run()` calls
Context/cost grows without bound in long sessions	Unbounded history	Set `max_context_tokens` on `AgentConfig` — oldest turns are trimmed automatically
Every `run()` is slow before the LLM call even starts	Blocking I/O in a context provider's `get_info()`	`get_info()` runs on every `run()`; move fetching out, cache, or make the provider hold precomputed state
`history.load(...)` "doesn't work"	Called as a classmethod	`load` is an instance method that mutates in place: `history = ChatHistory(); history.load(saved)`. `dump()` returns a JSON string

MCP interop

Symptom	Cause	Fix
`AttributeError: STREAMABLE_HTTP`	No such member	`MCPTransportType.HTTP_STREAM` (others: `SSE`, `STDIO`)
MCP tools fetch but calls fail	Transport/endpoint mismatch	See MCP section of framework/references/tools.md and the `mcp-agent` example

Escalation map

Failing area	Load
Schema design, validators	framework/references/schemas.md
Agent config, run modes, streaming	framework/references/agents.md
Provider wiring, roles, modes	framework/references/providers.md
History, persistence, multi-agent memory	framework/references/memory.md
Hooks, retries, telemetry	framework/references/hooks.md
Tools, MCP	framework/references/tools.md
Orchestration between agents	framework/references/orchestration.md

Related skills: framework (general guidance, auto-triggers), create-atomic-agent / create-atomic-schema / create-atomic-tool / create-atomic-context-provider (building rather than fixing). For a review of code that isn't currently failing, use the atomic-reviewer subagent.

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。