design-agent

CrewAI エージェント設計ガイド

適切な役割、目標、バックストーリー、ツール、設定で効果的なエージェントを設計する方法です。

2026-10-01 に crewai 1.15.23 に照らして検証済みです。 2026-10-01 に実際の LLM でライブテスト済みです。

正確な API 形式（インポート、デフォルト値、プロバイダー固有の追加設定、構造化出力）は check-crewai-api スキルに、ツールと MCP は connect-tools-and-mcp に記載されています。このスキルとそれらの内容が異なる場合は、そちらに従ってください。

---

80/20 の法則

労力の 80% をタスク設計に、20% をエージェント設計に費やしてください。 適切に設計されたタスクなら、単純なエージェントでも能力を発揮できます。しかし、どんなに優れたエージェントでも、曖昧で範囲の定まらないタスクを立て直すことはできません。まずタスクを適切に設計し（design-task スキルを参照）、その後でエージェントを調整してください。

---

0. エージェントは実際に何体必要ですか？

まずはエージェント 1 体を基本としてください。 作業が本当に分割され、次のような要件がある場合に限って追加します。

• 異なるツールや権限 — たとえば、一方のエージェントには Slack の書き込み権限があり、もう一方はドキュメントを読むだけです。
• LLM が明確に切り替える必要のある異なるペルソナ — 作家の語り口と研究者の語り口は異なります。
• 異なる LLM — 機械的な手順には低コストのモデルを、統合にはより高性能なモデルを使います。
• 異なるガードレールや出力スキーマ — エージェントを分けると、各段階の契約が明確になります。

ワークフローに複数の手順があるというだけで、エージェントを追加しないでください。 1 体のエージェントで、1 回の kickoff 内に複数のツールを順番に呼び出し（検索 → スクレイピング → 要約は 1 体のエージェントのループです）、1 回の応答で複数セクションからなる構造化出力を作成し、自身のツール使用ループを通じて反復できます。

コストの考え方： エージェントを 1 体追加するごとに、少なくとも LLM の kickoff が 1 回増え、コンテキストの引き継ぎも発生します。直線的な作業を同一ペルソナの複数エージェントに分割すると、トークンコストが増え、わずかな品質向上のために不安定さも増します。

アンチパターン

❌ 1 人の研究者が担当する作業に 3 体のエージェントを使う：

source_finder = Agent(role="Finds URLs via Firecrawl search", tools=[firecrawl_search])
scraper       = Agent(role="Scrapes URLs via Firecrawl scrape", tools=[firecrawl_scrape])
writer        = Agent(role="Writes the report")  # plus goal, backstory, llm

✅ 情報収集ループを担当する研究者と、その内容を統合するライター — ペルソナと LLM が本当に異なるため、エージェントは 2 体です：

researcher = Agent(role="Web Researcher", tools=[firecrawl_search, firecrawl_scrape], llm="anthropic/claude-haiku-4-5")
writer     = Agent(role="Technical Report Writer",                                    llm="anthropic/claude-sonnet-4-6")

❌ 文字列を要約して DM で送るために、apps=["slack"] を使う Summarizer エージェントと Slack Sender エージェントを用意する。 ✅ apps=["slack"] を使う Slack Reporter エージェントを 1 体にし、「冒頭に 2～3 文のエグゼクティブサマリーを書き、その後、要約に続けて本文全体を {recipient_email} に DM で送信する」というタスクを設定する。

目安： 2 体の「エージェント」が同じペルソナ、同じツール環境、同じ LLM を共有しているなら、それらは 1 体のエージェントに、より長いタスクの説明を与えたものです。

「エージェント 1 体で十分」と判断したら

Flow メソッド内で Agent.kickoff() を直接使ってください。Crew も Task の一連の設定も不要です。処理の順序と状態は Flow が管理し、各ステップではエージェントを 1 回 kickoff します（Flow の仕組みについては build-flow スキルを、ドキュメントについては https://docs.crewai.com/en/concepts/agents#direct-agent-interaction-with-kickoff を参照してください）。

@listen(previous_step)
def my_step(self):
    agent = Agent(role="…", goal="…", backstory="…", tools=[...], llm="anthropic/claude-haiku-4-5")
    result = agent.kickoff(
        f"Use this prior step's output: {self.state.prior_field}",
        response_format=MyPydanticModel,  # optional
    )
    self.state.my_field = result.pydantic  # or result.raw

