DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Classes / Agent
Class core

Agent: Reference Guide

By DevShelfHub

An autonomous worker defined by role, goal, backstory, tools, and LLM — the basic unit of work in a Crew.

See the CrewAI API reference index, CrewAI introduction, and core concepts for surrounding context.

What is Agent?

Agent is CrewAI's primary abstraction for a model-backed worker with a stable identity. The tuple of role, goal, and backstory is not cosmetic — it is folded into the system and task prompts so the same underlying LLM behaves differently when you swap those strings. Tools, knowledge_sources, memory flags, and multimodal settings extend that identity with capabilities, while max_iter, max_rpm, max_execution_time, and respect_context_window bound cost and runtime. Delegation (allow_delegation) lets an agent hand work to peers when the crew runs in hierarchical process mode.

CrewAI agents also participate in observability and safety: verbose and step_callback expose execution traces, cache controls whether tool results are memoized within a kickoff, and template overrides (system_template, prompt_template, response_template) let you align prompts with internal standards without forking the framework. Reasoning and max_reasoning_attempts add an inner reflection loop distinct from crew-level planning — useful when a single task needs deliberate tool use before answering.

Version-to-version, the constructor surface has grown with multimodal, reasoning, and security-adjacent options. When upgrading CrewAI, diff your Agent(...) calls against release notes: defaults like memory=True or cache=True affect cost and determinism. For one-shot calls without tasks, LiteAgent is the lighter entry point; Agent remains the right choice whenever Crew, Task, or Flow orchestration is in play.

When to Use

Whenever you have a distinct role in a workflow (Researcher, Writer, Reviewer, …) inside a Crew, Flow, or YAML-driven @CrewBase project.

Use Cases

  • • Research
  • • Writing
  • • Code review
  • • Customer support triage

Key Features

  • ✓ Role/goal/backstory identity
  • ✓ Tools & memory
  • ✓ Delegation
  • ✓ Multimodal mode
  • ✓ Reasoning loop

When NOT to Use

For one-shot LLM calls with no task orchestration — use LiteAgent or call LLM directly.

Notes

Tool budget and prompt size

Every tool description is injected into the model context. Large tool sets increase latency, cost, and hallucinated tool picks. Prefer narrow tool lists per agent, use MCP filters, and split crews so specialists do not see irrelevant tools.

max_iter vs reasoning

max_iter caps the outer agent loop for a task, while reasoning=True adds an inner reflection loop. Turning both on without profiling can multiply LLM calls. Start with defaults, measure token_usage on CrewOutput, then tune.

Caching semantics

cache=True deduplicates identical tool inputs within a kickoff. It speeds up repeated lookups but can hide stale external state. Disable caching for agents that must always see fresh APIs or rapidly changing databases.

Delegation surprises

allow_delegation=True only makes sense when another agent can receive the handoff — typically in hierarchical Process with a manager. In sequential crews without a manager path, flipping the flag on silently does little or produces confusing traces.

Import

python 
from crewai import Agent

Key Parameters

Parameter Type Default Purpose
role str — Short identity string.
goal str — What the agent is trying to accomplish.
backstory str — Context/persona prefix in the system prompt.
llm LLM | str | None None Model used by this agent.
tools list[BaseTool] [] Tools the agent can call.
memory bool True Enable per-agent memory.
verbose bool False Print step traces to stdout.
allow_delegation bool False Permit handing off to other agents.
max_iter int 20 Max reasoning iterations per task.
max_rpm int | None None Per-agent rate limit (requests / minute).
max_execution_time int | None None Per-task timeout in seconds.
max_retry_limit int 2 Retries on transient failures.
respect_context_window bool True Auto-trim to model's context.
cache bool True Cache tool results within a kickoff.
system_template str | None None Override system-prompt template.
prompt_template str | None None Override prompt template.
response_template str | None None Override response template.
allow_code_execution bool | None None Allow @code-execution tool.
code_execution_mode Literal['safe','unsafe'] 'safe' Sandbox vs unsafe execution.
function_calling_llm Any | None None Separate LLM for tool/function calls.
knowledge_sources list[BaseKnowledgeSource] | None None Per-agent knowledge.
embedder dict | None None Embedder config dict.
multimodal bool False Enable image/audio handling tools.
reasoning bool False Enable per-agent reasoning loop.
max_reasoning_attempts int | None None Cap reasoning iterations.
step_callback Callable | None None Per-step callback for tracing.

Code Examples

Minimal researcher with search

python 
from crewai import Agent
from crewai_tools import SerperDevTool

researcher = Agent(
    role='Researcher',
    goal='Find authoritative sources on {topic}',
    backstory='You cite primary sources and flag uncertainty.',
    tools=[SerperDevTool()],
    verbose=True,
)

Cap iterations and wall-clock

python 
from crewai import Agent

writer = Agent(
    role='Writer',
    goal='Draft a concise article',
    backstory='You edit for clarity.',
    max_iter=12,
    max_execution_time=120,
    respect_context_window=True,
)

Explicit LLM instance with tool-calling split

python 
from crewai import Agent, LLM

planner_llm = LLM(model='openai/gpt-4o-mini', temperature=0.2)
tool_llm = LLM(model='openai/gpt-4o', temperature=0.0)

agent = Agent(
    role='Analyst',
    goal='Answer with numbers when possible',
    backstory='You prefer tables over prose.',
    llm=planner_llm,
    function_calling_llm=tool_llm,
)

Common Mistakes

❌ Generic role like 'Helper' or 'Agent'

✅ Specific role: 'B2B Lead Researcher in fintech'.

❌ Attaching every built-in tool 'just in case'

✅ Give each agent the smallest viable tool surface for its goal.

Agent FAQ

What is Agent in CrewAI?

An autonomous worker defined by role, goal, backstory, tools, and LLM — the basic unit of work in a Crew. Agent is CrewAI's primary abstraction for a model-backed worker with a stable identity. The tuple of role, goal, and backstory is not cosmetic — it is folded into the system and task prompts so the same underlying LLM behaves differently when you swap those strings. Tools, knowledge_sources, memory flags, and multimodal settings extend that identity with capabilities, while max_iter, max_rpm, max_execution_time, and respect_context_window bound cost and runtime. Delegation (a…

Which package defines the CrewAI class Agent?

DevShelfHub maps Agent to Python module crewai (package path crewai in this reference). Pin your installed crewai version and match imports to the snippet on this page.

When should I use Agent?

Whenever you have a distinct role in a workflow (Researcher, Writer, Reviewer, …) inside a Crew, Flow, or YAML-driven @CrewBase project.

When should I avoid using Agent?

For one-shot LLM calls with no task orchestration — use LiteAgent or call LLM directly.

How do I import Agent in Python?

from crewai import Agent

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search 58 classes, 30 methods, and 16 decorators, each with runnable examples, parameters, common mistakes, and cross-links.