Configuring CrewAI Crews and Agents

Configure Agent Parameters

Every agent requires three fields. The role defines the agent specialization and appears in the agent system prompt. Use specific, descriptive roles like "Senior Financial Analyst" rather than generic ones like "Analyst." More specific roles produce more focused, higher-quality outputs because the LLM has clearer context about what expertise to apply.

The goal establishes what the agent is trying to accomplish. Goals should be outcome-oriented: "Produce a comprehensive market analysis with specific data points and actionable recommendations" is more effective than "Analyze the market." The goal shapes the agent decision-making throughout its task execution and determines how the agent prioritizes different aspects of a complex task.

The backstory provides context that shapes how the agent approaches problems. Think of it as an extended system prompt that gives the agent a personality, knowledge base, and working style. A backstory like "You have 15 years of experience in financial markets and are known for identifying non-obvious trends in public data" produces different behavior than "You are a helpful analyst." The backstory is the most underutilized configuration field, and investing effort into crafting detailed backstories consistently improves output quality across all use cases.

Optional agent parameters include allow_delegation (default True, controls whether the agent can pass work to other agents), verbose (default False, enables detailed logging of agent reasoning), max_iter (maximum reasoning iterations before returning best result), max_rpm (rate limit for API calls per minute), and llm (specific model to use for this agent). Setting max_iter is important for cost control because some agents enter reasoning loops that consume tokens without making progress.

Define Task Specifications

Tasks require a description that tells the agent exactly what to do. Task descriptions are the highest-leverage optimization point in any CrewAI deployment. Specific, detailed descriptions with clear success criteria produce dramatically better results than vague directives. Include the desired output format, level of detail, specific data points to include, and any constraints or requirements.

The expected_output field describes what the task output should look like. This helps the agent understand the deliverable format and content expectations. "A bullet-point list of the top 5 competitors with revenue, employee count, and key differentiators" is more useful than "A summary of competitors."

The agent field assigns the task to a specific agent. In sequential processing, tasks execute in definition order. In hierarchical processing, the manager agent may reassign tasks based on its judgment of which agent is best suited.

For structured output, use output_pydantic to specify a Pydantic model that the output must conform to. This enforces type safety and consistent formatting, which is valuable when task outputs feed into downstream systems or other agents. The framework validates the output against the schema and retries if the output does not conform. This retry behavior means that Pydantic output adds reliability but also adds token cost when the agent initial attempt does not match the schema.

Optional task parameters include context (list of specific previous tasks to use as context, rather than all previous tasks), callback (function called on completion for side effects like logging or notifications), human_input (whether to pause and request human review before accepting the output), and async_execution (whether this task can run in parallel with other async tasks).

Select a Process Type

Sequential (default) executes tasks in order, passing each output to the next task as context. This is the most predictable and commonly used process type. Each agent receives the full output of the previous agent, creating a clear information flow through the workflow. Sequential processing is best for workflows where each step builds directly on the previous one, like research followed by analysis followed by report writing.

Hierarchical adds a manager agent that delegates tasks to workers based on their roles and capabilities. The manager decides the execution order, can reassign tasks if an agent produces poor results, and aggregates the final output. This process type is useful when the optimal task assignment is not known in advance or when tasks need dynamic coordination. The manager agent consumes additional tokens for its reasoning about task delegation, so hierarchical processing is more expensive than sequential for simple workflows.

Consensual (experimental) allows agents to vote on decisions collectively. Each agent processes the task independently and the results are combined through a voting mechanism. This is primarily useful for scenarios where multiple independent assessments improve decision quality, such as content moderation or risk evaluation. The token cost scales linearly with the number of voting agents, so this process type is the most expensive per decision.

Configure Crew-Level Settings

The crew configuration brings agents and tasks together and sets global execution parameters. Key settings include memory (True/False, enables all memory layers including short-term, long-term, entity, and contextual), verbose (crew-level logging that shows the full execution flow), max_rpm (global rate limit across all agents to prevent hitting provider limits), and full_output (whether to return all task outputs or only the final result).

The planning parameter enables an automatic planning step before execution, where the framework analyzes the tasks and creates an execution plan. This can improve results for complex workflows but adds latency and token cost for the planning step itself. Planning is most valuable for hierarchical crews with many tasks where the optimal execution order is not obvious.

The manager_llm parameter specifies which model the manager agent uses in hierarchical processing. Since the manager makes delegation decisions that affect the entire workflow, using a high-capability model for the manager while using cheaper models for worker agents is a common optimization pattern. The cost savings from using cheaper worker models often outweigh the higher cost of a premium manager model.

Memory configuration deserves special attention. When memory=True is set, CrewAI enables four memory layers: short-term memory (within the current execution), long-term memory (persisted across executions), entity memory (structured facts about people, companies, and concepts), and contextual memory (situation-specific information). Each layer adds token overhead as the framework injects relevant memories into agent prompts. For workflows where agents do not benefit from remembering previous executions, leaving memory disabled reduces token consumption and latency.

Choose YAML or Code Configuration

YAML configuration separates agent and task definitions into configuration files, keeping them distinct from Python code. This makes it easy for non-developers to modify agent behavior, adjust prompts, and change model assignments. YAML is the recommended approach for teams where product managers or domain experts need to tune agent behavior without touching Python code.

Code-first configuration defines everything in Python, which offers more flexibility for dynamic workflows. Agents and tasks can be created conditionally based on runtime information, configuration can be loaded from databases or APIs, and complex initialization logic can be embedded directly. Code-first is better for workflows where the agent configuration depends on dynamic inputs or where the number of agents and tasks varies between executions.

Both approaches can be mixed: use YAML for stable agent definitions and code for dynamic task creation or conditional agent configuration. The framework treats both identically at runtime, so the choice is purely about development workflow preference. Many teams start with YAML for simplicity and migrate individual components to code as their configuration needs become more dynamic.