Crew.kickoff() を使うのは、委任、階層的な管理、複数の専門エージェントの並列処理結果を統合するなど、複数エージェントの協業が本当に有効な場合、またはエージェントがクルーのタスク内でしか使えない機能、つまり ナレッジソース と max_execution_time を必要とする場合（セクション 2）に限ってください。

---

1. 役割・目標・バックストーリーのフレームワーク

すべてのエージェントには、何者か、何を望むか、なぜその役割に適しているかの 3 つが必要です。3 つすべてにある {placeholders} は、crew.kickoff(inputs={...}) から値が設定されます。

役割 — エージェントは何者か

役割は、エージェントの専門分野を定義します。一般的な表現ではなく、具体的にしてください。

悪い例	良い例
Researcher	{topic} を専門とするシニアデータリサーチャー
Writer	開発者向けの技術ブログライター
Analyst	規制遵守の専門知識を持つ金融リスクアナリスト

役割は、LLM の推論に直接影響します。同じタスクでも、「シニアデータリサーチャー」と「リサーチアシスタント」では異なる出力が生成されます。

目標 — エージェントが目指すもの

目標は、エージェント個別の目的です。品質基準を伴う、成果重視の内容にしてください。

悪い例	良い例
Do research	{topic}の最先端の進展を調査し、裏付けとなる証拠とともに上位5つのトレンドを特定する
Write content	複雑なトピックを技術に詳しくない読者にもわかりやすく説明する、出版可能な品質の技術記事を作成する
Analyze data	信頼度と推奨される軽減策を含む、実行可能なリスク評価を提示する

背景 — エージェントが適任である理由

背景では、専門知識、経験、価値観、仕事の進め方を定めます。エージェントの「性格プロンプト」です。

backstory: >
  You're a seasoned researcher with 15 years of experience in AI/ML.
  You're known for your ability to find obscure but relevant papers
  and synthesize complex findings into clear, actionable insights.
  You always cite your sources and flag uncertainty explicitly.

含める内容： 経験年数や専門性の深さ、特定分野の知識、仕事の進め方と価値観（「必ず出典を引用する」「簡潔な出力を好む」など）、エージェントが自らに課す品質基準。

含めない内容： 実装の詳細（ツール、モデル、設定）、タスク固有の指示（タスクの説明に記載します）、出力品質に影響しない性格特性。

---

2. エージェント設定リファレンス

Agent は、認識しないキーワード引数を黙って無視します。そのため、パラメーターのスペルを間違えたり削除したりしても、何も起こらず、エラーも発生しません。判断に迷った場合は、"name" in Agent.model_fields を確認してください。

Agent(
    role="...", goal="...", backstory="...",   # Required
    llm="anthropic/claude-haiku-4-5",          # See LLM Selection
    tools=[...],                               # Tool instances
    max_iter=25,             # Max reasoning iterations per task (default: 25)
    max_execution_time=300,  # Seconds, crew tasks only (default: None - no limit)
    max_rpm=10,              # Max LLM calls per minute for this agent (default: None)
    max_retry_limit=2,       # Retries when task execution errors (default: 2)
    allow_delegation=False,  # Default: False — agent works alone
    respect_context_window=True,  # Summarize and continue on overflow (default: True)
    inject_date=False,       # Put today's date in the prompt (default: False; format via date_format)
    verbose=False,           # Detailed execution logs (default: False)
)

実行制限（1.15.23 で測定）

制限	動作
max_iter	上限に達しても、例外は発生しません。エージェントにはただちに最終回答を出すよう指示され、実行は、手元にある情報で「成功」します。max_iter=1 の場合、4段階のツール手順は1段階だけ記録され、不完全な回答が返されました。
max_rpm	上限を超えた呼び出しは、次の1分間の時間枠までブロックされます。max_rpm=2 の場合、3回目の LLM 呼び出しは約2秒後ではなく、62秒後に開始しました。
max_execution_time	エージェントが Crew 内で Task を実行する場合にのみ適用されます。Agent.kickoff() はこれを無視します（制限を5秒に設定しても、所要時間15秒のツールは、17秒後に正常に完了しました）。クルー内でも、期限に達した時点で作業が停止するわけではありません。実行中のツールと LLM の呼び出しが完了した後、タスクは TimeoutError: Task '...' execution timed out after 5 seconds を発生させ（18.8秒後に発生）、完了した作業は破棄されます。

