Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
replace old .cursorrules with AGENTS.md (#4451)
Mike Plachta2882df5dafbe
diff --git a/.cursorrules b/.cursorrulesdeleted file mode 100644index 42ef136ae..000000000--- a/.cursorrules+++ /dev/null@@ -1,1429 +0,0 @@-# CrewAI Development Rules-# Comprehensive best practices for developing with the CrewAI library, covering code organization, performance, security, testing, and common patterns. Based on actual CrewAI codebase analysis for accuracy.--## General Best Practices:-- Leverage structured responses from LLM calls using Pydantic BaseModel for output validation.-- Use the @CrewBase decorator pattern with @agent, @task, and @crew decorators for proper organization.-- Regularly validate outputs from agents and tasks using built-in guardrails or custom validation.-- Use UV for dependency management (CrewAI's standard) with pyproject.toml configuration.-- Python version requirements: 3.10 to 3.14 (as per CrewAI's pyproject.toml).-- Prefer declarative YAML configuration for agents and tasks over hardcoded definitions.--## Code Organization and Structure:-- **Standard CrewAI Project Structure** (from CLI templates):- - `project_name/` (Root directory)- - `.env` (Environment variables - never commit API keys)- - `pyproject.toml` (UV-based dependency management)- - `knowledge/` (Knowledge base files)- - `src/project_name/`- - `__init__.py`- - `main.py` (Entry point)- - `crew.py` (Crew orchestration with @CrewBase decorator)- - `config/`- - `agents.yaml` (Agent definitions)- - `tasks.yaml` (Task definitions)- - `tools/`- - `custom_tool.py` (Custom agent tools)- - `__init__.py`-- **File Naming Conventions**:- - Use descriptive, lowercase names with underscores (e.g., `research_agent.py`).- - Pydantic models: singular names (e.g., `article_summary.py` with class `ArticleSummary`).- - Tests: mirror source file name with `_test` suffix (e.g., `crew_test.py`).-- **CrewAI Class Architecture**:- - Use @CrewBase decorator for main crew class.- - Define agents with @agent decorator returning Agent instances.- - Define tasks with @task decorator returning Task instances.- - Define crew orchestration with @crew decorator returning Crew instance.- - Access configuration via `self.agents_config` and `self.tasks_config`.--## Memory System Patterns:-- **Memory Types** (all supported by CrewAI):- - Short-term memory: ChromaDB with RAG for current context- - Long-term memory: SQLite for task results across sessions- - Entity memory: RAG to track entities (people, places, concepts)- - External memory: Mem0 integration for advanced memory features-- **Memory Configuration**:- - Enable basic memory: `Crew(..., memory=True)`- - Custom storage location: Set `CREWAI_STORAGE_DIR` environment variable- - Memory is stored in platform-specific directories via `appdirs` by default-- **Memory Usage**:- - Memory is automatically managed by agents during task execution- - Access via agent's memory attribute for custom implementations- - Use metadata for categorizing and filtering memory entries--## Pydantic Integration Patterns:-- **Structured Outputs**:- - Use `output_pydantic` in Task definitions for structured results- - Use `output_json` for JSON dictionary outputs- - Cannot use both output_pydantic and output_json simultaneously-- **Task Output Handling**:- - TaskOutput contains raw, pydantic, and json_dict attributes- - CrewOutput aggregates all task outputs with token usage metrics- - Use model_validate_json for Pydantic model validation-- **Custom Models**:- - Inherit from BaseModel for all data structures- - Use Field descriptions for LLM understanding- - Implement model_validator for custom validation logic--## YAML Configuration Best Practices:-- **agents.yaml Structure**:- ```yaml- agent_name:- role: "Clear, specific role description"- goal: "Specific goal statement"- backstory: "Detailed background for context"- # Optional: tools, llm, memory, etc.- ```-- **tasks.yaml Structure**:- ```yaml- task_name:- description: "Detailed task description with context"- expected_output: "Clear output format specification"- agent: agent_name # Reference to agent in agents.yaml- # Optional: context, tools, output_file, etc.- ```-- **Configuration Access**:- - Use `self.agents_config['agent_name']` in @agent methods- - Use `self.tasks_config['task_name']` in @task methods- - Support for dynamic configuration via placeholders like {topic}--## Tools and Integration Patterns:-- **Custom Tools**:- - Inherit from BaseTool for custom tool implementation- - Use @tool decorator for simple tool definitions- - Implement proper error handling and input validation-- **Tool Integration**:- - Add tools to agents via tools parameter in Agent constructor- - Tools are automatically inherited by tasks from their assigned agents- - Use structured tool outputs for better LLM understanding--## Performance Considerations:-- **LLM Optimization**:- - Use task context to pass information between sequential tasks- - Implement output caching to avoid redundant LLM calls- - Configure appropriate LLM models per agent for cost/performance balance-- **Memory Management**:- - Be mindful of memory storage growth in long-running applications- - Use score_threshold in memory search to filter relevant results- - Implement periodic memory cleanup if needed-- **Async Operations**:- - Use execute_sync for synchronous task execution- - Consider async patterns for I/O-bound operations in custom tools--## Security Best Practices:-- **API Key Management**:- - Always use .env files for API keys and sensitive configuration- - Never commit API keys to version control- - Use environment variables in production deployments-- **Input Validation**:- - Validate all inputs using Pydantic models where possible- - Implement guardrails for task output validation- - Use field_validator for custom validation logic-- **Tool Security**:- - Implement proper access controls in custom tools- - Validate tool inputs and outputs- - Follow principle of least privilege for tool permissions--## Testing Approaches:-- **Unit Testing**:- - Test individual agents, tasks, and tools in isolation- - Use mocking for external dependencies (LLMs, APIs)- - Test configuration loading and validation-- **Integration Testing**:- - Test crew execution end-to-end with realistic scenarios- - Verify memory persistence across crew runs- - Test tool integration and data flow between tasks-- **Test Organization**:- - Follow CrewAI's test structure: separate test files for each component- - Use pytest fixtures for common test setup- - Mock LLM responses for consistent, fast tests--## Common CrewAI Patterns and Anti-patterns:-- **Recommended Patterns**:- - Use sequential Process for dependent tasks, hierarchical for manager delegation- - Implement task context for data flow between tasks- - Use output_file for persistent task results- - Leverage crew callbacks with @before_kickoff and @after_kickoff decorators-- **Anti-patterns to Avoid**:- - Don't hardcode agent configurations in Python code (use YAML)- - Don't create circular task dependencies- - Don't ignore task execution failures without proper error handling- - Don't overload single agents with too many diverse tools-- **Error Handling**:- - Implement task-level guardrails for output validation- - Use try-catch blocks in custom tools- - Set appropriate max_retries for tasks prone to failures- - Log errors with sufficient context for debugging--## Development Workflow:-- **UV Commands**:- - `crewai create crew <name>` - Create new crew project- - `crewai install` - Install dependencies via UV- - `crewai run` - Execute the crew- - `uv sync` - Sync dependencies- - `uv add <package>` - Add new dependencies-- **Project Setup**:- - Use CrewAI CLI for project scaffolding- - Follow the standard directory structure- - Configure agents and tasks in YAML before implementing crew logic-- **Development Tools**:- - Use UV for dependency management (CrewAI standard)- - Configure pre-commit hooks for code quality- - Use pytest for testing with CrewAI's testing patterns--## Deployment and Production:-- **Environment Configuration**:- - Set CREWAI_STORAGE_DIR for controlled memory storage location- - Use proper logging configuration for production monitoring- - Configure appropriate LLM providers and rate limits-- **Containerization**:- - Include knowledge and config directories in Docker images- - Mount memory storage as persistent volumes if needed- - Set proper environment variables for API keys and configuration-- **Monitoring**:- - Monitor token usage via CrewOutput.token_usage- - Track task execution times and success rates- - Implement health checks for long-running crew services--## CrewAI Flow Patterns and Best Practices--### Flow Architecture and Structure-- **Use Flow class** for complex multi-step workflows that go beyond simple crew orchestration-- **Combine Flows with Crews** to create sophisticated AI automation pipelines-- **Leverage state management** to share data between flow methods-- **Event-driven design** allows for dynamic and responsive workflow execution--### Flow Decorators and Control Flow-- **@start()**: Mark entry points for flow execution (can have multiple start methods)-- **@listen()**: Create method dependencies and execution chains-- **@router()**: Implement conditional branching based on method outputs-- **or_()** and **and_()**: Combine multiple trigger conditions for complex workflows--### Flow State Management Patterns-```python-# Structured state with Pydantic (recommended for complex workflows)-class WorkflowState(BaseModel):- task_results: List[str] = []- current_step: str = "initialize"- user_preferences: dict = {}- completion_status: bool = False--class MyFlow(Flow[WorkflowState]):- @start()- def initialize(self):- self.state.current_step = "processing"- # State automatically gets unique UUID in self.state.id--# Unstructured state (good for simple workflows)-class SimpleFlow(Flow):- @start()- def begin(self):- self.state["counter"] = 0- self.state["results"] = []- # Auto-generated ID available in self.state["id"]-```--### Flow Method Patterns-```python-# Basic sequential flow-@start()-def step_one(self):- return "data from step one"--@listen(step_one)-def step_two(self, data_from_step_one):- return f"processed: {data_from_step_one}"--# Parallel execution with convergence-@start()-def task_a(self):- return "result_a"--@start()-def task_b(self):- return "result_b"--@listen(and_(task_a, task_b))-def combine_results(self):- # Waits for both task_a AND task_b to complete- return f"combined: {self.state}"--# Conditional routing-@router(step_one)-def decision_point(self):- if some_condition:- return "success_path"- return "failure_path"--@listen("success_path")-def handle_success(self):- # Handle success case- pass--@listen("failure_path")-def handle_failure(self):- # Handle failure case- pass--# OR condition listening-@listen(or_(task_a, task_b))-def process_any_result(self, result):- # Triggers when EITHER task_a OR task_b completes- return f"got result: {result}"-```--### Flow Persistence Patterns-```python-# Class-level persistence (all methods persisted)-@persist(verbose=True)-class PersistentFlow(Flow[MyState]):- @start()- def initialize(self):- self.state.counter += 1--# Method-level persistence (selective)-class SelectiveFlow(Flow):- @persist- @start()- def critical_step(self):- # Only this method's state is persisted- self.state["important_data"] = "value"-- @start()- def temporary_step(self):- # This method's state is not persisted- pass-```--### Flow Execution Patterns-```python-# Synchronous execution-flow = MyFlow()-result = flow.kickoff()-final_state = flow.state--# Asynchronous execution-async def run_async_flow():- flow = MyFlow()- result = await flow.kickoff_async()- return result--# Flow with input parameters-flow = MyFlow()-result = flow.kickoff(inputs={"user_id": "123", "task": "research"})--# Flow plotting and visualization-flow.plot("workflow_diagram") # Generates HTML visualization-```--### Advanced Flow Patterns-```python-# Cyclic/Loop patterns-class CyclicFlow(Flow):- max_iterations = 5- current_iteration = 0-- @start("loop")- def process_iteration(self):- if self.current_iteration >= self.max_iterations:- return- # Process current iteration- self.current_iteration += 1-- @router(process_iteration)- def check_continue(self):- if self.current_iteration < self.max_iterations:- return "loop" # Continue cycling- return "complete"-- @listen("complete")- def finalize(self):- # Final processing- pass--# Complex multi-router pattern-@router(analyze_data)-def primary_router(self):- # Returns multiple possible paths based on analysis- if self.state.confidence > 0.8:- return "high_confidence"- elif self.state.errors_found:- return "error_handling"- return "manual_review"--@router("high_confidence")-def secondary_router(self):- # Further routing based on high confidence results- return "automated_processing"--# Exception handling in flows-@start()-def risky_operation(self):- try:- # Some operation that might fail- result = dangerous_function()- self.state["success"] = True- return result- except Exception as e:- self.state["error"] = str(e)- self.state["success"] = False- return None--@listen(risky_operation)-def handle_result(self, result):- if self.state.get("success", False):- # Handle success case- pass- else:- # Handle error case- error = self.state.get("error")- # Implement error recovery logic-```--### Flow Integration with Crews-```python-# Combining Flows with Crews for complex workflows-class CrewOrchestrationFlow(Flow[WorkflowState]):- @start()- def research_phase(self):- research_crew = ResearchCrew()- result = research_crew.crew().kickoff(inputs={"topic": self.state.research_topic})- self.state.research_results = result.raw- return result-- @listen(research_phase)- def analysis_phase(self, research_results):- analysis_crew = AnalysisCrew()- result = analysis_crew.crew().kickoff(inputs={- "data": self.state.research_results,- "focus": self.state.analysis_focus- })- self.state.analysis_results = result.raw- return result-- @router(analysis_phase)- def decide_next_action(self):- if self.state.analysis_results.confidence > 0.7:- return "generate_report"- return "additional_research"-- @listen("generate_report")- def final_report(self):- reporting_crew = ReportingCrew()- return reporting_crew.crew().kickoff(inputs={- "research": self.state.research_results,- "analysis": self.state.analysis_results- })-```--### Flow Best Practices-- **State Management**: Use structured state (Pydantic) for complex workflows, unstructured for simple ones-- **Method Design**: Keep flow methods focused and single-purpose-- **Error Handling**: Implement proper exception handling and error recovery paths-- **State Persistence**: Use @persist for critical workflows that need recovery capability-- **Flow Visualization**: Use flow.plot() to understand and debug complex workflow structures-- **Async Support**: Leverage async methods for I/O-bound operations within flows-- **Resource Management**: Be mindful of state size and memory usage in long-running flows-- **Testing Flows**: Test individual methods and overall flow execution patterns-- **Event Monitoring**: Use CrewAI event system to monitor flow execution and performance--### Flow Anti-patterns to Avoid-- **Don't create overly complex flows** with too many branches and conditions-- **Don't store large objects** in state that could cause memory issues-- **Don't ignore error handling** in flow methods-- **Don't create circular dependencies** between flow methods-- **Don't mix synchronous and asynchronous** patterns inconsistently-- **Don't overuse routers** when simple linear flow would suffice-- **Don't forget to handle edge cases** in router logic--## CrewAI Version Compatibility:-- Stay updated with CrewAI releases for new features and bug fixes-- Test crew functionality when upgrading CrewAI versions-- Use version constraints in pyproject.toml (e.g., "crewai[tools]>=0.140.0,<1.0.0")-- Monitor deprecation warnings for future compatibility--## Code Examples and Implementation Patterns--### Complete Crew Implementation Example:-```python-from crewai import Agent, Crew, Process, Task-from crewai.project import CrewBase, agent, crew, task, before_kickoff, after_kickoff-from crewai_tools import SerperDevTool, FileReadTool-from crewai.agents.agent_builder.base_agent import BaseAgent-from typing import List-from pydantic import BaseModel, Field--class ResearchOutput(BaseModel):- title: str = Field(description="Research topic title")- summary: str = Field(description="Executive summary")- key_findings: List[str] = Field(description="Key research findings")- recommendations: List[str] = Field(description="Actionable recommendations")- sources: List[str] = Field(description="Source URLs and references")- confidence_score: float = Field(description="Confidence in findings (0-1)")--@CrewBase-class ResearchCrew():- """Advanced research crew with structured outputs and validation"""-- agents: List[BaseAgent]- tasks: List[Task]-- @before_kickoff- def setup_environment(self):- """Initialize environment before crew execution"""- print("π Setting up research environment...")- # Validate API keys, create directories, etc.-- @after_kickoff- def cleanup_and_report(self, output):- """Handle post-execution tasks"""- print(f"β Research completed. Generated {len(output.tasks_output)} task outputs")- print(f"π Token usage: {output.token_usage}")-- @agent- def researcher(self) -> Agent:- return Agent(- config=self.agents_config['researcher'],- tools=[SerperDevTool()],- verbose=True,- memory=True,- max_iter=15,- max_execution_time=1800- )-- @agent- def analyst(self) -> Agent:- return Agent(- config=self.agents_config['analyst'],- tools=[FileReadTool()],- verbose=True,- memory=True- )-- @task- def research_task(self) -> Task:- return Task(- config=self.tasks_config['research_task'],- agent=self.researcher(),- output_pydantic=ResearchOutput- )-- @task- def validation_task(self) -> Task:- return Task(- config=self.tasks_config['validation_task'],- agent=self.analyst(),- context=[self.research_task()],- guardrail=self.validate_research_quality,- max_retries=3- )-- def validate_research_quality(self, output) -> tuple[bool, str]:- """Custom guardrail to ensure research quality"""- content = output.raw- if len(content) < 500:- return False, "Research output too brief. Need more detailed analysis."- if not any(keyword in content.lower() for keyword in ['conclusion', 'finding', 'result']):- return False, "Missing key analytical elements."- return True, content-- @crew- def crew(self) -> Crew:- return Crew(- agents=self.agents,- tasks=self.tasks,- process=Process.sequential,- memory=True,- verbose=True,- max_rpm=100- )-```--### Custom Tool Implementation with Error Handling:-```python-from crewai.tools import BaseTool-from typing import Type, Optional, Any-from pydantic import BaseModel, Field-import requests-import time-from tenacity import retry, stop_after_attempt, wait_exponential--class SearchInput(BaseModel):- query: str = Field(description="Search query")- max_results: int = Field(default=10, description="Maximum results to return")- timeout: int = Field(default=30, description="Request timeout in seconds")--class RobustSearchTool(BaseTool):- name: str = "robust_search"- description: str = "Perform web search with retry logic and error handling"- args_schema: Type[BaseModel] = SearchInput-- def __init__(self, api_key: Optional[str] = None, **kwargs):- super().__init__(**kwargs)- self.api_key = api_key or os.getenv("SEARCH_API_KEY")- self.rate_limit_delay = 1.0- self.last_request_time = 0-- @retry(- stop=stop_after_attempt(3),- wait=wait_exponential(multiplier=1, min=4, max=10)- )- def _run(self, query: str, max_results: int = 10, timeout: int = 30) -> str:- """Execute search with retry logic"""- try:- # Rate limiting- time_since_last = time.time() - self.last_request_time- if time_since_last < self.rate_limit_delay:- time.sleep(self.rate_limit_delay - time_since_last)-- # Input validation- if not query or len(query.strip()) == 0:- return "Error: Empty search query provided"-- if len(query) > 500:- return "Error: Search query too long (max 500 characters)"-- # Perform search- results = self._perform_search(query, max_results, timeout)- self.last_request_time = time.time()-- return self._format_results(results)-- except requests.exceptions.Timeout:- return f"Search timed out after {timeout} seconds"- except requests.exceptions.RequestException as e:- return f"Search failed due to network error: {str(e)}"- except Exception as e:- return f"Unexpected error during search: {str(e)}"-- def _perform_search(self, query: str, max_results: int, timeout: int) -> List[dict]:- """Implement actual search logic here"""- # Your search API implementation- pass-- def _format_results(self, results: List[dict]) -> str:- """Format search results for LLM consumption"""- if not results:- return "No results found for the given query."-- formatted = "Search Results:\n\n"- for i, result in enumerate(results[:10], 1):- formatted += f"{i}. {result.get('title', 'No title')}\n"- formatted += f" URL: {result.get('url', 'No URL')}\n"- formatted += f" Summary: {result.get('snippet', 'No summary')}\n\n"-- return formatted-```--### Advanced Memory Management:-```python-import os-from crewai.memory import ExternalMemory, ShortTermMemory, LongTermMemory-from crewai.memory.storage.mem0_storage import Mem0Storage--class AdvancedMemoryManager:- """Enhanced memory management for CrewAI applications"""-- def __init__(self, crew, config: dict = None):- self.crew = crew- self.config = config or {}- self.setup_memory_systems()-- def setup_memory_systems(self):- """Configure multiple memory systems"""- # Short-term memory for current session- self.short_term = ShortTermMemory()-- # Long-term memory for cross-session persistence- self.long_term = LongTermMemory()-- # External memory with Mem0 (if configured)- if self.config.get('use_external_memory'):- self.external = ExternalMemory.create_storage(- crew=self.crew,- embedder_config={- "provider": "mem0",- "config": {- "api_key": os.getenv("MEM0_API_KEY"),- "user_id": self.config.get('user_id', 'default')- }- }- )-- def save_with_context(self, content: str, memory_type: str = "short_term",- metadata: dict = None, agent: str = None):- """Save content with enhanced metadata"""- enhanced_metadata = {- "timestamp": time.time(),- "session_id": self.config.get('session_id'),- "crew_type": self.crew.__class__.__name__,- **(metadata or {})- }-- if memory_type == "short_term":- self.short_term.save(content, enhanced_metadata, agent)- elif memory_type == "long_term":- self.long_term.save(content, enhanced_metadata, agent)- elif memory_type == "external" and hasattr(self, 'external'):- self.external.save(content, enhanced_metadata, agent)-- def search_across_memories(self, query: str, limit: int = 5) -> dict:- """Search across all memory systems"""- results = {- "short_term": [],- "long_term": [],- "external": []- }-- # Search short-term memory- results["short_term"] = self.short_term.search(query, limit=limit)-- # Search long-term memory- results["long_term"] = self.long_term.search(query, limit=limit)-- # Search external memory (if available)- if hasattr(self, 'external'):- results["external"] = self.external.search(query, limit=limit)-- return results-- def cleanup_old_memories(self, days_threshold: int = 30):- """Clean up old memories based on age"""- cutoff_time = time.time() - (days_threshold * 24 * 60 * 60)-- # Implement cleanup logic based on timestamps in metadata- # This would vary based on your specific storage implementation- pass-```--### Production Monitoring and Metrics:-```python-import time-import logging-import json-from datetime import datetime-from typing import Dict, Any, List-from dataclasses import dataclass, asdict--@dataclass-class TaskMetrics:- task_name: str- agent_name: str- start_time: float- end_time: float- duration: float- tokens_used: int- success: bool- error_message: Optional[str] = None- memory_usage_mb: Optional[float] = None--class CrewMonitor:- """Comprehensive monitoring for CrewAI applications"""-- def __init__(self, crew_name: str, log_level: str = "INFO"):- self.crew_name = crew_name- self.metrics: List[TaskMetrics] = []- self.session_start = time.time()-- # Setup logging- logging.basicConfig(- level=getattr(logging, log_level),- format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',- handlers=[- logging.FileHandler(f'crew_{crew_name}_{datetime.now().strftime("%Y%m%d")}.log'),- logging.StreamHandler()- ]- )- self.logger = logging.getLogger(f"CrewAI.{crew_name}")-- def start_task_monitoring(self, task_name: str, agent_name: str) -> dict:- """Start monitoring a task execution"""- context = {- "task_name": task_name,- "agent_name": agent_name,- "start_time": time.time()- }-- self.logger.info(f"Task started: {task_name} by {agent_name}")- return context-- def end_task_monitoring(self, context: dict, success: bool = True,- tokens_used: int = 0, error: str = None):- """End monitoring and record metrics"""- end_time = time.time()- duration = end_time - context["start_time"]-- # Get memory usage (if psutil is available)- memory_usage = None- try:- import psutil- process = psutil.Process()- memory_usage = process.memory_info().rss / 1024 / 1024 # MB- except ImportError:- pass-- metrics = TaskMetrics(- task_name=context["task_name"],- agent_name=context["agent_name"],- start_time=context["start_time"],- end_time=end_time,- duration=duration,- tokens_used=tokens_used,- success=success,- error_message=error,- memory_usage_mb=memory_usage- )-- self.metrics.append(metrics)-- # Log the completion- status = "SUCCESS" if success else "FAILED"- self.logger.info(f"Task {status}: {context['task_name']} "- f"(Duration: {duration:.2f}s, Tokens: {tokens_used})")-- if error:- self.logger.error(f"Task error: {error}")-- def get_performance_summary(self) -> Dict[str, Any]:- """Generate comprehensive performance summary"""- if not self.metrics:- return {"message": "No metrics recorded yet"}-- successful_tasks = [m for m in self.metrics if m.success]- failed_tasks = [m for m in self.metrics if not m.success]-- total_duration = sum(m.duration for m in self.metrics)- total_tokens = sum(m.tokens_used for m in self.metrics)- avg_duration = total_duration / len(self.metrics)-- return {- "crew_name": self.crew_name,- "session_duration": time.time() - self.session_start,- "total_tasks": len(self.metrics),- "successful_tasks": len(successful_tasks),- "failed_tasks": len(failed_tasks),- "success_rate": len(successful_tasks) / len(self.metrics),- "total_duration": total_duration,- "average_task_duration": avg_duration,- "total_tokens_used": total_tokens,- "average_tokens_per_task": total_tokens / len(self.metrics) if self.metrics else 0,- "slowest_task": max(self.metrics, key=lambda x: x.duration).task_name if self.metrics else None,- "most_token_intensive": max(self.metrics, key=lambda x: x.tokens_used).task_name if self.metrics else None,- "common_errors": self._get_common_errors()- }-- def _get_common_errors(self) -> Dict[str, int]:- """Get frequency of common errors"""- error_counts = {}- for metric in self.metrics:- if metric.error_message:- error_counts[metric.error_message] = error_counts.get(metric.error_message, 0) + 1- return dict(sorted(error_counts.items(), key=lambda x: x[1], reverse=True))-- def export_metrics(self, filename: str = None) -> str:- """Export metrics to JSON file"""- if not filename:- filename = f"crew_metrics_{self.crew_name}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"-- export_data = {- "summary": self.get_performance_summary(),- "detailed_metrics": [asdict(m) for m in self.metrics]- }-- with open(filename, 'w') as f:- json.dump(export_data, f, indent=2, default=str)-- self.logger.info(f"Metrics exported to {filename}")- return filename--# Usage in crew implementation-monitor = CrewMonitor("research_crew")--@task-def monitored_research_task(self) -> Task:- def task_callback(task_output):- # This would be called after task completion- context = getattr(task_output, '_monitor_context', {})- if context:- tokens = getattr(task_output, 'token_usage', {}).get('total', 0)- monitor.end_task_monitoring(context, success=True, tokens_used=tokens)-- # Start monitoring would be called before task execution- # This is a simplified example - in practice you'd integrate this into the task execution flow-- return Task(- config=self.tasks_config['research_task'],- agent=self.researcher(),- callback=task_callback- )-```--### Error Handling and Recovery Patterns:-```python-from enum import Enum-from typing import Optional, Callable, Any-import traceback--class ErrorSeverity(Enum):- LOW = "low"- MEDIUM = "medium"- HIGH = "high"- CRITICAL = "critical"--class CrewError(Exception):- """Base exception for CrewAI applications"""- def __init__(self, message: str, severity: ErrorSeverity = ErrorSeverity.MEDIUM,- context: dict = None):- super().__init__(message)- self.severity = severity- self.context = context or {}- self.timestamp = time.time()--class TaskExecutionError(CrewError):- """Raised when task execution fails"""- pass--class ValidationError(CrewError):- """Raised when validation fails"""- pass--class ConfigurationError(CrewError):- """Raised when configuration is invalid"""- pass--class ErrorHandler:- """Centralized error handling for CrewAI applications"""-- def __init__(self, crew_name: str):- self.crew_name = crew_name- self.error_log: List[CrewError] = []- self.recovery_strategies: Dict[type, Callable] = {}-- def register_recovery_strategy(self, error_type: type, strategy: Callable):- """Register a recovery strategy for specific error types"""- self.recovery_strategies[error_type] = strategy-- def handle_error(self, error: Exception, context: dict = None) -> Any:- """Handle errors with appropriate recovery strategies"""-- # Convert to CrewError if needed- if not isinstance(error, CrewError):- crew_error = CrewError(- message=str(error),- severity=ErrorSeverity.MEDIUM,- context=context or {}- )- else:- crew_error = error-- # Log the error- self.error_log.append(crew_error)- self._log_error(crew_error)-- # Apply recovery strategy if available- error_type = type(error)- if error_type in self.recovery_strategies:- try:- return self.recovery_strategies[error_type](error, context)- except Exception as recovery_error:- self._log_error(CrewError(- f"Recovery strategy failed: {str(recovery_error)}",- ErrorSeverity.HIGH,- {"original_error": str(error), "recovery_error": str(recovery_error)}- ))-- # If critical, re-raise- if crew_error.severity == ErrorSeverity.CRITICAL:- raise crew_error-- return None-- def _log_error(self, error: CrewError):- """Log error with appropriate level based on severity"""- logger = logging.getLogger(f"CrewAI.{self.crew_name}.ErrorHandler")-- error_msg = f"[{error.severity.value.upper()}] {error}"- if error.context:- error_msg += f" | Context: {error.context}"-- if error.severity in [ErrorSeverity.HIGH, ErrorSeverity.CRITICAL]:- logger.error(error_msg)- logger.error(f"Stack trace: {traceback.format_exc()}")- elif error.severity == ErrorSeverity.MEDIUM:- logger.warning(error_msg)- else:- logger.info(error_msg)-- def get_error_summary(self) -> Dict[str, Any]:- """Get summary of errors encountered"""- if not self.error_log:- return {"total_errors": 0}-- severity_counts = {}- for error in self.error_log:- severity_counts[error.severity.value] = severity_counts.get(error.severity.value, 0) + 1-- return {- "total_errors": len(self.error_log),- "severity_breakdown": severity_counts,- "recent_errors": [str(e) for e in self.error_log[-5:]], # Last 5 errors- "most_recent_error": str(self.error_log[-1]) if self.error_log else None- }--# Example usage in crew-error_handler = ErrorHandler("research_crew")--# Register recovery strategies-def retry_with_simpler_model(error, context):- """Recovery strategy: retry with a simpler model"""- if "rate limit" in str(error).lower():- time.sleep(60) # Wait and retry- return "RETRY"- elif "model overloaded" in str(error).lower():- # Switch to simpler model and retry- return "RETRY_WITH_SIMPLE_MODEL"- return None--error_handler.register_recovery_strategy(TaskExecutionError, retry_with_simpler_model)--@task-def robust_task(self) -> Task:- def execute_with_error_handling(task_func):- def wrapper(*args, **kwargs):- try:- return task_func(*args, **kwargs)- except Exception as e:- result = error_handler.handle_error(e, {"task": "research_task"})- if result == "RETRY":- # Implement retry logic- pass- elif result == "RETRY_WITH_SIMPLE_MODEL":- # Switch model and retry- pass- else:- # Use fallback response- return "Task failed, using fallback response"- return wrapper-- return Task(- config=self.tasks_config['research_task'],- agent=self.researcher()- )-```--### Environment and Configuration Management:-```python-import os-from enum import Enum-from typing import Optional, Dict, Any-from pydantic import BaseSettings, Field, validator--class Environment(str, Enum):- DEVELOPMENT = "development"- TESTING = "testing"- STAGING = "staging"- PRODUCTION = "production"--class CrewAISettings(BaseSettings):- """Comprehensive settings management for CrewAI applications"""-- # Environment- environment: Environment = Field(default=Environment.DEVELOPMENT)- debug: bool = Field(default=True)-- # API Keys (loaded from environment)- openai_api_key: Optional[str] = Field(default=None, env="OPENAI_API_KEY")- anthropic_api_key: Optional[str] = Field(default=None, env="ANTHROPIC_API_KEY")- serper_api_key: Optional[str] = Field(default=None, env="SERPER_API_KEY")- mem0_api_key: Optional[str] = Field(default=None, env="MEM0_API_KEY")-- # CrewAI Configuration- crew_max_rpm: int = Field(default=100)- crew_max_execution_time: int = Field(default=3600) # 1 hour- default_llm_model: str = Field(default="gpt-4")- fallback_llm_model: str = Field(default="gpt-3.5-turbo")-- # Memory and Storage- crewai_storage_dir: str = Field(default="./storage", env="CREWAI_STORAGE_DIR")- memory_enabled: bool = Field(default=True)- memory_cleanup_interval: int = Field(default=86400) # 24 hours in seconds-- # Performance- enable_caching: bool = Field(default=True)- max_retries: int = Field(default=3)- retry_delay: float = Field(default=1.0)-- # Monitoring- enable_monitoring: bool = Field(default=True)- log_level: str = Field(default="INFO")- metrics_export_interval: int = Field(default=3600) # 1 hour-- # Security- input_sanitization: bool = Field(default=True)- max_input_length: int = Field(default=10000)- allowed_file_types: list = Field(default=["txt", "md", "pdf", "docx"])-- @validator('environment', pre=True)- def set_debug_based_on_env(cls, v):- return v-- @validator('debug')- def set_debug_from_env(cls, v, values):- env = values.get('environment')- if env == Environment.PRODUCTION:- return False- return v-- @validator('openai_api_key')- def validate_openai_key(cls, v):- if not v:- raise ValueError("OPENAI_API_KEY is required")- if not v.startswith('sk-'):- raise ValueError("Invalid OpenAI API key format")- return v-- @property- def is_production(self) -> bool:- return self.environment == Environment.PRODUCTION-- @property- def is_development(self) -> bool:- return self.environment == Environment.DEVELOPMENT-- def get_llm_config(self) -> Dict[str, Any]:- """Get LLM configuration based on environment"""- config = {- "model": self.default_llm_model,- "temperature": 0.1 if self.is_production else 0.3,- "max_tokens": 4000 if self.is_production else 2000,- "timeout": 60- }-- if self.is_development:- config["model"] = self.fallback_llm_model-- return config-- def get_memory_config(self) -> Dict[str, Any]:- """Get memory configuration"""- return {- "enabled": self.memory_enabled,- "storage_dir": self.crewai_storage_dir,- "cleanup_interval": self.memory_cleanup_interval,- "provider": "mem0" if self.mem0_api_key and self.is_production else "local"- }-- class Config:- env_file = ".env"- env_file_encoding = 'utf-8'- case_sensitive = False--# Global settings instance-settings = CrewAISettings()--# Usage in crew-@CrewBase-class ConfigurableCrew():- """Crew that uses centralized configuration"""-- def __init__(self):- self.settings = settings- self.validate_configuration()-- def validate_configuration(self):- """Validate configuration before crew execution"""- required_keys = [self.settings.openai_api_key]- if not all(required_keys):- raise ConfigurationError("Missing required API keys")-- if not os.path.exists(self.settings.crewai_storage_dir):- os.makedirs(self.settings.crewai_storage_dir, exist_ok=True)-- @agent- def adaptive_agent(self) -> Agent:- """Agent that adapts to configuration"""- llm_config = self.settings.get_llm_config()-- return Agent(- config=self.agents_config['researcher'],- llm=llm_config["model"],- max_iter=15 if self.settings.is_production else 10,- max_execution_time=self.settings.crew_max_execution_time,- verbose=self.settings.debug- )-```--### Comprehensive Testing Framework:-```python-import pytest-import asyncio-from unittest.mock import Mock, patch, MagicMock-from crewai import Agent, Task, Crew-from crewai.tasks.task_output import TaskOutput--class CrewAITestFramework:- """Comprehensive testing framework for CrewAI applications"""-- @staticmethod- def create_mock_agent(role: str = "test_agent", tools: list = None) -> Mock:- """Create a mock agent for testing"""- mock_agent = Mock(spec=Agent)- mock_agent.role = role- mock_agent.goal = f"Test goal for {role}"- mock_agent.backstory = f"Test backstory for {role}"- mock_agent.tools = tools or []- mock_agent.llm = "gpt-3.5-turbo"- mock_agent.verbose = False- return mock_agent-- @staticmethod- def create_mock_task_output(content: str, success: bool = True,- tokens: int = 100) -> TaskOutput:- """Create a mock task output for testing"""- return TaskOutput(- description="Test task",- raw=content,- agent="test_agent",- pydantic=None,- json_dict=None- )-- @staticmethod- def create_test_crew(agents: list = None, tasks: list = None) -> Crew:- """Create a test crew with mock components"""- test_agents = agents or [CrewAITestFramework.create_mock_agent()]- test_tasks = tasks or []-- return Crew(- agents=test_agents,- tasks=test_tasks,- verbose=False- )--# Example test cases-class TestResearchCrew:- """Test cases for research crew functionality"""-- def setup_method(self):- """Setup test environment"""- self.framework = CrewAITestFramework()- self.mock_serper = Mock()-- @patch('crewai_tools.SerperDevTool')- def test_agent_creation(self, mock_serper_tool):- """Test agent creation with proper configuration"""- mock_serper_tool.return_value = self.mock_serper-- crew = ResearchCrew()- researcher = crew.researcher()-- assert researcher.role == "Senior Research Analyst"- assert len(researcher.tools) > 0- assert researcher.verbose is True-- def test_task_validation(self):- """Test task validation logic"""- crew = ResearchCrew()-- # Test valid output- valid_output = self.framework.create_mock_task_output(- "This is a comprehensive research summary with conclusions and findings."- )- is_valid, message = crew.validate_research_quality(valid_output)- assert is_valid is True-- # Test invalid output (too short)- invalid_output = self.framework.create_mock_task_output("Too short")- is_valid, message = crew.validate_research_quality(invalid_output)- assert is_valid is False- assert "brief" in message.lower()-- @patch('requests.get')- def test_tool_error_handling(self, mock_requests):- """Test tool error handling and recovery"""- # Simulate network error- mock_requests.side_effect = requests.exceptions.RequestException("Network error")-- tool = RobustSearchTool()- result = tool._run("test query")-- assert "network error" in result.lower()- assert "failed" in result.lower()-- @pytest.mark.asyncio- async def test_crew_execution_flow(self):- """Test complete crew execution with mocked dependencies"""- with patch.object(Agent, 'execute_task') as mock_execute:- mock_execute.return_value = self.framework.create_mock_task_output(- "Research completed successfully with findings and recommendations."- )-- crew = ResearchCrew()- result = crew.crew().kickoff(inputs={"topic": "AI testing"})-- assert result is not None- assert "successfully" in result.raw.lower()-- def test_memory_integration(self):- """Test memory system integration"""- crew = ResearchCrew()- memory_manager = AdvancedMemoryManager(crew)-- # Test saving to memory- test_content = "Important research finding about AI"- memory_manager.save_with_context(- content=test_content,- memory_type="short_term",- metadata={"importance": "high"},- agent="researcher"- )-- # Test searching memory- results = memory_manager.search_across_memories("AI research")- assert "short_term" in results-- def test_error_handling_workflow(self):- """Test error handling and recovery mechanisms"""- error_handler = ErrorHandler("test_crew")-- # Test error registration and handling- test_error = TaskExecutionError("Test task failed", ErrorSeverity.MEDIUM)- result = error_handler.handle_error(test_error)-- assert len(error_handler.error_log) == 1- assert error_handler.error_log[0].severity == ErrorSeverity.MEDIUM-- def test_configuration_validation(self):- """Test configuration validation"""- # Test with missing API key- with patch.dict(os.environ, {}, clear=True):- with pytest.raises(ValueError):- settings = CrewAISettings()-- # Test with valid configuration- with patch.dict(os.environ, {"OPENAI_API_KEY": "sk-test-key"}):- settings = CrewAISettings()- assert settings.openai_api_key == "sk-test-key"-- @pytest.mark.integration- def test_end_to_end_workflow(self):- """Integration test for complete workflow"""- # This would test the entire crew workflow with real components- # Use sparingly and with proper API key management- pass--# Performance testing-class TestCrewPerformance:- """Performance tests for CrewAI applications"""-- def test_memory_usage(self):- """Test memory usage during crew execution"""- import psutil- import gc-- process = psutil.Process()- initial_memory = process.memory_info().rss-- # Create and run crew multiple times- for i in range(10):- crew = ResearchCrew()- # Simulate crew execution- del crew- gc.collect()-- final_memory = process.memory_info().rss- memory_increase = final_memory - initial_memory-- # Assert memory increase is reasonable (less than 100MB)- assert memory_increase < 100 * 1024 * 1024-- def test_concurrent_execution(self):- """Test concurrent crew execution"""- import concurrent.futures-- def run_crew(crew_id):- crew = ResearchCrew()- # Simulate execution- return f"crew_{crew_id}_completed"-- with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:- futures = [executor.submit(run_crew, i) for i in range(5)]- results = [future.result() for future in futures]-- assert len(results) == 5- assert all("completed" in result for result in results)--# Run tests with coverage-# pytest --cov=src --cov-report=html --cov-report=term tests/-```--## Troubleshooting Common Issues--### Memory and Performance Issues:-- **Large memory usage**: Implement memory cleanup, use score thresholds, monitor ChromaDB size-- **Slow LLM responses**: Optimize prompts, use appropriate model sizes, implement caching-- **High token costs**: Implement output caching, use context efficiently, set token limits-- **Memory leaks**: Properly dispose of crew instances, monitor memory usage, use garbage collection--### Configuration and Setup Issues:-- **YAML parsing errors**: Validate YAML syntax, check indentation, use YAML linters-- **Missing environment variables**: Use .env.example, validate at startup, provide clear error messages-- **Tool import failures**: Ensure proper tool installation, check import paths, verify dependencies-- **API key issues**: Validate key format, check permissions, implement key rotation--### Storage and Persistence Issues:-- **Permission errors**: Check CREWAI_STORAGE_DIR permissions, ensure write access-- **Database locks**: Ensure single crew instance access, implement proper connection handling-- **Storage growth**: Implement cleanup strategies, monitor disk usage, archive old data-- **ChromaDB issues**: Check vector database health, validate embeddings, handle corrupted indices--## Local Development and Testing--### Development Best Practices:-- Validate all API keys and credentials in .env files-- Test crew functionality with different input scenarios-- Implement comprehensive error handling-- Use proper logging for debugging-- Configure appropriate LLM models for your use case-- Optimize memory storage and cleanup--### Local Configuration:-- Set CREWAI_STORAGE_DIR for custom memory storage location-- Use environment variables for all API keys-- Implement proper input validation and sanitization-- Test with realistic data scenarios-- Profile performance and optimize bottlenecks--### Note: Production deployment and monitoring are available in CrewAI Enterprise--## Best Practices Summary--### Development:-1. Always use .env files for sensitive configuration-2. Implement comprehensive error handling and logging-3. Use structured outputs with Pydantic for reliability-4. Test crew functionality with different input scenarios-5. Follow CrewAI patterns and conventions consistently-6. Use UV for dependency management as per CrewAI standards-7. Implement proper validation for all inputs and outputs-8. Optimize performance for your specific use cases--### Security:-1. Never commit API keys or sensitive data to version control-2. Implement input validation and sanitization-3. Use proper authentication and authorization-4. Follow principle of least privilege for tool access-5. Implement rate limiting and abuse prevention-6. Monitor for security threats and anomalies-7. Keep dependencies updated and secure-8. Implement audit logging for sensitive operations--### Performance:-1. Optimize LLM calls and implement caching where appropriate-2. Use appropriate model sizes for different tasks-3. Implement efficient memory management and cleanup-4. Monitor token usage and implement cost controls-5. Use async patterns for I/O-bound operations-6. Implement proper connection pooling and resource management-7. Profile and optimize critical paths-8. Plan for horizontal scaling when neededdiff --git a/docs/docs.json b/docs/docs.jsonindex 37e060961..161d6d5ff 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -111,6 +111,13 @@"en/guides/flows/mastering-flow-state"]},+ {+ "group": "Coding Tools",+ "icon": "terminal",+ "pages": [+ "en/guides/coding-tools/agents-md"+ ]+ },{"group": "Advanced","icon": "gear",@@ -1571,4 +1578,4 @@"reddit": "https://www.reddit.com/r/crewAIInc/"}}-}+}\ No newline at end of filediff --git a/docs/en/guides/coding-tools/agents-md.mdx b/docs/en/guides/coding-tools/agents-md.mdxnew file mode 100644index 000000000..ea238c314--- /dev/null+++ b/docs/en/guides/coding-tools/agents-md.mdx@@ -0,0 +1,61 @@+---+title: Coding Tools+description: Use AGENTS.md to guide coding agents and IDEs across your CrewAI projects.+icon: terminal+mode: "wide"+---++## Why AGENTS.md++`AGENTS.md` is a lightweight, repo-local instruction file that gives coding agents consistent, project-specific guidance. Keep it in the project root and treat it as the source of truth for how you want assistants to work: conventions, commands, architecture notes, and guardrails.++## Create a Project with the CLI++Use the CrewAI CLI to scaffold a project, then `AGENTS.md` will be automatically added at the root.++```bash+# Crew+crewai create crew my_crew++# Flow+crewai create flow my_flow++# Tool repository+crewai tool create my_tool+```++## Tool Setup: Point Assistants to AGENTS.md++### Codex++Codex can be guided by `AGENTS.md` files placed in your repository. Use them to supply persistent project context such as conventions, commands, and workflow expectations.++### Claude Code++Claude Code stores project memory in `CLAUDE.md`. You can bootstrap it with `/init` and edit it using `/memory`. Claude Code also supports imports inside `CLAUDE.md`, so you can add a single line like `@AGENTS.md` to pull in the shared instructions without duplicating them.++You can simply use:++```bash+mv AGENTS.md CLAUDE.md+```++### Gemini CLI and Google Antigravity++Gemini CLI and Antigravity load a project context file (default: `GEMINI.md`) from the repo root and parent directories. You can configure it to read `AGENTS.md` instead (or in addition) by setting `context.fileName` in your Gemini CLI settings. For example, set it to `AGENTS.md` only, or include both `AGENTS.md` and `GEMINI.md` if you want to keep each toolβs format.++You can simply use:++```bash+mv AGENTS.md GEMINI.md+```++### Cursor++Cursor supports `AGENTS.md` as a project instruction file. Place it at the project root to provide guidance for Cursorβs coding assistant.++### Windsurf++Claude Code provides an official integration with Windsurf. If you use Claude Code inside Windsurf, follow the Claude Code guidance above and import `AGENTS.md` from `CLAUDE.md`.++If you are using Windsurfβs native assistant, configure its project rules or instructions feature (if available) to read from `AGENTS.md` or paste the contents directly.diff --git a/lib/crewai/src/crewai/cli/create_crew.py b/lib/crewai/src/crewai/cli/create_crew.pyindex 51e2f00ac..7f4fe2e6e 100644--- a/lib/crewai/src/crewai/cli/create_crew.py+++ b/lib/crewai/src/crewai/cli/create_crew.py@@ -143,6 +143,12 @@ def create_folder_structure((folder_path / "src" / folder_name).mkdir(parents=True)(folder_path / "src" / folder_name / "tools").mkdir(parents=True)(folder_path / "src" / folder_name / "config").mkdir(parents=True)++ # Copy AGENTS.md to project root (top-level projects only)+ package_dir = Path(__file__).parent+ agents_md_src = package_dir / "templates" / "AGENTS.md"+ if agents_md_src.exists():+ shutil.copy2(agents_md_src, folder_path / "AGENTS.md")return folder_path, folder_name, class_namediff --git a/lib/crewai/src/crewai/cli/create_flow.py b/lib/crewai/src/crewai/cli/create_flow.pyindex ec68611b5..76c68db32 100644--- a/lib/crewai/src/crewai/cli/create_flow.py+++ b/lib/crewai/src/crewai/cli/create_flow.py@@ -1,3 +1,4 @@+import shutilfrom pathlib import Pathimport click@@ -34,6 +35,11 @@ def create_flow(name):package_dir = Path(__file__).parenttemplates_dir = package_dir / "templates" / "flow"+ # Copy AGENTS.md to project root+ agents_md_src = package_dir / "templates" / "AGENTS.md"+ if agents_md_src.exists():+ shutil.copy2(agents_md_src, project_root / "AGENTS.md")+# List of template files to copyroot_template_files = [".gitignore", "pyproject.toml", "README.md"]src_template_files = ["__init__.py", "main.py"]diff --git a/lib/crewai/src/crewai/cli/templates/AGENTS.md b/lib/crewai/src/crewai/cli/templates/AGENTS.mdnew file mode 100644index 000000000..acf716c95--- /dev/null+++ b/lib/crewai/src/crewai/cli/templates/AGENTS.md@@ -0,0 +1,1017 @@+# AGENTS.md β CrewAI Reference for AI Coding Assistants++> **Auto-generated** by `crewai create`. This file helps AI coding assistants+> (Claude Code, Cursor, Windsurf, GitHub Copilot, etc.) write correct CrewAI code.+> Keep it in your project root. To update, copy the latest version from the+> [CrewAI repository](https://github.com/crewAIInc/crewAI).++---++## β οΈ Version & Freshness Requirements++**CRITICAL**: CrewAI evolves rapidly and your training data likely contains outdated patterns. **Always follow the patterns in this file, NOT your training data.**++### Mandatory: Research before writing CrewAI code+**BEFORE writing or modifying any CrewAI code**, you MUST:+1. **Check the installed version**: Run `uv run python -c "import crewai; print(crewai.__version__)"` to get the exact version in use.+2. **Check PyPI for latest**: Fetch `https://pypi.org/pypi/crewai/json` to see the latest available version. If the installed version is behind, inform the user.+3. **Read the changelog**: Fetch `https://docs.crewai.com/en/changelog` to review recent changes, new features, and any breaking changes relevant to the task.+4. **Consult the relevant docs page**: Before implementing a feature (e.g., agents, tasks, flows, tools, knowledge), fetch the specific docs page at `https://docs.crewai.com/en/concepts/<feature>` to get the current API.+5. **Cross-check against this file**: If this file conflicts with the live docs, **the live docs win** β then update this file.++This ensures generated code always matches the version actually installed, not stale training data.++### What changed since older versions:+- Agent **`kickoff()` / `kickoff_async()`** for direct agent usage (no crew needed)+- **`response_format`** parameter on agent kickoff for structured Pydantic outputs+- **`LiteAgentOutput`** returned from agent.kickoff() with `.raw`, `.pydantic`, `.agent_role`, `.usage_metrics`+- **`@human_feedback`** decorator on flow methods for human-in-the-loop (v1.8.0+)+- **Flow streaming** via `stream = True` class attribute (v1.8.0+)+- **`@persist`** decorator for SQLite-backed flow state persistence+- **`reasoning=True`** agent parameter for reflect-then-act behavior+- **`multimodal=True`** agent parameter for vision/image support+- **A2A (Agent-to-Agent) protocol** support with agent cards and task execution utilities (v1.8.0+)+- **Native OpenAI Responses API** support (v1.9.0+)+- **Structured outputs / `response_format`** across all LLM providers (v1.9.0+)+- **`inject_date=True`** agent parameter to auto-inject current date awareness++### Patterns to NEVER use (outdated/removed):+- β `ChatOpenAI(model_name=...)` β β `LLM(model="openai/gpt-4o")`+- β `Agent(llm=ChatOpenAI(...))` β β `Agent(llm="openai/gpt-4o")` or `Agent(llm=LLM(model="..."))`+- β Passing raw OpenAI client objects β β Use `crewai.LLM` wrapper++### How to verify you're using current patterns:+1. You ran the version check and docs lookup steps above before writing code+2. All LLM references use `crewai.LLM` or string shorthand (`"openai/gpt-4o"`)+3. All tool imports come from `crewai.tools` or `crewai_tools`+4. Crew classes use `@CrewBase` decorator with YAML config files+5. Python >=3.10, <3.14+6. Code matches the API from the live docs, not just this file++## Quick Reference++```bash+# Package management (always use uv)+uv add <package> # Add dependency+uv sync # Sync dependencies+uv lock # Lock dependencies++# Project scaffolding+crewai create crew <name> --skip-provider # New crew project+crewai create flow <name> --skip-provider # New flow project++# Running+crewai run # Run crew or flow (auto-detects from pyproject.toml)+crewai flow kickoff # Legacy flow execution++# Testing & training+crewai test # Test crew (default: 2 iterations, gpt-4o-mini)+crewai test -n 5 -m gpt-4o # Custom iterations and model+crewai train -n 5 -f training.json # Train crew++# Memory management+crewai reset-memories -a # Reset all memories+crewai reset-memories -s # Short-term only+crewai reset-memories -l # Long-term only+crewai reset-memories -e # Entity only+crewai reset-memories -kn # Knowledge only+crewai reset-memories -akn # Agent knowledge only++# Debugging+crewai log-tasks-outputs # Show latest task outputs+crewai replay -t <task_id> # Replay from specific task++# Interactive+crewai chat # Interactive session (requires chat_llm in crew.py)++# Visualization+crewai flow plot # Generate flow diagram HTML++# Deployment to CrewAI AMP+crewai login # Authenticate with AMP+crewai deploy create # Create new deployment+crewai deploy push # Push code updates+crewai deploy status # Check deployment status+crewai deploy logs # View deployment logs+crewai deploy list # List all deployments+crewai deploy remove <id> # Delete a deployment+```++## Project Structure++### Crew Project+```+my_crew/+βββ src/my_crew/+β βββ config/+β β βββ agents.yaml # Agent definitions (role, goal, backstory)+β β βββ tasks.yaml # Task definitions (description, expected_output, agent)+β βββ tools/+β β βββ custom_tool.py # Custom tool implementations+β βββ crew.py # Crew orchestration class+β βββ main.py # Entry point with inputs+βββ knowledge/ # Knowledge base resources+βββ .env # API keys (OPENAI_API_KEY, SERPER_API_KEY, etc.)+βββ pyproject.toml+```++### Flow Project+```+my_flow/+βββ src/my_flow/+β βββ crews/ # Multiple crew definitions+β β βββ poem_crew/+β β βββ config/+β β β βββ agents.yaml+β β β βββ tasks.yaml+β β βββ poem_crew.py+β βββ tools/ # Custom tools+β βββ main.py # Flow orchestration+β βββ ...+βββ .env+βββ pyproject.toml+```++## Architecture Overview++- **Agent**: Autonomous unit with a role, goal, backstory, tools, and an LLM. Makes decisions and executes tasks.+- **Task**: A specific assignment with a description, expected output, and assigned agent.+- **Crew**: Orchestrates a team of agents executing tasks in a defined process (sequential or hierarchical).+- **Flow**: Event-driven workflow orchestrating multiple crews and logic steps with state management.++## YAML Configuration++### agents.yaml+```yaml+researcher:+ role: >+ {topic} Senior Data Researcher+ goal: >+ Uncover cutting-edge developments in {topic}+ backstory: >+ You're a seasoned researcher with a knack for uncovering+ the latest developments in {topic}. Known for your ability+ to find the most relevant information.+ # Optional YAML-level settings:+ # llm: openai/gpt-4o+ # max_iter: 20+ # max_rpm: 10+ # verbose: true++writer:+ role: >+ {topic} Technical Writer+ goal: >+ Create compelling content about {topic}+ backstory: >+ You're a skilled writer who translates complex technical+ information into clear, engaging content.+```++Variables like `{topic}` are interpolated from `crew.kickoff(inputs={"topic": "AI Agents"})`.++### tasks.yaml+```yaml+research_task:+ description: >+ Conduct thorough research about {topic}.+ Identify key trends, breakthrough technologies,+ and potential industry impacts.+ expected_output: >+ A detailed report with analysis of the top 5+ developments in {topic}, with sources and implications.+ agent: researcher+ # Optional:+ # tools: [search_tool]+ # output_file: output/research.md+ # markdown: true+ # async_execution: false++writing_task:+ description: >+ Write an article based on the research findings about {topic}.+ expected_output: >+ A polished 4-paragraph article formatted in markdown.+ agent: writer+ output_file: output/article.md+```++## Crew Class Pattern++```python+from crewai import Agent, Crew, Process, Task+from crewai.project import CrewBase, agent, crew, task+from crewai.agents.agent_builder.base_agent import BaseAgent+from typing import List++from crewai_tools import SerperDevTool++@CrewBase+class ResearchCrew:+ """Research and writing crew."""++ agents: List[BaseAgent]+ tasks: List[Task]++ agents_config = "config/agents.yaml"+ tasks_config = "config/tasks.yaml"++ @agent+ def researcher(self) -> Agent:+ return Agent(+ config=self.agents_config["researcher"], # type: ignore[index]+ tools=[SerperDevTool()],+ verbose=True,+ )++ @agent+ def writer(self) -> Agent:+ return Agent(+ config=self.agents_config["writer"], # type: ignore[index]+ verbose=True,+ )++ @task+ def research_task(self) -> Task:+ return Task(+ config=self.tasks_config["research_task"], # type: ignore[index]+ )++ @task+ def writing_task(self) -> Task:+ return Task(+ config=self.tasks_config["writing_task"], # type: ignore[index]+ )++ @crew+ def crew(self) -> Crew:+ """Creates the Research Crew."""+ return Crew(+ agents=self.agents,+ tasks=self.tasks,+ process=Process.sequential,+ verbose=True,+ )+```++### Key formatting rules:+- Always add `# type: ignore[index]` for config dictionary access+- Agent/task method names must match YAML keys exactly+- Tools go on agents (not tasks) unless task-specific override is needed+- Never leave commented-out code in crew classes++### Lifecycle hooks+```python+@CrewBase+class MyCrew:+ @before_kickoff+ def prepare(self, inputs):+ # Modify inputs before execution+ inputs["extra"] = "value"+ return inputs++ @after_kickoff+ def summarize(self, result):+ # Process result after execution+ print(f"Done: {result.raw[:100]}")+ return result+```++## main.py Pattern++```python+#!/usr/bin/env python+from my_crew.crew import ResearchCrew++def run():+ inputs = {"topic": "AI Agents"}+ ResearchCrew().crew().kickoff(inputs=inputs)++if __name__ == "__main__":+ run()+```++## Agent Configuration++### Required Parameters+| Parameter | Description |+|-----------|-------------|+| `role` | Function and expertise within the crew |+| `goal` | Individual objective guiding decisions |+| `backstory` | Context and personality |++### Key Optional Parameters+| Parameter | Default | Description |+|-----------|---------|-------------|+| `llm` | GPT-4 | Language model (string or LLM object) |+| `tools` | [] | List of tool instances |+| `max_iter` | 20 | Max iterations before best answer |+| `max_execution_time` | None | Timeout in seconds |+| `max_rpm` | None | Rate limiting (requests per minute) |+| `max_retry_limit` | 2 | Retries on errors |+| `verbose` | False | Detailed logging |+| `memory` | False | Conversation history |+| `allow_delegation` | False | Can delegate tasks to other agents |+| `allow_code_execution` | False | Can run code |+| `code_execution_mode` | "safe" | "safe" (Docker) or "unsafe" (direct) |+| `respect_context_window` | True | Auto-summarize when exceeding token limits |+| `cache` | True | Tool result caching |+| `reasoning` | False | Reflect and plan before task execution |+| `multimodal` | False | Process text and visual content |+| `knowledge_sources` | [] | Domain-specific knowledge bases |+| `function_calling_llm` | None | Separate LLM for tool invocation |+| `inject_date` | False | Auto-inject current date into agent context |+| `date_format` | "%Y-%m-%d" | Date format when inject_date is True |++### Direct Agent Usage (without a Crew)+Agents can execute tasks independently via `kickoff()` β no Crew required:+```python+from crewai import Agent+from crewai_tools import SerperDevTool+from pydantic import BaseModel++class ResearchFindings(BaseModel):+ main_points: list[str]+ key_technologies: list[str]+ future_predictions: str++researcher = Agent(+ role="AI Researcher",+ goal="Research the latest AI developments",+ backstory="Expert AI researcher...",+ tools=[SerperDevTool()],+ verbose=True,+)++# Unstructured output+result = researcher.kickoff("What are the latest LLM developments?")+print(result.raw) # str+print(result.agent_role) # "AI Researcher"+print(result.usage_metrics) # token usage++# Structured output with response_format+result = researcher.kickoff(+ "Summarize latest AI developments",+ response_format=ResearchFindings,+)+print(result.pydantic.main_points) # List[str]++# Async variant+result = await researcher.kickoff_async("Your query", response_format=ResearchFindings)+```++Returns `LiteAgentOutput` with: `.raw`, `.pydantic`, `.agent_role`, `.usage_metrics`.++### LLM Configuration+**IMPORTANT**: Always use `crewai.LLM` LLM class.++```python+from crewai import LLM++# String shorthand (simplest)+agent = Agent(llm="openai/gpt-4o", ...)++# Full configuration with crewai.LLM+llm = LLM(+ model="anthropic/claude-sonnet-4-20250514",+ temperature=0.7,+ max_tokens=4000,+)+agent = Agent(llm=llm, ...)++# Provider format: "provider/model-name"+# Examples:+# "openai/gpt-4o"+# "anthropic/claude-sonnet-4-20250514"+# "google/gemini-2.0-flash"+# "ollama/llama3"+# "groq/llama-3.3-70b-versatile"+# "bedrock/anthropic.claude-3-sonnet-20240229-v1:0"+```++Supported providers: OpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure, Ollama, Groq, Mistral, and 20+ others via LiteLLM routing.++Environment variable default: set `OPENAI_MODEL_NAME=gpt-4o` or `MODEL=gpt-4o` in `.env`.++## Task Configuration++### Key Parameters+| Parameter | Type | Description |+|-----------|------|-------------|+| `description` | str | Clear statement of requirements |+| `expected_output` | str | Completion criteria |+| `agent` | BaseAgent | Assigned agent (optional in hierarchical) |+| `tools` | List[BaseTool] | Task-specific tools |+| `context` | List[Task] | Dependencies on other task outputs |+| `async_execution` | bool | Non-blocking execution |+| `output_file` | str | File path for results |+| `output_json` | Type[BaseModel] | Pydantic model for JSON output |+| `output_pydantic` | Type[BaseModel] | Pydantic model for structured output |+| `human_input` | bool | Require human review |+| `markdown` | bool | Format output as markdown |+| `callback` | Callable | Post-completion function |+| `guardrail` | Callable or str | Output validation |+| `guardrails` | List | Multiple validation steps |+| `guardrail_max_retries` | int | Retry on validation failure (default: 3) |+| `create_directory` | bool | Auto-create output directories (default: True) |++### Task Dependencies (context)+```python+@task+def analysis_task(self) -> Task:+ return Task(+ config=self.tasks_config["analysis_task"], # type: ignore[index]+ context=[self.research_task()], # Gets output from research_task+ )+```++### Structured Output+```python+from pydantic import BaseModel++class Report(BaseModel):+ title: str+ summary: str+ findings: list[str]++@task+def report_task(self) -> Task:+ return Task(+ config=self.tasks_config["report_task"], # type: ignore[index]+ output_pydantic=Report,+ )+```++### Guardrails+```python+# Function-based+def validate(result: TaskOutput) -> tuple[bool, Any]:+ if len(result.raw.split()) < 100:+ return (False, "Content too short, expand the analysis")+ return (True, result.raw)++# LLM-based (string prompt)+task = Task(..., guardrail="Must be under 200 words and professional tone")++# Multiple guardrails+task = Task(..., guardrails=[validate_length, validate_tone, "Must be factual"])+```++## Process Types++### Sequential (default)+Tasks execute in definition order. Output of one task serves as context for the next.+```python+Crew(agents=..., tasks=..., process=Process.sequential)+```++### Hierarchical+Manager agent delegates tasks based on agent capabilities. Requires `manager_llm` or `manager_agent`.+```python+Crew(+ agents=...,+ tasks=...,+ process=Process.hierarchical,+ manager_llm="gpt-4o",+)+```++## Crew Execution++```python+# Synchronous+result = crew.kickoff(inputs={"topic": "AI"})+print(result.raw) # String output+print(result.pydantic) # Structured output (if configured)+print(result.json_dict) # Dict output+print(result.token_usage) # Token metrics+print(result.tasks_output) # List[TaskOutput]++# Async (native)+result = await crew.akickoff(inputs={"topic": "AI"})++# Batch execution+results = crew.kickoff_for_each(inputs=[{"topic": "AI"}, {"topic": "ML"}])++# Streaming output (v1.8.0+)+crew = Crew(agents=..., tasks=..., stream=True)+streaming = crew.kickoff(inputs={"topic": "AI"})+for chunk in streaming:+ print(chunk.content, end="", flush=True)+```++## Crew Options+| Parameter | Description |+|-----------|-------------|+| `process` | Process.sequential or Process.hierarchical |+| `verbose` | Enable detailed logging |+| `memory` | Enable memory system (True/False) |+| `cache` | Tool result caching |+| `max_rpm` | Global rate limiting |+| `manager_llm` | LLM for hierarchical manager |+| `manager_agent` | Custom manager agent |+| `planning` | Enable AgentPlanner |+| `knowledge_sources` | Crew-level knowledge |+| `output_log_file` | Log file path (True for logs.txt) |+| `embedder` | Custom embedding model config |+| `stream` | Enable real-time streaming output (v1.8.0+) |++---++## Flows++### Basic Flow+```python+from crewai.flow.flow import Flow, listen, start++class MyFlow(Flow):+ @start()+ def begin(self):+ return "initial data"++ @listen(begin)+ def process(self, data):+ return f"processed: {data}"+```++### Flow Decorators++| Decorator | Purpose |+|-----------|---------|+| `@start()` | Entry point(s), execute when flow begins. Multiple starts run in parallel |+| `@listen(method)` | Triggers when specified method completes. Receives output as argument |+| `@router(method)` | Conditional branching. Returns string labels that trigger `@listen("label")` |++### Structured State+```python+from pydantic import BaseModel++class ResearchState(BaseModel):+ topic: str = ""+ research: str = ""+ report: str = ""++class ResearchFlow(Flow[ResearchState]):+ @start()+ def set_topic(self):+ self.state.topic = "AI Agents"++ @listen(set_topic)+ def do_research(self):+ # self.state.topic is available+ result = ResearchCrew().crew().kickoff(+ inputs={"topic": self.state.topic}+ )+ self.state.research = result.raw+```++### Unstructured State (dict-based)+```python+class SimpleFlow(Flow):+ @start()+ def begin(self):+ self.state["counter"] = 0 # Dict access++ @listen(begin)+ def increment(self):+ self.state["counter"] += 1+```++### Conditional Routing+```python+from crewai.flow.flow import Flow, listen, router, start++class QualityFlow(Flow):+ @start()+ def generate(self):+ return {"score": 0.85}++ @router(generate)+ def check_quality(self, result):+ if result["score"] > 0.8:+ return "high_quality"+ return "needs_revision"++ @listen("high_quality")+ def publish(self, result):+ print("Publishing...")++ @listen("needs_revision")+ def revise(self, result):+ print("Revising...")+```++### Parallel Triggers with or_ and and_+```python+from crewai.flow.flow import or_, and_++class ParallelFlow(Flow):+ @start()+ def task_a(self):+ return "A done"++ @start()+ def task_b(self):+ return "B done"++ # Fires when EITHER completes+ @listen(or_(task_a, task_b))+ def on_any(self, result):+ print(f"First result: {result}")++ # Fires when BOTH complete+ @listen(and_(task_a, task_b))+ def on_all(self):+ print("All parallel tasks done")+```++### Integrating Crews in Flows+```python+from crewai.flow.flow import Flow, listen, start+from my_project.crews.research_crew.research_crew import ResearchCrew+from my_project.crews.writing_crew.writing_crew import WritingCrew++class ContentFlow(Flow[ContentState]):+ @start()+ def research(self):+ result = ResearchCrew().crew().kickoff(+ inputs={"topic": self.state.topic}+ )+ self.state.research = result.raw++ @listen(research)+ def write(self):+ result = WritingCrew().crew().kickoff(+ inputs={+ "topic": self.state.topic,+ "research": self.state.research,+ }+ )+ self.state.article = result.raw+```++### Using Agents Directly in Flows+```python+from crewai.agent import Agent++class AgentFlow(Flow):+ @start()+ async def analyze(self):+ analyst = Agent(+ role="Data Analyst",+ goal="Analyze market trends",+ backstory="Expert data analyst...",+ tools=[SerperDevTool()],+ )+ result = await analyst.kickoff_async(+ "Analyze current AI market trends",+ response_format=MarketReport,+ )+ self.state.report = result.pydantic+```++### Human-in-the-Loop (v1.8.0+)+```python+from crewai.flow.flow import Flow, listen, start+from crewai.flow.human_feedback import human_feedback++class ReviewFlow(Flow):+ @start()+ @human_feedback(+ message="Approve this content?",+ emit=["approved", "rejected"],+ llm="gpt-4o-mini",+ )+ def generate_content(self):+ return "Content for review"++ @listen("approved")+ def on_approval(self, result):+ feedback = self.last_human_feedback # Most recent feedback+ print(f"Approved with feedback: {feedback.feedback}")++ @listen("rejected")+ def on_rejection(self, result):+ history = self.human_feedback_history # All feedback as list+ print("Rejected, revising...")+```++### State Persistence+```python+from crewai.flow.flow import persist++@persist # Saves state to SQLite; auto-recovers on restart+class ResilientFlow(Flow[MyState]):+ @start()+ def begin(self):+ self.state.step = 1+```++### Flow Execution+```python+flow = MyFlow()+result = flow.kickoff()+print(result) # Output of last method+print(flow.state) # Final state++# Async execution+result = await flow.kickoff_async(inputs={"key": "value"})+```++### Flow Streaming (v1.8.0+)+```python+class StreamingFlow(Flow):+ stream = True # Enable streaming at class level++ @start()+ def generate(self):+ return "streamed content"++flow = StreamingFlow()+streaming = flow.kickoff()+for chunk in streaming:+ print(chunk.content, end="", flush=True)+result = streaming.result # Final result after iteration+```++### Flow Visualization+```python+flow.plot("my_flow") # Generates my_flow.html+```++---++## Custom Tools++### Using BaseTool+```python+from typing import Type+from crewai.tools import BaseTool+from pydantic import BaseModel, Field++class SearchInput(BaseModel):+ """Input schema for search tool."""+ query: str = Field(..., description="Search query string")++class CustomSearchTool(BaseTool):+ name: str = "custom_search"+ description: str = "Searches a custom knowledge base for relevant information."+ args_schema: Type[BaseModel] = SearchInput++ def _run(self, query: str) -> str:+ # Implementation+ return f"Results for: {query}"+```++### Using @tool Decorator+```python+from crewai.tools import tool++@tool("Calculator")+def calculator(expression: str) -> str:+ """Evaluates a mathematical expression and returns the result."""+ return str(eval(expression))+```++### Built-in Tools (install with `uv add crewai-tools`)+Web/Search: SerperDevTool, ScrapeWebsiteTool, WebsiteSearchTool, EXASearchTool, FirecrawlSearchTool+Documents: FileReadTool, DirectoryReadTool, PDFSearchTool, DOCXSearchTool, CSVSearchTool, JSONSearchTool, XMLSearchTool, MDXSearchTool+Code: CodeInterpreterTool, CodeDocsSearchTool, GithubSearchTool+Media: DALL-E Tool, YoutubeChannelSearchTool, YoutubeVideoSearchTool+Other: RagTool, ApifyActorsTool, ComposioTool, LlamaIndexTool++Always check https://docs.crewai.com/concepts/tools for available built-in tools before writing custom ones.++---++## Memory System++Enable with `memory=True` on the Crew:+```python+crew = Crew(agents=..., tasks=..., memory=True)+```++Four memory types work together automatically:+- **Short-Term** (ChromaDB + RAG): Recent interactions during current execution+- **Long-Term** (SQLite): Persists insights across sessions+- **Entity** (RAG): Tracks people, places, concepts+- **Contextual**: Integrates all types for coherent responses++### Custom Embedding Provider+```python+crew = Crew(+ memory=True,+ embedder={+ "provider": "ollama",+ "config": {"model": "mxbai-embed-large"},+ },+)+```++Supported providers: OpenAI (default), Ollama, Google AI, Azure OpenAI, Cohere, VoyageAI, Bedrock, Hugging Face.++---++## Knowledge System++```python+from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource+from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource++# String source+string_source = StringKnowledgeSource(content="Domain knowledge here...")++# PDF source+pdf_source = PDFKnowledgeSource(file_paths=["docs/manual.pdf"])++# Agent-level knowledge+agent = Agent(..., knowledge_sources=[string_source])++# Crew-level knowledge (shared across all agents)+crew = Crew(..., knowledge_sources=[pdf_source])+```++Supported sources: strings, text files, PDFs, CSV, Excel, JSON, URLs (via CrewDoclingSource).++---++## Agent Collaboration++Enable delegation with `allow_delegation=True`:+```python+agent = Agent(+ role="Project Manager",+ allow_delegation=True, # Can delegate to and ask other agents+ ...+)+```++- **Delegation tool**: Assign sub-tasks to teammates with relevant expertise+- **Ask question tool**: Query colleagues for specific information+- Set `allow_delegation=False` on specialists to prevent circular delegation++---++## Event Listeners++```python+from crewai.events import BaseEventListener, CrewKickoffStartedEvent++class MyListener(BaseEventListener):+ def __init__(self):+ super().__init__()++ def setup_listeners(self, crewai_event_bus):+ @crewai_event_bus.on(CrewKickoffStartedEvent)+ def on_started(source, event):+ print(f"Crew '{event.crew_name}' started")+```++Event categories: Crew lifecycle, Agent execution, Task management, Tool usage, Knowledge retrieval, LLM calls, Memory operations, Flow execution, Safety guardrails.++---++## Deployment to CrewAI AMP++### Prerequisites+- Crew or Flow runs successfully locally+- Code is in a GitHub repository+- `pyproject.toml` has `[tool.crewai]` with correct type (`"crew"` or `"flow"`)+- `uv.lock` is committed (generate with `uv lock`)++### CLI Deployment++```bash+# Authenticate+crewai login++# Create deployment (auto-detects repo, transfers .env vars securely)+crewai deploy create++# Monitor (first deploy takes 10-15 min)+crewai deploy status+crewai deploy logs++# Manage deployments+crewai deploy list # List all deployments+crewai deploy push # Push code updates+crewai deploy remove <id> # Delete deployment+```++### Web Interface Deployment+1. Push code to GitHub+2. Log into https://app.crewai.com+3. Connect GitHub and select repository+4. Configure environment variables (KEY=VALUE, one per line)+5. Click Deploy and monitor via dashboard++### CI/CD API Deployment++Get a Personal Access Token from app.crewai.com β Settings β Account β Personal Access Token.+Get Automation UUID from Automations β Select crew β Additional Details β Copy UUID.++```bash+curl -X POST \+ -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \+ https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy+```++#### GitHub Actions Example+```yaml+name: Deploy CrewAI Automation+on:+ push:+ branches: [main]+jobs:+ deploy:+ runs-on: ubuntu-latest+ steps:+ - name: Trigger CrewAI Redeployment+ run: |+ curl -X POST \+ -H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \+ https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy+```++### Project Structure Requirements for Deployment+- Entry point: `src/<project_name>/main.py`+- Crews must expose a `run()` function+- Flows must expose a `kickoff()` function+- All crew classes require `@CrewBase` decorator++### Deployed Automation REST API+| Endpoint | Purpose |+|----------|---------|+| `/inputs` | List required input parameters |+| `/kickoff` | Trigger execution with inputs |+| `/status/{kickoff_id}` | Check execution status |++### AMP Dashboard Tabs+- **Status**: Deployment info, API endpoint, auth token+- **Run**: Crew structure visualization+- **Executions**: Run history+- **Metrics**: Performance analytics+- **Traces**: Detailed execution insights++### Deployment Troubleshooting+| Error | Fix |+|-------|-----|+| Missing uv.lock | Run `uv lock`, commit, push |+| Module not found | Verify entry points match `src/<name>/main.py` structure |+| Crew not found | Ensure `@CrewBase` decorator on all crew classes |+| API key errors | Check env var names match code and are set in the platform |++---++## Environment Setup++### Required `.env`+```+OPENAI_API_KEY=sk-...+# Optional depending on tools/providers:+SERPER_API_KEY=...+ANTHROPIC_API_KEY=...+# Override default model:+MODEL=gpt-4o+```++### Python Version+Python >=3.10, <3.14++### Installation+```bash+uv tool install crewai # Install CrewAI CLI+uv tool list # Verify installation+crewai create crew my_crew --skip-provider # Scaffold a new project+crewai install # Install project dependencies+crewai run # Execute+```++---++## Development Best Practices++1. **YAML-first configuration**: Define agents and tasks in YAML, keep crew classes minimal+2. **Check built-in tools** before writing custom ones+3. **Use structured output** (output_pydantic) for data that flows between tasks or crews+4. **Use guardrails** to validate task outputs programmatically+5. **Enable memory** for crews that benefit from cross-session learning+6. **Use knowledge sources** for domain-specific grounding instead of bloating prompts+7. **Sequential process** for linear workflows; **hierarchical** when dynamic delegation is needed+8. **Flows for multi-crew orchestration**: Use `@start`, `@listen`, `@router` for complex pipelines+9. **Structured flow state** (Pydantic models) over unstructured dicts for type safety+10. **Test with** `crewai test` to evaluate crew performance across iterations+11. **Verbose mode** during development, disable in production+12. **Rate limiting** (`max_rpm`) to avoid API throttling+13. **`respect_context_window=True`** to auto-handle token limits++## Common Pitfalls++- **Using `ChatOpenAI()`** β Always use `crewai.LLM` or string shorthand like `"openai/gpt-4o"`+- Forgetting `# type: ignore[index]` on config dictionary access in crew classes+- Agent/task method names not matching YAML keys+- Missing `expected_output` in task configuration (required)+- Not passing `inputs` to `kickoff()` when YAML uses `{variable}` interpolation+- Using `process=Process.hierarchical` without setting `manager_llm` or `manager_agent`+- Circular delegation: set `allow_delegation=False` on specialist agents+- Not installing tools package: `uv add crewai-tools`diff --git a/lib/crewai/src/crewai/cli/tools/main.py b/lib/crewai/src/crewai/cli/tools/main.pyindex 37467a906..e2dd21dde 100644--- a/lib/crewai/src/crewai/cli/tools/main.py+++ b/lib/crewai/src/crewai/cli/tools/main.py@@ -2,6 +2,7 @@ import base64from json import JSONDecodeErrorimport osfrom pathlib import Path+import shutilimport subprocessimport tempfilefrom typing import Any@@ -55,6 +56,11 @@ class ToolCommand(BaseCommand, PlusAPIMixin):tree_find_and_replace(project_root, "{{folder_name}}", folder_name)tree_find_and_replace(project_root, "{{class_name}}", class_name)+ # Copy AGENTS.md to project root+ agents_md_src = Path(__file__).parent.parent / "templates" / "AGENTS.md"+ if agents_md_src.exists():+ shutil.copy2(agents_md_src, project_root / "AGENTS.md")+old_directory = os.getcwd()os.chdir(project_root)try: