8000 docs: update agent and task documentation with new parameters by tonykipkemboi · Pull Request #2891 · crewAIInc/crewAI · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

docs: update agent and task documentation with new parameters #2891

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 3 commits into from
May 22, 2025
Merged

docs: update agent and task documentation with new parameters #2891

merged 3 commits into from
May 22, 2025

Conversation

tonykipkemboi
Copy link
Contributor

Documentation Improvements:
✅ Updated Task Attributes table
✅ Added comprehensive "Markdown Output Formatting" section
✅ Updated YAML and Python code examples to show markdown usage
✅ Explained benefits and use cases for markdown formatting
✅ Added automatic formatting instructions details

@tonykipkemboi
Update agent and task documentation with new parameters - Add new Age…
81070f3 
…nt parameters: multimodal, allow_feedback, allow_conflict, allow_iteration, embedder_config - Add new Task parameter: markdown for automatic formatting - Update documentation examples and usage patterns - Add comprehensive sections for advanced collaboration features and markdown formatting
@joaomdmoura
Copy link
Collaborator

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

Code Review Comment for PR #2891

Overview

This pull request brings valuable updates to the documentation for agents.mdx and tasks.mdx within the CrewAI framework, focusing on clarity and the introduction of new parameters. The resulting improvements enhance usability and guide users towards more effective usage of the framework components.

Detailed Code Improvements

1. agents.mdx

Positive Aspects

  • Structured Parameter Documentation: The organization of parameters is coherent and user-friendly.
  • Examples: Inclusion of practical examples aids in comprehension.
  • Thoroughness: New features are well-documented, promoting understanding.

Concerns and Recommendations

  1. Parameter Grouping:

    • Issue: The parameters can benefit from logical grouping to enhance readability.

    • Suggestion: Consider restructuring as follows:

      Collaboration Parameters
      Multimodal
      Allow Feedback
      Allow Conflict
      Allow Iteration
      Core Configuration
      Role
      Goal
      Backstory

  2. Type Definitions:

    • Issue: The type hinting for embedder_config lacks specificity.
    • Suggestion: Utilize clearer type hints: 
      embedder_config: Optional[Dict[str, Union[str, int, float, bool]]]

  3. Enhance Examples:

    • Issue: Examples do not address error handling.
    • Suggestion: Implement an error handler in the collaborative agent example: 
      collaborative_agent = Agent(
    role="Senior Researcher",
    goal="Conduct comprehensive research with iterative improvements",
    backstory="Expert researcher who values feedback and collaborative refinement",
    allow_feedback=True,
    allow_conflict=True,
    allow_iteration=True,
    max_iter=30,
    verbose=True,
    error_handler=lambda e: print(f"Collaboration error: {e}"),
    max_retry_limit=3
)

2. tasks.mdx

Positive Aspects

  • Effective Parameter Documentation: Clearly defined parameters assist users in understanding task configurations.
  • Markdown Compatibility: The inclusion of a markdown parameter enriches output formatting capabilities.

Concerns and Recommendations

  1. Markdown Parameter Validation:

    • Issue: Current validations for the markdown attribute are insufficient.
    • Suggestion: Integrate validation logic to ensure proper markdown formatting: 
      class TaskOutput(BaseModel):
    content: str
    is_markdown: bool

    @validator('content')
    def validate_markdown(cls, v, values):
        if values.get('is_markdown'):
            if not v.startswith('#') and not any(['##' in v, '- ' in v, '*' in v]):
                raise ValueError("Invalid markdown format")
        return v

  2. Output File Handling:

    • Issue: There is a lack of output file extension validation.
    • Suggestion: Ensure the correct file extension when markdown is specified: 
      def validate_output_file(output_file: Optional[str], markdown: bool) -> str:
    if output_file:
        if markdown and not output_file.endswith(('.md', '.mdx')):
            raise ValueError("Markdown output requires .md or .mdx extension")
    return output_file

  3. Example Enhancements:

    • Issue: Examples would be more effective with error handling included.
    • Suggestion: Revamp task examples to encapsulate error management: 
      formatted_task = Task(
    description="Create a comprehensive report on AI trends",
    expected_output="A well-structured report with headers, sections, and bullet points",
    agent=reporter_agent,
    markdown=True,
    config={
        'markdown_validation': True,
        'allowed_tags': ['h1', 'h2', 'h3', 'ul', 'ol', 'code'],
        'max_depth': 3
    },
    error_handler=lambda e: print(f"Markdown formatting error: {e}")
)

General Recommendations

  1. Documentation Structure:

    • Suggestion: Add a table of contents for each file to assist navigation.
    • Suggestion: Incorporate cross-references between sections to bolster interconnected understanding.

  2. Code Example Improvements:

    • Suggestion: Ensure consistent addition of type hints and error handling scenarios across all examples.
    • Suggestion: Enhance the relevance of examples with real-world use cases.

  3. Testing Considerations:

    • Recommendation: Provide documentation for testing newly introduced features, particularly for output formatting validations: 
      # Testing markdown output
def test_markdown_output(task_output):
    assert task_output.startswith('#')
    assert '##' in task_output
    assert any(['- ' in line for line in task_output.split('\n')])

Conclusion

The updates within this pull request significantly improve the documentation for the CrewAI framework, indicating thoughtful enhancements. Addressing the outlined recommendations concerning parameter organization, type safety, and error handling will further augment the usability and reliability of the agents and tasks functionalities. Thank you for your contributions!

@tonykipkemboi tonykipkemboi reopened this May 22, 2025
lorenzejay
lorenzejay requested changes May 22, 2025
View reviewed changes
8000 docs/concepts/agents.mdx Outdated
| **Allow Feedback** _(optional)_ | `allow_feedback` | `bool` | Enable agent to receive and process feedback during execution. Default is False. |
| **Allow Conflict** _(optional)_ | `allow_conflict` | `bool` | Enable agent to handle conflicts with other agents during execution. Default is False. |
| **Allow Iteration** _(optional)_ | `allow_iteration` | `bool` | Enable agent to iterate on its solutions based on feedback and validation. Default is False. |
| **Embedder Config** _(optional)_ | `embedder_config` | `Optional[Dict[str, Any]]` | Configuration for the embedder used by the agent. |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think its still just embedder. can we double check this one

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah yes!

@tonykipkemboi
Fix agent documentation: remove non-existent parameters and add missi…
df42ac7 
…ng ones - Remove incorrect parameters: allow_feedback, allow_conflict, allow_iteration - Add actual parameters: inject_date, date_format, reasoning, max_reasoning_attempts - Fix embedder_config to embedder to match source code - Update examples and best practices with correct parameters
@tonykipkemboi tonykipkemboi requested a review from lorenzejay May 22, 2025 21:47
@tonykipkemboi tonykipkemboi merged commit 2d6deee into crewAIInc:main May 22, 2025
6 checks passed
didier-durand pushed a commit to didier-durand/crewAI that referenced this pull request Jun 12, 2025
@tonykipkemboi @didier-durand
docs: update agent and task documentation with new parameters (crewAI…
22cad2f 
…Inc#2891)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@lorenzejay lorenzejay lorenzejay approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@tonykipkemboi @joaomdmoura @lorenzejay
0