したがって、max_execution_time は遅い実行をエラーにしますが、ハングを止めるものではありません。実時間を制限するには、時間を費やす箇所でタイムアウトを設定してください。たとえば、LLM(model=..., timeout=60) やツール内部のタイムアウトを使うか、強制終了できるサブプロセスで kickoff を実行します。

max_iter の調整： デフォルトの25は余裕があり、ほとんどのタスクは3〜8回の反復で完了します。タスクの定義が明確な場合は、早めに失敗させるために10〜15に下げます。エージェントが上限に達し続ける場合は、タスクが曖昧すぎます（上限ではなく、タスクを修正してください）。上限に達しても例外は発生しないため、終了コードではなく出力を確認してください。

その他のスイッチ： respect_context_window=True の場合、プロバイダーからコンテキスト長の超過が報告されると、会話を要約して続行します。False の場合、実行は SystemExit: Context length exceeded ... で停止します。時間に左右されるタスク（調査、ニュース、スケジュール管理）では、inject_date=True を設定すると便利です。今日の日付を尋ねたところ、これを設定したエージェントは正しく答え、設定していないエージェントは UNKNOWN と回答しました。

ツール

• ツールなしのエージェントは、検索、取得、ファイル読み取りを求められるとデータを幻覚するため、外部データが必要なタスクには必ずツールを用意してください。
• 少数の用途を絞ったツールを優先してください。ツールが多すぎると、エージェントは混乱します。
• エージェントレベルのツールは、そのエージェントが実行するすべてのタスクで利用できます。Task(tools=[...]) は、そのタスクではエージェントレベルのツールを置き換えます。実際のテストでは、天気ツールを持つエージェントに人口ツールだけを指定したタスクを与えたところ、人口ツールだけを呼び出せました。
• 事前構築済みツールにはキーが必要です（SerperDevTool() には SERPER_API_KEY が必要です）。カスタムツール、実在する crewai_tools の名前、キャッシュ、MCP サーバーについては、connect-tools-and-mcp を参照してください。

LLM の選択

from crewai import LLM

Agent(..., llm="anthropic/claude-haiku-4-5")
Agent(..., llm=LLM(model="anthropic/claude-haiku-4-5", temperature=0.2, timeout=60))

• llm= を指定しない場合、エージェントは環境変数 MODEL、次に MODEL_NAME、次に OPENAI_MODEL_NAME を使用し、いずれも設定されていない場合は gpt-4.1-mini を使用します。これは OpenAI のモデルなので、OPENAI_API_KEY がないとキックオフに失敗します。
• core crewai に含まれているのは OpenAI のみです。anthropic/... には uv add "crewai[anthropic]"、gemini/... には crewai[google-genai]、ネイティブに対応していないプロバイダーには crewai[litellm] が必要です（完全な表は check-crewai-api を参照）。
• 定型的な処理を行うエージェントには、より低コストのモデルを指定してください。ツール呼び出し用の別モデルである function_calling_llm は、Agent と Crew の両方で非推奨です。代わりに、各エージェントの llm を設定してください。

コラボレーション

エージェントがほかの専門エージェントとクルーを組んでいる場合、サブタスクの引き継ぎが実際に役立つ場合、またはマネージャーが委任する階層型プロセスを使用する場合に限り、allow_delegation=True を設定してください。警告： 明確なタスク境界のない委任は、無限ループや反復の浪費につながります。

プランニング（計画して実行するモード）

PlanningConfig を指定すると、エージェントは最初に計画（ステップのリスト）を生成し、各ステップを個別のマルチターンループで実行します（max_step_iterations で上限を設定）。各結果を確認したうえで、続行、再計画、または早期終了します。

from crewai import Agent
from crewai.agent.planning_config import PlanningConfig

agent = Agent(
    role="…", goal="…", backstory="…", tools=[...],
    planning_config=PlanningConfig(reasoning_effort="medium"),  # most common
)

