docs: improve docs about planning LLM usage

[lucasgomide]

Closes #2647

[joaomdmoura]

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

Code Review Comment for PR #2977

Overview

The documentation update in PR #2977 enhances docs/concepts/planning.mdx by incorporating a critical warning about the default LLM used when planning with crewAI. This addition effectively alerts users to the requirement of a valid OpenAI API key, which is crucial for avoiding potential confusion and errors in LLM interactions.

Positive Aspects

1. Helpful Warning Message: The warning about API key necessities is valuable for user guidance.
2. Logical Placement: The warning appears immediately after setup instructions, ensuring it is seen at an appropriate moment in the user workflow.
3. Best Practices: The implementation of the <Warning> component adheres to documentation best practices for emphasizing important information.

Suggestions for Improvement

1. Clarity and Accuracy

The warning message could benefit from a clearer and corrected text:

<Warning>
When planning is enabled, crewAI uses `gpt-4-turbo` as the default planning LLM, which requires an OpenAI API key. If you're using different LLMs for your agents but haven't configured an OpenAI API key, you may encounter unexpected errors during the planning phase. To avoid this, either:
- Configure a valid OpenAI API key
- Specify a custom planning LLM (see "Planning LLM" section below)
</Warning>

• This revision clarifies the LLM being used and adds actionable steps to mitigate issues.

2. Context Enhancement

Consider adding practical examples for configuring a custom planning LLM just after the "Planning LLM" heading:

#### Planning LLM

You can customize the LLM used for planning tasks by configuring it in your Crew initialization:

```python
from crewai import Crew
from langchain.llms import HuggingFaceHub

custom_planner = HuggingFaceHub(repo_id="mistralai/Mistral-7B-Instruct-v0.1")

my_crew = Crew(
    agents=[agent1, agent2],
    tasks=[task1, task2],
    planning=True,
    planning_llm=custom_planner
)

• Adding code examples enhances user understanding and usability.

3. Additional Recommendations

• Incorporate a troubleshooting segment addressing common issues users might face regarding planning and API key configurations.
• Include details about the minimum required capabilities for LLMs used in planning to set clear expectations.
• Suggest mentioning the performance implications related to various LLM choices to assist users in making informed decisions.

Formatting and Style

• The warning text is mostly well formatted. However, it contains a typo in referring to gpt-4o-mini, which should be corrected to gpt-4-turbo.
• The usage of the <Warning> component aligns with MDX conventions, and the overall document maintains consistent indentation and spacing.

Security Considerations

• The update appropriately highlights the requirement for an API key.
• It could be useful to add a section on API key security best practices to protect user credentials.

Summary

The changes in this PR significantly enhance the documentation by providing an essential warning about API keys and planning LLM configurations. By implementing the suggested improvements, the overall documentation can become more comprehensive, user-friendly, and informative, ensuring that users navigate the complexities of LLM configurations within crewAI seamlessly.

For additional insights, I recommend reviewing related PRs that modified the docs/concepts/planning.mdx file to gather historical context and surface any user feedback incorporated in this update. This will help align our documentation more closely with user experiences and expectations.