design-agent

Define a specific role (e.g. "Senior Data Researcher" rather than "Researcher"), an outcome-focused goal with quality standards, and a backstory establishing expertise and working style. Keep task instructions out of the backstory — those belong in the task description.

Default to one agent. Add more only when work genuinely requires different tools, personas, LLMs, or guardrails. A single agent can call multiple tools sequentially in one kickoff, so splitting linear steps into separate agents multiplies token cost without quality gains.

Use Agent.kickoff() inside a Flow method when one agent does one job — the Flow owns sequencing and state. Use Crew.kickoff() only when a step genuinely benefits from multi-agent collaboration such as delegation or parallel specialists feeding one synthesis.

An agent with no tools will hallucinate when asked to search, fetch, or read files. Always assign tools for tasks requiring external data, but limit to 3-5 focused tools per agent since too many tools confuses tool selection.

Set function_calling_llm to a cheaper model so the main llm handles reasoning while the cheap model handles tool-calling mechanics. For planning mode, use a cheap model like claude-haiku for the planner while keeping a stronger model for execution.

Yes, define agents in an agents.yaml file with role, goal, and backstory keys, then load them in a @CrewBase class via agents_config. The Python method name must exactly match the YAML key or you will get a KeyError.