プランニングを無効にするには、planning_config を省略してください。planning=True は PlanningConfig(reasoning_effort="low", max_attempts=1) の省略形です。reasoning=True は非推奨（DeprecationWarning）です。代わりに planning_config を使用してください。

reasoning_effort	各ステップの後にプランナーが行うこと	選択する状況
"low"	ヒューリスティックを使ってステップを確認し（追加の LLM 呼び出しなし）、続行します。再計画も調整もしません。	計画の可視性（ToDo、観察結果）は必要だが、エージェントが直線的に計画に従うと信頼している場合。最速です。
"medium"（デフォルト）	LLM を呼び出してステップを観察し、失敗時のみ再計画します。	エージェントのツールが失敗する可能性（ネットワーク、exec、スクレイピング）があり、適切に復旧させたい場合。サンドボックス内のコーディング、調査、その他のツールを多用するループに適したデフォルトです。
"high"	観察したうえで、各ステップの後に早期終了、全面的な再計画、または計画の調整を行えます。	中間結果に応じてタスクの内容が変化する場合、または最大限の適応性が必要な場合。実行あたりの LLM 呼び出し回数が最も多くなります。

PlanningConfig(
    reasoning_effort="medium",
    observe_steps=None,      # None = LLM observation for medium/high, heuristic for low
    max_steps=20,            # cap on planned steps
    max_replans=3,           # full re-plans before finalizing
    max_attempts=None,       # refinement attempts during plan generation
    max_step_iterations=15,  # LLM turns per step
    step_timeout=None,       # wall-clock seconds per step
    system_prompt=None, plan_prompt=None, refine_prompt=None,  # custom prompts
    llm=None,                # separate (cheaper) LLM for planning; else agent.llm
)

有効にする場合： エージェントが自分でステップを選ぶ自律的なループで、失敗からの復旧が必要な場合に使います（書く → 実行する → 修正するコーディングエージェント、検索する → スクレイピングする → 見直す調査エージェントなど）。「この文字列を要約する」「この Slack の DM を投稿する」といった、単一ツールで目的が一つの呼び出しでは使用しないでください。

コスト： ある実測では、2 ステップのタスクにプランニングを追加すると、呼び出しが 3～7 回増え、回答が散文で返されました。有効にする前に、独自のタスクで測定してください。

コード実行

allow_code_execution と code_execution_mode は非推奨の無効な設定です（allow_code_execution=True は DeprecationWarning を出します）。また、CodeInterpreterTool は crewai_tools に存在しなくなりました。代わりに、E2BPythonTool や DaytonaPythonTool などのサンドボックスツールをエージェントに渡してください（connect-tools-and-mcp を参照）。

エージェントのガードレール

from typing import Any

def require_uppercase(result) -> tuple[bool, Any]:
    if result.raw != result.raw.upper():
        return (False, "Rewrite the whole answer in UPPERCASE letters only.")
    return (True, result.raw)

agent = Agent(..., guardrail=require_uppercase, guardrail_max_retries=3)  # default retries: 3
result = agent.kickoff("...")   # the agent guardrail runs here

ガードレールには文字列を指定することもでき、その場合は追加の LLM 呼び出しでチェックされます。1.15.23 のエージェントガードレールには、実際の LLM で確認した次の 2 つの制限があります。

• Agent.kickoff() でのみ実行されます。 同じエージェントが Crew 内で Task を実行する場合、エージェントガードレールは呼び出されません。
• crewai 1.15.23 では、エージェントレベルのガードレールの再試行時にフィードバックを含めず元のプロンプトを再送信し、上記の大文字チェックは 3 回とも失敗しました。 フィードバックが渡されるタスクレベルのガードレールを優先してください。再試行が尽きると、kickoff は ValueError: Agent's guardrail failed validation after N retries. Last error: ... を発生させます。

出力を単に拒否するのではなく修正させる必要がある場合は、ガードレールをタスクに設定します（Task(guardrail=..., guardrail_max_retries=...)）。エラーメッセージはそこでフィードバックされ、同じ大文字チェックは 2 回目の試行で通過しました。design-task と check-crewai-api を参照してください。

ナレッジソース

from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource

Agent(
    ...,
    knowledge_sources=[TextFileKnowledgeSource(file_paths=["company_handbook.txt"])],  # read from ./knowledge/
    embedder={"provider": "onnx"},   # local, no API key; omit it to use OpenAI embeddings
)

ナレッジソースは、RAG を介してエージェントにドメイン固有のデータを提供します。エージェントが大規模なドキュメント、ポリシー、データセットを参照する必要がある場合に使用します。知っておくべき点は 2 つあります。

• エージェントのナレッジが照会されるのは、エージェントが Crew 内でタスクを実行するときだけです。 Agent.kickoff() は knowledge_sources を無視しても何も通知しません。実際のテストでは、同じエージェントが kickoff() では「UNKNOWN」と回答し、1 タスクの crew では正しく回答しました。
• embedder= を指定しない場合、ナレッジでは OpenAI の埋め込みを使用します。OPENAI_API_KEY が設定されていないと、crew の kickoff 時にエージェントのナレッジで ValueError: Invalid Knowledge Configuration が発生します。crew レベルのナレッジでは Failed to upsert documents のみがログに記録され、ナレッジを使用せずに実行されます。

OpenAI を使わずに動作するエンベッダー、KnowledgeConfig、メモリ、ストレージパスについては、references/memory-and-knowledge.md を参照してください。

---

3. YAML 設定（推奨）

設定とコードを明確に分離するため、agents.yaml でエージェントを定義します。crewai create crew <name> --classic で YAML プロジェクトを作成します。--classic を指定しない場合、crewai create crew は対話型ウィザードを開始し、代わりに JSON プロジェクトを作成します。

researcher:
  role: >
    {topic} Senior Data Researcher
  goal: >
    Uncover cutting-edge developments in {topic}
    with supporting evidence and source citations
  backstory: >
    You're a seasoned researcher with 15 years of experience.
    Known for finding obscure but relevant sources and
    synthesizing complex findings into clear insights.
    You always cite your sources and flag uncertainty.
  # Optional overrides: llm: anthropic/claude-haiku-4-5, max_iter: 15, max_rpm: 10,
  # allow_delegation: false, verbose: true

次に、crew.py で接続します。

@CrewBase
class MyCrew:
    agents_config = "config/agents.yaml"
    tasks_config = "config/tasks.yaml"

    @agent
    def researcher(self) -> Agent:
        return Agent(config=self.agents_config["researcher"], tools=[SerperDevTool()])

重要： メソッド名（def researcher）は YAML のキー（researcher:）と一致させる必要があります。一致しない場合、KeyError が発生します（確認済み：KeyError: 'researcher'）。

実際の環境で確認済み：YAML で設定した llm と max_iter が適用され、ロール内の {topic} は kickoff 時に置き換えられ、ツールは Python でアタッチされます。ツール、ガードレール関数、Pydantic モデルは Python に記述し、YAML にはテキストとスカラー設定を記述してください。

---

4. Agent.kickoff() — エージェントを直接実行

crew のオーバーヘッドなしで、ツールと推論機能を備えたエージェントを 1 つ使用する場合は、Agent.kickoff() を使います。これは Flows で最も一般的なパターンです。エージェントのナレッジソースや max_execution_time は使用しません（セクション 2）。

from pydantic import BaseModel
from crewai import Agent

researcher = Agent(
    role="Senior Research Analyst",
    goal="Find comprehensive, factual information with source citations",
    backstory="Expert researcher known for thorough, evidence-based analysis.",
    tools=[...],
    llm="anthropic/claude-haiku-4-5",
)

result = researcher.kickoff("What are the latest developments in quantum computing?")
print(result.raw)             # str — the agent's full response
print(result.usage_metrics)   # dict: total_tokens, prompt_tokens, completion_tokens, ...

class ResearchFindings(BaseModel):
    key_trends: list[str]
    sources: list[str]
    confidence: float

result = researcher.kickoff("Research the latest AI agent frameworks", response_format=ResearchFindings)
print(result.pydantic.key_trends, result.pydantic.confidence)

result = await researcher.kickoff_async("...", response_format=ResearchFindings)  # async variant

注： Agent.kickoff() は LiteAgentOutput を返します。構造化出力には result.pydantic でアクセスしてください。これは、Pydantic オブジェクトを直接返す llm.call(messages, response_model=Model) とは異なります。Agent.kickoff(..., response_model=...) は TypeError になります。

