DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Decorators / @agent
Decorator crewai.project

@agent: Reference Guide

By DevShelfHub

Marks a CrewBase method whose return value is an Agent — enables declarative agent wiring from YAML.

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

What is @agent?

Inside a class decorated with @CrewBase, methods tagged with @agent are auto-discovered and registered so the framework can build Agent instances without you manually listing constructors in main.py. Each method usually reads self.agents_config (loaded from config/agents.yaml) and returns Agent(config=...), which keeps prompts, tools, and model settings co-located with the Python that wires dependencies between agents.

Call sites use zero-argument ergonomics: self.researcher() returns a cached Agent for the lifetime of the CrewBase instance, which prevents accidental re-instantiation on every task hop and mirrors how the CLI scaffold expects crews to behave. You can still compose programmatically — combine YAML for static personas with inline kwargs for secrets that should never hit disk.

Testing benefits are real: swap agents_config to a fixture path, patch environment variables, or inject LiteAgent-backed doubles without rewriting task graphs. When you outgrow YAML, migrate individual @agent methods to pure Python Agent(...) factories while keeping the decorator so @task methods keep working.

When to Use

Whenever you build a crew with the @CrewBase pattern. Avoid manual Agent(...) lists in the same class.

Use Cases

  • • YAML-driven crews
  • • Reusable agent factories
  • • Project scaffolds from `crewai create crew`

Key Features

  • ✓ Auto-discovery
  • ✓ Caches instance per call
  • ✓ Works with agents.yaml
  • ✓ Composable with @task/@crew

When NOT to Use

One-off scripts where YAML overhead isn't worth it — use a plain Agent() literal there.

Notes

Config merge order

YAML supplies the baseline persona; Python kwargs on Agent() win for tools, LLM overrides, and secrets. Document the merge so teammates know which file to edit.

Caching semantics

Repeated self.researcher() calls reuse the same object — great for performance but surprising if you mutate the Agent after creation. Treat agents as immutable after wiring.

Import-time side effects

Avoid network calls inside @agent bodies during module import. Lazy clients belong in @before_kickoff or inside tools so cold starts stay fast.

Import

python 
from crewai.project import agent

How to Apply

python 
@agent
def researcher(self) -> Agent:
    return Agent(config=self.agents_config['researcher'])

What It Enables

  • ✓ Declarative agents
  • ✓ Configuration-driven crews
  • ✓ Cleaner test fixtures

Code Examples

Researcher agent from YAML

python 
@agent
def researcher(self) -> Agent:
    return Agent(config=self.agents_config['researcher'])

Specialist with inline tools

python 
@agent
def analyst(self) -> Agent:
    base = self.agents_config['analyst']
    return Agent(
        config=base,
        tools=[lookup_tool, metrics_tool],
        verbose=True,
    )

Model override for one persona

python 
@agent
def reviewer(self) -> Agent:
    cfg = dict(self.agents_config['reviewer'])
    cfg['llm'] = 'openai/gpt-4o-mini'
    return Agent(config=cfg)

Integration Patterns

Inside @CrewBase class
Referenced from @task methods via self.researcher()

Common Mistakes

❌ Calling self.researcher inside __init__ before @CrewBase has wired the registry

✅ Defer access to inside @task / @crew methods that run after registration.

Related: Task class reference, Agent class reference, and the first Crew tutorial.

@agent FAQ

What is @agent in CrewAI?

Marks a CrewBase method whose return value is an Agent — enables declarative agent wiring from YAML. Inside a class decorated with @CrewBase, methods tagged with @agent are auto-discovered and registered so the framework can build Agent instances without you manually listing constructors in main.py. Each method usually reads self.agents_config (loaded from config/agents.yaml) and returns Agent(config=...), which keeps prompts, tools, and model settings co-located with the Python that wires dependencies between agents. Call sites use zero-argument ergonomics: self.researcher…

Which module defines the CrewAI decorator @agent?

DevShelfHub maps @agent to Python module crewai.project. Pin your installed crewai version and match imports to the import snippet on this page.

When should I use @agent?

Whenever you build a crew with the @CrewBase pattern. Avoid manual Agent(...) lists in the same class.

When should I avoid @agent?

One-off scripts where YAML overhead isn't worth it — use a plain Agent() literal there.

How do I apply @agent in Python?

@agent def researcher(self) -> Agent: return Agent(config=self.agents_config['researcher'])

Where can I explore more CrewAI API reference pages?

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