chore: Update Tasks.md documentation to include example of using output JSON in tasks

[leandrosilvaferreira]

The documentation in Tasks.md was updated to include an example of how to use the output_json parameter in task definitions. This allows for specifying that the output of a task should be in JSON format. The example demonstrates how to define a task that searches for local companies and outputs the results in a JSON format according to a predefined schema using Pydantic models.

This fix improves the clarity and comprehensiveness of the documentation, making it easier for users to understand and utilize the output_json parameter. It also ensures consistency in the documentation and code examples.

Note: The modifications made to the Tasks.md file are the only ones relevant to this commit message.

[github-actions[bot]]

This PR is stale because it has been open for 45 days with no activity.

[joaomdmoura]

Disclaimer: This review was made by a crew of AI Agents.

Code Review Comment for PR #746

Overview

The changes in this PR enhance the Tasks.md documentation by integrating examples for using output JSON in tasks and improving the documentation around the tool override mechanism. The proposed modifications significantly improve the clarity and usability of the documentation.

Strengths

1. Clear Example Implementation: The new integration of Pydantic models in the examples provides a solid understanding of how to manage JSON outputs in tasks.
2. Well-Structured Output Example: The inclusion of a sample JSON output enhances the reader's grasp of the expected output structure, making it tangible for implementation.
3. Good Content Integration: The updates flow well with the existing documentation, making for a cohesive reading experience.

Areas for Improvement

1. Missing Import Statements:

   • To ensure users have a complete view, add the necessary import statements at the top of the file:

     from crewai import Task, Crew
     from typing import List
     from pydantic import BaseModel
     

2. Error Handling Documentation:

   • It's essential to address how error handling works with output_json and Pydantic validation. Consider documenting it as follows:

     ### Error Handling with JSON Output
     
     When using `output_json`, the task validates the output against the provided Pydantic model. If validation fails, an exception is raised.
     

3. Type Hints in Examples:

   • Enhancing clarity through type hints in your example code will greatly aid users:

     task_search_companies: Task = Task(
         description='Search for local companies...',
         expected_output='List of companies...',
         agent=search_agent,
         tools=[search_tool],
         async_execution=False,
         output_json=CompanyList,
         output_file='companies.json'
     )
     

4. Document Optional Parameters:

   • Outlining optional parameters will help users better understand their choices:

     ### Optional Parameters for JSON Output Tasks
     
     - `output_file`: (Optional) Specify a path for saving the JSON output.
     - `async_execution`: (Optional) Set to `True` for asynchronous execution.
     

5. Complex Nested Models Example:

   • Including examples for complex data structures will benefit users needing advanced usage patterns:

     class Location(BaseModel):
         latitude: float
         longitude: float
         address: str
     
     class CompanyData(BaseModel):
         Name: str
         Address: str
         Phone: str
         Website: str
         Email: str
         location: Location
     

Technical Recommendations

1. Validation Configuration:

   • Documenting customization options for Pydantic's validation will improve usability:

     ### Configuring JSON Validation
     
     Customize validation behavior through Pydantic's Config classes.
     

2. Customizing Error Messages:

   • Suggesting methods to tailor error messages can enhance user-friendliness:

     class CompanyData(BaseModel):
         Name: str = Field(..., description="Company's legal name")
     

General Suggestions

1. Include a troubleshooting section for common JSON output issues.
2. Discuss performance considerations when using JSON validation.
3. Ensure cross-references to related documentation sections for better navigation.
4. Provide more real-world examples to illustrate practical applications of the discussed features.
5. Document JSON schema compatibility to showcase extensibility.

Conclusion

The adjustments made significantly enhance the understanding of JSON output functionality in CrewAI tasks. The documentation now offers clearer guidance and practical implementations. Implementing the suggested enhancements will address the identified gaps and strengthen the resource for users at varying levels of expertise. These changes will ultimately improve the overall user experience by providing comprehensive guidance on implementing JSON output in CrewAI tasks.

Impact Assessment

• 🟢 Documentation Clarity: High
• 🟢 Technical Accuracy: High
• 🟡 Completeness: Medium (can be improved with suggested additions)
• 🟢 Example Quality: High

Your efforts in enhancing the documentation are commendable, and I look forward to seeing the implementation of the recommendations!

[pythonbyte]

Hey @leandrosilvaferreira, thanks for your pull request!

When you get a chance, could you take a look at the comment from the Crew above? Also, we’ve made some exciting updates to our documentation (docs.crewai.com/) and moved around a few files. It would be awesome if you could check whether your PR is still relevant to these changes.

Thanks

[github-actions[bot]]

This PR is stale because it has been open for 45 days with no activity.