ファイル入力には追加の依存関係が必要です。uv add "crewai[file-processing]" を実行し、次に from crewai_files import FileInput をインポートして、researcher.kickoff("Summarize this document", input_files={"document": FileInput(path="report.pdf")}) を実行します。追加の依存関係がない場合、インポートは ModuleNotFoundError: No module named 'crewai_files' で失敗します。

Agent.kickoff() と Crew.kickoff()： 各ステップが個別のエージェントで、Flow が順序を制御する場合（セクション 0 の構成。2 ステップの Flow として実環境で確認済み）は Agent.kickoff() を使用します。複数のエージェントが 1 つのステップ内で関連するタスクに協力する場合、またはエージェントがナレッジソースや max_execution_time を必要とする場合は Crew.kickoff() を使用します。

会話型 Flow のルートでのエージェント

会話型 Flow（from crewai.flow import ConversationState）では、Flow がチャットのライフサイクルとルート選択を担います。ルートハンドラー内でエージェントを呼び出し、調査、ドキュメント検索、アカウント操作、トリアージ、文書の作成、エスカレーション準備など、範囲を限定したツールベースの作業を実行します。仕組み（handle_turn、ConversationConfig、テスト済みの例）については、build-flow スキルの conversational-flows リファレンスを参照してください。

設計上の留意点：

• 会話型の Flow に、セッション ID、メッセージ履歴、ルーティング、トレースの確定、承認を担当させます。
• 各エージェントの範囲は、ルート 1 つ、ツールの対象範囲 1 つ、仕事 1 つに限定します。
• 正規のチャット履歴に含めない作業用の結果には、self.append_agent_result(name, result, visibility="private") を使用します。
• ハンドラーからユーザーに表示する返信を返すか（または self.append_assistant_message(reply) を呼び出して）、次のターンでアシスタントのコンテキストが維持されるようにします。
• あらゆるツールを備えた「チャットエージェント」は作らないでください。まずルーティングし、選択されたルートに合わせて範囲を絞ったエージェントを呼び出します。

5. 専門特化型エージェントと汎用型エージェント

このセクションは、複数のエージェントが本当に必要だと判断した後に適用してください（セクション 0）。エージェントが 1 つの場合、考えるべきなのはそのエージェントの設計方法だけです。

複数のエージェントが必要な場合は、専門特化型を優先してください。 1 つのことをうまくこなすエージェントは、多くのことをそこそこにこなすエージェントより優れています。深いドメイン知識が必要な場合、スピードより品質が重要な場合、または集中的な専門知識が役立つほどタスクが複雑な場合は、専門特化型エージェントを使ってください。汎用型エージェントは、明確な指示がある単純なタスク、後で専門特化する予定のプロトタイピング、そして実際に複数のドメインに等しくまたがるタスクであれば問題ありません。

1 つの「コンテンツライター」エージェントを作る代わりに、（技術的な正確さとコード例を担当する）technical_writer、（説得力があり、対象読者を重視したコピーを担当する）copywriter、（文法、一貫性、スタイルガイドを担当する）editorを作成します。それぞれに、狭い役割、具体的な目標、その専門性を強化するバックストーリーを設定します。

---

6. エージェントの連携パターン

逐次型（デフォルト）： Researcher → Writer → Editor。エージェントが順番に作業し、それぞれが前のエージェントの出力をコンテキストとして受け取ります。各ステップが前のステップを土台にする直線的なパイプラインに最適です。

階層型： マネージャーエージェントが作業を委任して検証し、タスクの割り当てを動的に行います。中間結果に応じて割り当てが変わる複雑なワークフローに最適です。

Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process=Process.hierarchical,
    manager_llm="anthropic/claude-haiku-4-5",   # or manager_agent=...; one is required
)

manager_llmもmanager_agentも指定せずにCrew(...)を呼び出すと、ValidationErrorが発生します。

エージェント間の委任： allow_delegation=Trueを設定すると、エージェントに、他のクルーメンバーの名前が設定されたDelegate work to coworkerとAsk question to coworkerという 2 つのツールが与えられます。実際に動作を確認したところ、Writerから文を取得するよう依頼すると、リードエージェントはask_question_to_coworkerを呼び出し、Writerの回答を返しました。

---

7. エージェント設計でよくある間違い

間違い	影響	修正方法
「Assistant」のような汎用的な役割	エージェントの出力が焦点を欠き、内容が浅くなる	「Senior Financial Analyst」のように、具体的な専門性を指定する
データ収集タスクにツールがない	エージェントが検索せずにデータを幻覚する	外部情報が必要なタスクには、必ずツールを追加する
ツールが多すぎる（10 個以上）	エージェントがツールの選択に迷う	エージェントごとに、関連するツールを 3～5 個に絞る
バックストーリーにタスクの指示を詰め込む	エージェントが個性とタスクの実行を混同する	バックストーリーにはエージェントが誰かだけを書き、タスクの詳細はタスクに記述する
デフォルトでallow_delegation=Trueにする	エージェントが些細な作業を委任し、反復を無駄にする	委任が本当に役立つ場合にのみ有効にする
単純なタスクに対してmax_iterが大きすぎる	エージェントが曖昧なタスクで不必要にループする	max_iterを下げ、代わりにタスクの説明を改善する
重要な出力にガードレールがない	不適切な出力がチェックされずに通過する	本番システムに渡す出力にはTaskのガードレールを追加する
Crewで使うエージェントにガードレールを設定する	ガードレールが実行されない	ガードレールはTaskに設定する
ハングを止めるためにmax_execution_timeを信頼する	遅い呼び出しが返った後にしか例外が発生せず、Agent.kickoff()はこれを無視する	LLMとツールにタイムアウトを設定する
Agent.kickoff()経由で実行するエージェントにナレッジソースを設定する	ナレッジが使われずに終わる	クルーのタスクとして実行するか、事実をプロンプトに記述する
llm=を指定せず、OpenAIのキーも設定しない	Kickoffに失敗する：デフォルトはOpenAIのgpt-4.1-mini	llm=（または環境変数MODEL）を設定し、プロバイダーの追加パッケージをインストールする
単純なタスクに計画機能を使う	LLMの呼び出しが 2～3 倍になり、回答の質が下がることもある	自由度の高いツールループに限って計画機能を有効にする

---

8. エージェント設計チェックリスト

エージェントをデプロイする前に、次の項目を確認してください。

• 役割が具体的で、対象分野に特化している（「アシスタント」や「ヘルパー」ではない）
• 目標に、望ましい成果と品質基準の両方が含まれている
• バックストーリーで専門知識と作業スタイルが示されている
• 外部データが必要なタスクにはツールが割り当てられている
• ツールを過剰に割り当てない — エージェントあたり最大3～5個
• max_iterが想定されるタスクの複雑さに合わせて調整されている（単純なタスクは10～15、複雑なタスクは20～25）
• 時間がかかる処理にはタイムアウトが設定されている（LLMのtimeout、ツールのタイムアウト）。max_execution_timeはクルーのタスクに対する最終的な安全策としてのみ使用する
• 重要な出力に対するガードレールがタスクに設定されている
• LLMが明示的に設定され、タスクの複雑さに適合し、プロバイダーの追加パッケージがインストールされている
• ナレッジに明示的なembedderが設定され、エージェントがクルー内で実行される
• 本当に必要な場合を除き、委任が無効になっている

---

参考資料

各トピックの詳細については、以下をご覧ください。

• カスタムツール — @toolデコレーターとBaseToolサブクラスを使った独自ツールの作成
• メモリとナレッジ - メモリ、ナレッジソース、OpenAIなしで動作する埋め込みモデル、ストレージ、スコープ

関連するスキル：

• check-crewai-api - 現在のインポート、パラメーター、デフォルト値、プロバイダーの追加パッケージ
• connect-tools-and-mcp - カスタムツール、実際のcrewai_tools名、キャッシュ、MCP サーバー
• build-flow - Flowの状態、ルーティング、永続化、会話型フロー
• getting-started - プロジェクトのひな形作成、適切な抽象化の選択
• design-task — タスクの説明とexpected_outputに関するベストプラクティス、ガードレール、構造化出力、依存関係
• test-crewai-project - スタブLLMを使った、オフラインでのエージェントとクルーのテスト
• ask-docs - これらのスキルで扱っていない質問について、最新のCrewAIドキュメントに問い合わせる