Adding HITL for Flows (#4143)

* feat: introduce human feedback events and decorator for flow methods

- Added HumanFeedbackRequestedEvent and HumanFeedbackReceivedEvent classes to handle human feedback interactions within flows.
- Implemented the @human_feedback decorator to facilitate human-in-the-loop workflows, allowing for feedback collection and routing based on responses.
- Enhanced Flow class to store human feedback history and manage feedback outcomes.
- Updated flow wrappers to preserve attributes from methods decorated with @human_feedback.
- Added integration and unit tests for the new human feedback functionality, ensuring proper validation and routing behavior.

* adding deployment docs

* New docs

* fix printer

* wrong change

* Adding Async Support
feat: enhance human feedback support in flows

- Updated the @human_feedback decorator to use 'message' parameter instead of 'request' for clarity.
- Introduced new FlowPausedEvent and MethodExecutionPausedEvent to handle flow and method pauses during human feedback.
- Added ConsoleProvider for synchronous feedback collection and integrated async feedback capabilities.
- Implemented SQLite persistence for managing pending feedback context.
- Expanded documentation to include examples of async human feedback usage and best practices.

* linter

* fix

* migrating off printer

* updating docs

* new tests

* doc update

.github/workflows/publish.yml

@@ -1,9 +1,14 @@
 name: Publish to PyPI
 
 on:
-  release:
-    types: [ published ]
+  repository_dispatch:
+    types: [deployment-tests-passed]
   workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Release tag to publish'
+        required: false
+        type: string
 
 jobs:
   build:
@@ -12,7 +17,21 @@ jobs:
     permissions:
         contents: read
     steps:
+      - name: Determine release tag
+        id: release
+        run: |
+          # Priority: workflow_dispatch input > repository_dispatch payload > default branch
+          if [ -n "${{ inputs.release_tag }}" ]; then
+            echo "tag=${{ inputs.release_tag }}" >> $GITHUB_OUTPUT
+          elif [ -n "${{ github.event.client_payload.release_tag }}" ]; then
+            echo "tag=${{ github.event.client_payload.release_tag }}" >> $GITHUB_OUTPUT
+          else
+            echo "tag=" >> $GITHUB_OUTPUT
+          fi
+
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.release.outputs.tag || github.ref }}
 
       - name: Set up Python
         uses: actions/setup-python@v5

.github/workflows/trigger-deployment-tests.yml

@@ -0,0 +1,18 @@
+name: Trigger Deployment Tests
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  trigger:
+    name: Trigger deployment tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger deployment tests
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.CREWAI_DEPLOYMENTS_PAT }}
+          repository: ${{ secrets.CREWAI_DEPLOYMENTS_REPOSITORY }}
+          event-type: crewai-release
+          client-payload: '{"release_tag": "${{ github.event.release.tag_name }}", "release_name": "${{ github.event.release.name }}"}'

.pre-commit-config.yaml

@@ -24,4 +24,10 @@ repos:
     rev: 0.9.3
     hooks:
       - id: uv-lock
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.10.1
+    hooks:
+      - id: commitizen
+      - id: commitizen-branch
+        stages: [ pre-push ]
 

docs/docs.json

@@ -308,6 +308,7 @@
                   "en/learn/hierarchical-process",
                   "en/learn/human-input-on-execution",
                   "en/learn/human-in-the-loop",
+                  "en/learn/human-feedback-in-flows",
                   "en/learn/kickoff-async",
                   "en/learn/kickoff-for-each",
                   "en/learn/llm-connections",
@@ -735,6 +736,7 @@
                   "pt-BR/learn/hierarchical-process",
                   "pt-BR/learn/human-input-on-execution",
                   "pt-BR/learn/human-in-the-loop",
+                  "pt-BR/learn/human-feedback-in-flows",
                   "pt-BR/learn/kickoff-async",
                   "pt-BR/learn/kickoff-for-each",
                   "pt-BR/learn/llm-connections",
@@ -1171,6 +1173,7 @@
                   "ko/learn/hierarchical-process",
                   "ko/learn/human-input-on-execution",
                   "ko/learn/human-in-the-loop",
+                  "ko/learn/human-feedback-in-flows",
                   "ko/learn/kickoff-async",
                   "ko/learn/kickoff-for-each",
                   "ko/learn/llm-connections",

docs/en/api-reference/introduction.mdx

@@ -16,16 +16,17 @@ Welcome to the CrewAI AOP API reference. This API allows you to programmatically
     Navigate to your crew's detail page in the CrewAI AOP dashboard and copy your Bearer Token from the Status tab.
   </Step>
 
-  <Step title="Discover Required Inputs">
-    Use the `GET /inputs` endpoint to see what parameters your crew expects.
-  </Step>
+<Step title="Discover Required Inputs">
+  Use the `GET /inputs` endpoint to see what parameters your crew expects.
+</Step>
 
-  <Step title="Start a Crew Execution">
-    Call `POST /kickoff` with your inputs to start the crew execution and receive a `kickoff_id`.
-  </Step>
+<Step title="Start a Crew Execution">
+  Call `POST /kickoff` with your inputs to start the crew execution and receive
+  a `kickoff_id`.
+</Step>
 
   <Step title="Monitor Progress">
-    Use `GET /status/{kickoff_id}` to check execution status and retrieve results.
+    Use `GET /{kickoff_id}/status` to check execution status and retrieve results.
   </Step>
 </Steps>
 
@@ -40,13 +41,14 @@ curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \
 
 ### Token Types
 
-| Token Type | Scope | Use Case |
-|:-----------|:--------|:----------|
-| **Bearer Token** | Organization-level access | Full crew operations, ideal for server-to-server integration |
-| **User Bearer Token** | User-scoped access | Limited permissions, suitable for user-specific operations |
+| Token Type            | Scope                     | Use Case                                                     |
+| :-------------------- | :------------------------ | :----------------------------------------------------------- |
+| **Bearer Token**      | Organization-level access | Full crew operations, ideal for server-to-server integration |
+| **User Bearer Token** | User-scoped access        | Limited permissions, suitable for user-specific operations   |
 
 <Tip>
-You can find both token types in the Status tab of your crew's detail page in the CrewAI AOP dashboard.
+  You can find both token types in the Status tab of your crew's detail page in
+  the CrewAI AOP dashboard.
 </Tip>
 
 ## Base URL
@@ -63,29 +65,33 @@ Replace `your-crew-name` with your actual crew's URL from the dashboard.
 
 1. **Discovery**: Call `GET /inputs` to understand what your crew needs
 2. **Execution**: Submit inputs via `POST /kickoff` to start processing
-3. **Monitoring**: Poll `GET /status/{kickoff_id}` until completion
+3. **Monitoring**: Poll `GET /{kickoff_id}/status` until completion
 4. **Results**: Extract the final output from the completed response
 
 ## Error Handling
 
 The API uses standard HTTP status codes:
 
-| Code | Meaning |
-|------|:--------|
-| `200` | Success |
-| `400` | Bad Request - Invalid input format |
-| `401` | Unauthorized - Invalid bearer token |
-| `404` | Not Found - Resource doesn't exist |
+| Code  | Meaning                                    |
+| ----- | :----------------------------------------- |
+| `200` | Success                                    |
+| `400` | Bad Request - Invalid input format         |
+| `401` | Unauthorized - Invalid bearer token        |
+| `404` | Not Found - Resource doesn't exist         |
 | `422` | Validation Error - Missing required inputs |
-| `500` | Server Error - Contact support |
+| `500` | Server Error - Contact support             |
 
 ## Interactive Testing
 
 <Info>
-**Why no "Send" button?** Since each CrewAI AOP user has their own unique crew URL, we use **reference mode** instead of an interactive playground to avoid confusion. This shows you exactly what the requests should look like without non-functional send buttons.
+  **Why no "Send" button?** Since each CrewAI AOP user has their own unique crew
+  URL, we use **reference mode** instead of an interactive playground to avoid
+  confusion. This shows you exactly what the requests should look like without
+  non-functional send buttons.
 </Info>
 
 Each endpoint page shows you:
+
 - ✅ **Exact request format** with all parameters
 - ✅ **Response examples** for success and error cases
 - ✅ **Code samples** in multiple languages (cURL, Python, JavaScript, etc.)
@@ -103,6 +109,7 @@ Each endpoint page shows you:
 </CardGroup>
 
 **Example workflow:**
+
 1. **Copy this cURL example** from any endpoint page
 2. **Replace `your-actual-crew-name.crewai.com`** with your real crew URL
 3. **Replace the Bearer token** with your real token from the dashboard
@@ -111,10 +118,18 @@ Each endpoint page shows you:
 ## Need Help?
 
 <CardGroup cols={2}>
-  <Card title="Enterprise Support" icon="headset" href="mailto:support@crewai.com">
+  <Card
+    title="Enterprise Support"
+    icon="headset"
+    href="mailto:support@crewai.com"
+  >
     Get help with API integration and troubleshooting
   </Card>
-  <Card title="Enterprise Dashboard" icon="chart-line" href="https://app.crewai.com">
+  <Card
+    title="Enterprise Dashboard"
+    icon="chart-line"
+    href="https://app.crewai.com"
+  >
     Manage your crews and view execution logs
   </Card>
 </CardGroup>

docs/en/api-reference/status.mdx

@@ -1,8 +1,6 @@
 ---
-title: "GET /status/{kickoff_id}"
+title: "GET /{kickoff_id}/status"
 description: "Get execution status"
-openapi: "/enterprise-api.en.yaml GET /status/{kickoff_id}"
+openapi: "/enterprise-api.en.yaml GET /{kickoff_id}/status"
 mode: "wide"
 ---
-
-

docs/en/concepts/flows.mdx

@@ -572,6 +572,55 @@ The `third_method` and `fourth_method` listen to the output of the `second_metho
 
 When you run this Flow, the output will change based on the random boolean value generated by the `start_method`.
 
+### Human in the Loop (human feedback)
+
+The `@human_feedback` decorator enables human-in-the-loop workflows by pausing flow execution to collect feedback from a human. This is useful for approval gates, quality review, and decision points that require human judgment.
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
+
+class ReviewFlow(Flow):
+    @start()
+    @human_feedback(
+        message="Do you approve this content?",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+    )
+    def generate_content(self):
+        return "Content to be reviewed..."
+
+    @listen("approved")
+    def on_approval(self, result: HumanFeedbackResult):
+        print(f"Approved! Feedback: {result.feedback}")
+
+    @listen("rejected")
+    def on_rejection(self, result: HumanFeedbackResult):
+        print(f"Rejected. Reason: {result.feedback}")
+```
+
+When `emit` is specified, the human's free-form feedback is interpreted by an LLM and collapsed into one of the specified outcomes, which then triggers the corresponding `@listen` decorator.
+
+You can also use `@human_feedback` without routing to simply collect feedback:
+
+```python Code
+@start()
+@human_feedback(message="Any comments on this output?")
+def my_method(self):
+    return "Output for review"
+
+@listen(my_method)
+def next_step(self, result: HumanFeedbackResult):
+    # Access feedback via result.feedback
+    # Access original output via result.output
+    pass
+```
+
+Access all feedback collected during a flow via `self.last_human_feedback` (most recent) or `self.human_feedback_history` (all feedback as a list).
+
+For a complete guide on human feedback in flows, including **async/non-blocking feedback** with custom providers (Slack, webhooks, etc.), see [Human Feedback in Flows](/en/learn/human-feedback-in-flows).
+
 ## Adding Agents to Flows
 
 Agents can be seamlessly integrated into your flows, providing a lightweight alternative to full Crews when you need simpler, focused task execution. Here's an example of how to use an Agent within a flow to perform market research:

docs/en/enterprise/guides/deploy-crew.mdx

@@ -187,6 +187,97 @@ You can also deploy your crews directly through the CrewAI AOP web interface by
 
 </Steps>
 
+## Option 3: Redeploy Using API (CI/CD Integration)
+
+For automated deployments in CI/CD pipelines, you can use the CrewAI API to trigger redeployments of existing crews. This is particularly useful for GitHub Actions, Jenkins, or other automation workflows.
+
+<Steps>
+  <Step title="Get Your Personal Access Token">
+
+    Navigate to your CrewAI AOP account settings to generate an API token:
+
+    1. Go to [app.crewai.com](https://app.crewai.com)
+    2. Click on **Settings** → **Account** → **Personal Access Token**
+    3. Generate a new token and copy it securely
+    4. Store this token as a secret in your CI/CD system
+
+  </Step>
+
+  <Step title="Find Your Automation UUID">
+
+    Locate the unique identifier for your deployed crew:
+
+    1. Go to **Automations** in your CrewAI AOP dashboard
+    2. Select your existing automation/crew
+    3. Click on **Additional Details**
+    4. Copy the **UUID** - this identifies your specific crew deployment
+
+  </Step>
+
+  <Step title="Trigger Redeployment via API">
+
+    Use the Deploy API endpoint to trigger a redeployment:
+
+    ```bash
+    curl -i -X POST \
+         -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
+         https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy
+
+    # HTTP/2 200
+    # content-type: application/json
+    #
+    # {
+    #   "uuid": "your-automation-uuid",
+    #   "status": "Deploy Enqueued",
+    #   "public_url": "https://your-crew-deployment.crewai.com",
+    #   "token": "your-bearer-token"
+    # }
+    ```
+
+    <Info>
+    If your automation was first created connected to Git, the API will automatically pull the latest changes from your repository before redeploying.
+    </Info>
+
+
+  </Step>
+
+  <Step title="GitHub Actions Integration Example">
+
+    Here's a GitHub Actions workflow with more complex deployment triggers:
+
+    ```yaml
+    name: Deploy CrewAI Automation
+
+    on:
+      push:
+        branches: [ main ]
+      pull_request:
+        types: [ labeled ]
+      release:
+        types: [ published ]
+
+    jobs:
+      deploy:
+        runs-on: ubuntu-latest
+        if: |
+          (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+          (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) ||
+          (github.event_name == 'release')
+        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
+    ```
+
+    <Tip>
+    Add `CREWAI_PAT` and `CREWAI_AUTOMATION_UUID` as repository secrets. For PR deployments, add a "deploy" label to trigger the workflow.
+    </Tip>
+
+    </Step>
+  </Steps>
+
 ## ⚠️ Environment Variable Security Requirements
 
 <Warning>

docs/en/enterprise/guides/gmail-trigger.mdx

@@ -62,13 +62,13 @@ Test your Gmail trigger integration locally using the CrewAI CLI:
 crewai triggers list
 
 # Simulate a Gmail trigger with realistic payload
-crewai triggers run gmail/new_email
+crewai triggers run gmail/new_email_received
 ```
 
 The `crewai triggers run` command will execute your crew with a complete Gmail payload, allowing you to test your parsing logic before deployment.
 
 <Warning>
-  Use `crewai triggers run gmail/new_email` (not `crewai run`) to simulate trigger execution during development. After deployment, your crew will automatically receive the trigger payload.
+  Use `crewai triggers run gmail/new_email_received` (not `crewai run`) to simulate trigger execution during development. After deployment, your crew will automatically receive the trigger payload.
 </Warning>
 
 ## Monitoring Executions
@@ -83,6 +83,6 @@ Track history and performance of triggered runs:
 
 - Ensure Gmail is connected in Tools & Integrations
 - Verify the Gmail Trigger is enabled on the Triggers tab
-- Test locally with `crewai triggers run gmail/new_email` to see the exact payload structure
+- Test locally with `crewai triggers run gmail/new_email_received` to see the exact payload structure
 - Check the execution logs and confirm the payload is passed as `crewai_trigger_payload`
 - Remember: use `crewai triggers run` (not `crewai run`) to simulate trigger execution

docs/en/learn/human-feedback-in-flows.mdx

@@ -0,0 +1,581 @@
+---
+title: Human Feedback in Flows
+description: Learn how to integrate human feedback directly into your CrewAI Flows using the @human_feedback decorator
+icon: user-check
+mode: "wide"
+---
+
+## Overview
+
+The `@human_feedback` decorator enables human-in-the-loop (HITL) workflows directly within CrewAI Flows. It allows you to pause flow execution, present output to a human for review, collect their feedback, and optionally route to different listeners based on the feedback outcome.
+
+This is particularly valuable for:
+
+- **Quality assurance**: Review AI-generated content before it's used downstream
+- **Decision gates**: Let humans make critical decisions in automated workflows
+- **Approval workflows**: Implement approve/reject/revise patterns
+- **Interactive refinement**: Collect feedback to improve outputs iteratively
+
+```mermaid
+flowchart LR
+    A[Flow Method] --> B[Output Generated]
+    B --> C[Human Reviews]
+    C --> D{Feedback}
+    D -->|emit specified| E[LLM Collapses to Outcome]
+    D -->|no emit| F[HumanFeedbackResult]
+    E --> G["@listen('approved')"]
+    E --> H["@listen('rejected')"]
+    F --> I[Next Listener]
+```
+
+## Quick Start
+
+Here's the simplest way to add human feedback to a flow:
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback
+
+class SimpleReviewFlow(Flow):
+    @start()
+    @human_feedback(message="Please review this content:")
+    def generate_content(self):
+        return "This is AI-generated content that needs review."
+
+    @listen(generate_content)
+    def process_feedback(self, result):
+        print(f"Content: {result.output}")
+        print(f"Human said: {result.feedback}")
+
+flow = SimpleReviewFlow()
+flow.kickoff()
+```
+
+When this flow runs, it will:
+1. Execute `generate_content` and return the string
+2. Display the output to the user with the request message
+3. Wait for the user to type feedback (or press Enter to skip)
+4. Pass a `HumanFeedbackResult` object to `process_feedback`
+
+## The @human_feedback Decorator
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `message` | `str` | Yes | The message shown to the human alongside the method output |
+| `emit` | `Sequence[str]` | No | List of possible outcomes. Feedback is collapsed to one of these, which triggers `@listen` decorators |
+| `llm` | `str \| BaseLLM` | When `emit` specified | LLM used to interpret feedback and map to an outcome |
+| `default_outcome` | `str` | No | Outcome to use if no feedback provided. Must be in `emit` |
+| `metadata` | `dict` | No | Additional data for enterprise integrations |
+| `provider` | `HumanFeedbackProvider` | No | Custom provider for async/non-blocking feedback. See [Async Human Feedback](#async-human-feedback-non-blocking) |
+
+### Basic Usage (No Routing)
+
+When you don't specify `emit`, the decorator simply collects feedback and passes a `HumanFeedbackResult` to the next listener:
+
+```python Code
+@start()
+@human_feedback(message="What do you think of this analysis?")
+def analyze_data(self):
+    return "Analysis results: Revenue up 15%, costs down 8%"
+
+@listen(analyze_data)
+def handle_feedback(self, result):
+    # result is a HumanFeedbackResult
+    print(f"Analysis: {result.output}")
+    print(f"Feedback: {result.feedback}")
+```
+
+### Routing with emit
+
+When you specify `emit`, the decorator becomes a router. The human's free-form feedback is interpreted by an LLM and collapsed into one of the specified outcomes:
+
+```python Code
+@start()
+@human_feedback(
+    message="Do you approve this content for publication?",
+    emit=["approved", "rejected", "needs_revision"],
+    llm="gpt-4o-mini",
+    default_outcome="needs_revision",
+)
+def review_content(self):
+    return "Draft blog post content here..."
+
+@listen("approved")
+def publish(self, result):
+    print(f"Publishing! User said: {result.feedback}")
+
+@listen("rejected")
+def discard(self, result):
+    print(f"Discarding. Reason: {result.feedback}")
+
+@listen("needs_revision")
+def revise(self, result):
+    print(f"Revising based on: {result.feedback}")
+```
+
+<Tip>
+The LLM uses structured outputs (function calling) when available to guarantee the response is one of your specified outcomes. This makes routing reliable and predictable.
+</Tip>
+
+## HumanFeedbackResult
+
+The `HumanFeedbackResult` dataclass contains all information about a human feedback interaction:
+
+```python Code
+from crewai.flow.human_feedback import HumanFeedbackResult
+
+@dataclass
+class HumanFeedbackResult:
+    output: Any              # The original method output shown to the human
+    feedback: str            # The raw feedback text from the human
+    outcome: str | None      # The collapsed outcome (if emit was specified)
+    timestamp: datetime      # When the feedback was received
+    method_name: str         # Name of the decorated method
+    metadata: dict           # Any metadata passed to the decorator
+```
+
+### Accessing in Listeners
+
+When a listener is triggered by a `@human_feedback` method with `emit`, it receives the `HumanFeedbackResult`:
+
+```python Code
+@listen("approved")
+def on_approval(self, result: HumanFeedbackResult):
+    print(f"Original output: {result.output}")
+    print(f"User feedback: {result.feedback}")
+    print(f"Outcome: {result.outcome}")  # "approved"
+    print(f"Received at: {result.timestamp}")
+```
+
+## Accessing Feedback History
+
+The `Flow` class provides two attributes for accessing human feedback:
+
+### last_human_feedback
+
+Returns the most recent `HumanFeedbackResult`:
+
+```python Code
+@listen(some_method)
+def check_feedback(self):
+    if self.last_human_feedback:
+        print(f"Last feedback: {self.last_human_feedback.feedback}")
+```
+
+### human_feedback_history
+
+A list of all `HumanFeedbackResult` objects collected during the flow:
+
+```python Code
+@listen(final_step)
+def summarize(self):
+    print(f"Total feedback collected: {len(self.human_feedback_history)}")
+    for i, fb in enumerate(self.human_feedback_history):
+        print(f"{i+1}. {fb.method_name}: {fb.outcome or 'no routing'}")
+```
+
+<Warning>
+Each `HumanFeedbackResult` is appended to `human_feedback_history`, so multiple feedback steps won't overwrite each other. Use this list to access all feedback collected during the flow.
+</Warning>
+
+## Complete Example: Content Approval Workflow
+
+Here's a full example implementing a content review and approval workflow:
+
+<CodeGroup>
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
+from pydantic import BaseModel
+
+
+class ContentState(BaseModel):
+    topic: str = ""
+    draft: str = ""
+    final_content: str = ""
+    revision_count: int = 0
+
+
+class ContentApprovalFlow(Flow[ContentState]):
+    """A flow that generates content and gets human approval."""
+
+    @start()
+    def get_topic(self):
+        self.state.topic = input("What topic should I write about? ")
+        return self.state.topic
+
+    @listen(get_topic)
+    def generate_draft(self, topic):
+        # In real use, this would call an LLM
+        self.state.draft = f"# {topic}\n\nThis is a draft about {topic}..."
+        return self.state.draft
+
+    @listen(generate_draft)
+    @human_feedback(
+        message="Please review this draft. Reply 'approved', 'rejected', or provide revision feedback:",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+    )
+    def review_draft(self, draft):
+        return draft
+
+    @listen("approved")
+    def publish_content(self, result: HumanFeedbackResult):
+        self.state.final_content = result.output
+        print("\n✅ Content approved and published!")
+        print(f"Reviewer comment: {result.feedback}")
+        return "published"
+
+    @listen("rejected")
+    def handle_rejection(self, result: HumanFeedbackResult):
+        print("\n❌ Content rejected")
+        print(f"Reason: {result.feedback}")
+        return "rejected"
+
+    @listen("needs_revision")
+    def revise_content(self, result: HumanFeedbackResult):
+        self.state.revision_count += 1
+        print(f"\n📝 Revision #{self.state.revision_count} requested")
+        print(f"Feedback: {result.feedback}")
+
+        # In a real flow, you might loop back to generate_draft
+        # For this example, we just acknowledge
+        return "revision_requested"
+
+
+# Run the flow
+flow = ContentApprovalFlow()
+result = flow.kickoff()
+print(f"\nFlow completed. Revisions requested: {flow.state.revision_count}")
+```
+
+```text Output
+What topic should I write about? AI Safety
+
+==================================================
+OUTPUT FOR REVIEW:
+==================================================
+# AI Safety
+
+This is a draft about AI Safety...
+==================================================
+
+Please review this draft. Reply 'approved', 'rejected', or provide revision feedback:
+(Press Enter to skip, or type your feedback)
+
+Your feedback: Looks good, approved!
+
+✅ Content approved and published!
+Reviewer comment: Looks good, approved!
+
+Flow completed. Revisions requested: 0
+```
+
+</CodeGroup>
+
+## Combining with Other Decorators
+
+The `@human_feedback` decorator works with other flow decorators. Place it as the innermost decorator (closest to the function):
+
+```python Code
+# Correct: @human_feedback is innermost (closest to the function)
+@start()
+@human_feedback(message="Review this:")
+def my_start_method(self):
+    return "content"
+
+@listen(other_method)
+@human_feedback(message="Review this too:")
+def my_listener(self, data):
+    return f"processed: {data}"
+```
+
+<Tip>
+Place `@human_feedback` as the innermost decorator (last/closest to the function) so it wraps the method directly and can capture the return value before passing to the flow system.
+</Tip>
+
+## Best Practices
+
+### 1. Write Clear Request Messages
+
+The `request` parameter is what the human sees. Make it actionable:
+
+```python Code
+# ✅ Good - clear and actionable
+@human_feedback(message="Does this summary accurately capture the key points? Reply 'yes' or explain what's missing:")
+
+# ❌ Bad - vague
+@human_feedback(message="Review this:")
+```
+
+### 2. Choose Meaningful Outcomes
+
+When using `emit`, pick outcomes that map naturally to human responses:
+
+```python Code
+# ✅ Good - natural language outcomes
+emit=["approved", "rejected", "needs_more_detail"]
+
+# ❌ Bad - technical or unclear
+emit=["state_1", "state_2", "state_3"]
+```
+
+### 3. Always Provide a Default Outcome
+
+Use `default_outcome` to handle cases where users press Enter without typing:
+
+```python Code
+@human_feedback(
+    message="Approve? (press Enter to request revision)",
+    emit=["approved", "needs_revision"],
+    llm="gpt-4o-mini",
+    default_outcome="needs_revision",  # Safe default
+)
+```
+
+### 4. Use Feedback History for Audit Trails
+
+Access `human_feedback_history` to create audit logs:
+
+```python Code
+@listen(final_step)
+def create_audit_log(self):
+    log = []
+    for fb in self.human_feedback_history:
+        log.append({
+            "step": fb.method_name,
+            "outcome": fb.outcome,
+            "feedback": fb.feedback,
+            "timestamp": fb.timestamp.isoformat(),
+        })
+    return log
+```
+
+### 5. Handle Both Routed and Non-Routed Feedback
+
+When designing flows, consider whether you need routing:
+
+| Scenario | Use |
+|----------|-----|
+| Simple review, just need the feedback text | No `emit` |
+| Need to branch to different paths based on response | Use `emit` |
+| Approval gates with approve/reject/revise | Use `emit` |
+| Collecting comments for logging only | No `emit` |
+
+## Async Human Feedback (Non-Blocking)
+
+By default, `@human_feedback` blocks execution waiting for console input. For production applications, you may need **async/non-blocking** feedback that integrates with external systems like Slack, email, webhooks, or APIs.
+
+### The Provider Abstraction
+
+Use the `provider` parameter to specify a custom feedback collection strategy:
+
+```python Code
+from crewai.flow import Flow, start, human_feedback, HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext
+
+class WebhookProvider(HumanFeedbackProvider):
+    """Provider that pauses flow and waits for webhook callback."""
+
+    def __init__(self, webhook_url: str):
+        self.webhook_url = webhook_url
+
+    def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str:
+        # Notify external system (e.g., send Slack message, create ticket)
+        self.send_notification(context)
+
+        # Pause execution - framework handles persistence automatically
+        raise HumanFeedbackPending(
+            context=context,
+            callback_info={"webhook_url": f"{self.webhook_url}/{context.flow_id}"}
+        )
+
+class ReviewFlow(Flow):
+    @start()
+    @human_feedback(
+        message="Review this content:",
+        emit=["approved", "rejected"],
+        llm="gpt-4o-mini",
+        provider=WebhookProvider("https://myapp.com/api"),
+    )
+    def generate_content(self):
+        return "AI-generated content..."
+
+    @listen("approved")
+    def publish(self, result):
+        return "Published!"
+```
+
+<Tip>
+The flow framework **automatically persists state** when `HumanFeedbackPending` is raised. Your provider only needs to notify the external system and raise the exception—no manual persistence calls required.
+</Tip>
+
+### Handling Paused Flows
+
+When using an async provider, `kickoff()` returns a `HumanFeedbackPending` object instead of raising an exception:
+
+```python Code
+flow = ReviewFlow()
+result = flow.kickoff()
+
+if isinstance(result, HumanFeedbackPending):
+    # Flow is paused, state is automatically persisted
+    print(f"Waiting for feedback at: {result.callback_info['webhook_url']}")
+    print(f"Flow ID: {result.context.flow_id}")
+else:
+    # Normal completion
+    print(f"Flow completed: {result}")
+```
+
+### Resuming a Paused Flow
+
+When feedback arrives (e.g., via webhook), resume the flow:
+
+```python Code
+# Sync handler:
+def handle_feedback_webhook(flow_id: str, feedback: str):
+    flow = ReviewFlow.from_pending(flow_id)
+    result = flow.resume(feedback)
+    return result
+
+# Async handler (FastAPI, aiohttp, etc.):
+async def handle_feedback_webhook(flow_id: str, feedback: str):
+    flow = ReviewFlow.from_pending(flow_id)
+    result = await flow.resume_async(feedback)
+    return result
+```
+
+### Key Types
+
+| Type | Description |
+|------|-------------|
+| `HumanFeedbackProvider` | Protocol for custom feedback providers |
+| `PendingFeedbackContext` | Contains all info needed to resume a paused flow |
+| `HumanFeedbackPending` | Returned by `kickoff()` when flow is paused for feedback |
+| `ConsoleProvider` | Default blocking console input provider |
+
+### PendingFeedbackContext
+
+The context contains everything needed to resume:
+
+```python Code
+@dataclass
+class PendingFeedbackContext:
+    flow_id: str           # Unique identifier for this flow execution
+    flow_class: str        # Fully qualified class name
+    method_name: str       # Method that triggered feedback
+    method_output: Any     # Output shown to the human
+    message: str           # The request message
+    emit: list[str] | None # Possible outcomes for routing
+    default_outcome: str | None
+    metadata: dict         # Custom metadata
+    llm: str | None        # LLM for outcome collapsing
+    requested_at: datetime
+```
+
+### Complete Async Flow Example
+
+```python Code
+from crewai.flow import (
+    Flow, start, listen, human_feedback,
+    HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext
+)
+
+class SlackNotificationProvider(HumanFeedbackProvider):
+    """Provider that sends Slack notifications and pauses for async feedback."""
+
+    def __init__(self, channel: str):
+        self.channel = channel
+
+    def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str:
+        # Send Slack notification (implement your own)
+        slack_thread_id = self.post_to_slack(
+            channel=self.channel,
+            message=f"Review needed:\n\n{context.method_output}\n\n{context.message}",
+        )
+
+        # Pause execution - framework handles persistence automatically
+        raise HumanFeedbackPending(
+            context=context,
+            callback_info={
+                "slack_channel": self.channel,
+                "thread_id": slack_thread_id,
+            }
+        )
+
+class ContentPipeline(Flow):
+    @start()
+    @human_feedback(
+        message="Approve this content for publication?",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+        provider=SlackNotificationProvider("#content-reviews"),
+    )
+    def generate_content(self):
+        return "AI-generated blog post content..."
+
+    @listen("approved")
+    def publish(self, result):
+        print(f"Publishing! Reviewer said: {result.feedback}")
+        return {"status": "published"}
+
+    @listen("rejected")
+    def archive(self, result):
+        print(f"Archived. Reason: {result.feedback}")
+        return {"status": "archived"}
+
+    @listen("needs_revision")
+    def queue_revision(self, result):
+        print(f"Queued for revision: {result.feedback}")
+        return {"status": "revision_needed"}
+
+
+# Starting the flow (will pause and wait for Slack response)
+def start_content_pipeline():
+    flow = ContentPipeline()
+    result = flow.kickoff()
+
+    if isinstance(result, HumanFeedbackPending):
+        return {"status": "pending", "flow_id": result.context.flow_id}
+
+    return result
+
+
+# Resuming when Slack webhook fires (sync handler)
+def on_slack_feedback(flow_id: str, slack_message: str):
+    flow = ContentPipeline.from_pending(flow_id)
+    result = flow.resume(slack_message)
+    return result
+
+
+# If your handler is async (FastAPI, aiohttp, Slack Bolt async, etc.)
+async def on_slack_feedback_async(flow_id: str, slack_message: str):
+    flow = ContentPipeline.from_pending(flow_id)
+    result = await flow.resume_async(slack_message)
+    return result
+```
+
+<Warning>
+If you're using an async web framework (FastAPI, aiohttp, Slack Bolt async mode), use `await flow.resume_async()` instead of `flow.resume()`. Calling `resume()` from within a running event loop will raise a `RuntimeError`.
+</Warning>
+
+### Best Practices for Async Feedback
+
+1. **Check the return type**: `kickoff()` returns `HumanFeedbackPending` when paused—no try/except needed
+2. **Use the right resume method**: Use `resume()` in sync code, `await resume_async()` in async code
+3. **Store callback info**: Use `callback_info` to store webhook URLs, ticket IDs, etc.
+4. **Implement idempotency**: Your resume handler should be idempotent for safety
+5. **Automatic persistence**: State is automatically saved when `HumanFeedbackPending` is raised and uses `SQLiteFlowPersistence` by default
+6. **Custom persistence**: Pass a custom persistence instance to `from_pending()` if needed
+
+## Related Documentation
+
+- [Flows Overview](/en/concepts/flows) - Learn about CrewAI Flows
+- [Flow State Management](/en/guides/flows/mastering-flow-state) - Managing state in flows
+- [Flow Persistence](/en/concepts/flows#persistence) - Persisting flow state
+- [Routing with @router](/en/concepts/flows#router) - More about conditional routing
+- [Human Input on Execution](/en/learn/human-input-on-execution) - Task-level human input

docs/en/learn/human-in-the-loop.mdx

@@ -5,9 +5,22 @@ icon: "user-check"
 mode: "wide"
 ---
 
-Human-in-the-Loop (HITL) is a powerful approach that combines artificial intelligence with human expertise to enhance decision-making and improve task outcomes. This guide shows you how to implement HITL within CrewAI.
+Human-in-the-Loop (HITL) is a powerful approach that combines artificial intelligence with human expertise to enhance decision-making and improve task outcomes. CrewAI provides multiple ways to implement HITL depending on your needs.
 
-## Setting Up HITL Workflows
+## Choosing Your HITL Approach
+
+CrewAI offers two main approaches for implementing human-in-the-loop workflows:
+
+| Approach | Best For | Integration |
+|----------|----------|-------------|
+| **Flow-based** (`@human_feedback` decorator) | Local development, console-based review, synchronous workflows | [Human Feedback in Flows](/en/learn/human-feedback-in-flows) |
+| **Webhook-based** (Enterprise) | Production deployments, async workflows, external integrations (Slack, Teams, etc.) | This guide |
+
+<Tip>
+If you're building flows and want to add human review steps with routing based on feedback, check out the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide for the `@human_feedback` decorator.
+</Tip>
+
+## Setting Up Webhook-Based HITL Workflows
 
 <Steps>
     <Step title="Configure Your Task">

docs/enterprise-api.base.yaml

@@ -35,7 +35,7 @@ info:
 
     1. **Discover inputs** using `GET /inputs`
     2. **Start execution** using `POST /kickoff`
-    3. **Monitor progress** using `GET /status/{kickoff_id}`
+    3. **Monitor progress** using `GET /{kickoff_id}/status`
   version: 1.0.0
   contact:
     name: CrewAI Support
@@ -63,7 +63,7 @@ paths:
         Use this endpoint to discover what inputs you need to provide when starting a crew execution.
       operationId: getRequiredInputs
       responses:
-        '200':
+        "200":
           description: Successfully retrieved required inputs
           content:
             application/json:
@@ -84,13 +84,21 @@ paths:
                 outreach_crew:
                   summary: Outreach crew inputs
                   value:
-                    inputs: ["name", "title", "company", "industry", "our_product", "linkedin_url"]
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
-          $ref: '#/components/responses/NotFoundError'
-        '500':
-          $ref: '#/components/responses/ServerError'
+                    inputs:
+                      [
+                        "name",
+                        "title",
+                        "company",
+                        "industry",
+                        "our_product",
+                        "linkedin_url",
+                      ]
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/ServerError"
 
   /kickoff:
     post:
@@ -170,7 +178,7 @@ paths:
                   taskWebhookUrl: "https://api.example.com/webhooks/task"
                   crewWebhookUrl: "https://api.example.com/webhooks/crew"
       responses:
-        '200':
+        "200":
           description: Crew execution started successfully
           content:
             application/json:
@@ -182,24 +190,24 @@ paths:
                     format: uuid
                     description: Unique identifier for tracking this execution
                     example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
-        '400':
+        "400":
           description: Invalid request body or missing required inputs
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '422':
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "422":
           description: Validation error - ensure all required inputs are provided
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ValidationError'
-        '500':
-          $ref: '#/components/responses/ServerError'
+                $ref: "#/components/schemas/ValidationError"
+        "500":
+          $ref: "#/components/responses/ServerError"
 
-  /status/{kickoff_id}:
+  /{kickoff_id}/status:
     get:
       summary: Get Execution Status
       description: |
@@ -222,15 +230,15 @@ paths:
             format: uuid
             example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
       responses:
-        '200':
+        "200":
           description: Successfully retrieved execution status
           content:
             application/json:
               schema:
                 oneOf:
-                  - $ref: '#/components/schemas/ExecutionRunning'
-                  - $ref: '#/components/schemas/ExecutionCompleted'
-                  - $ref: '#/components/schemas/ExecutionError'
+                  - $ref: "#/components/schemas/ExecutionRunning"
+                  - $ref: "#/components/schemas/ExecutionCompleted"
+                  - $ref: "#/components/schemas/ExecutionError"
               examples:
                 running:
                   summary: Execution in progress
@@ -262,19 +270,19 @@ paths:
                     status: "error"
                     error: "Task execution failed: Invalid API key for external service"
                     execution_time: 23.1
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
           description: Kickoff ID not found
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
               example:
                 error: "Execution not found"
                 message: "No execution found with ID: abcd1234-5678-90ef-ghij-klmnopqrstuv"
-        '500':
-          $ref: '#/components/responses/ServerError'
+        "500":
+          $ref: "#/components/responses/ServerError"
 
   /resume:
     post:
@@ -354,7 +362,7 @@ paths:
                   taskWebhookUrl: "https://api.example.com/webhooks/task"
                   crewWebhookUrl: "https://api.example.com/webhooks/crew"
       responses:
-        '200':
+        "200":
           description: Execution resumed successfully
           content:
             application/json:
@@ -381,28 +389,28 @@ paths:
                   value:
                     status: "retrying"
                     message: "Task will be retried with your feedback"
-        '400':
+        "400":
           description: Invalid request body or execution not in pending state
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
               example:
                 error: "Invalid Request"
                 message: "Execution is not in pending human input state"
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
           description: Execution ID or Task ID not found
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
               example:
                 error: "Not Found"
                 message: "Execution ID not found"
-        '500':
-          $ref: '#/components/responses/ServerError'
+        "500":
+          $ref: "#/components/responses/ServerError"
 
 components:
   securitySchemes:
@@ -458,7 +466,7 @@ components:
             tasks:
               type: array
               items:
-                $ref: '#/components/schemas/TaskResult'
+                $ref: "#/components/schemas/TaskResult"
         execution_time:
           type: number
           description: Total execution time in seconds
@@ -536,7 +544,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             error: "Unauthorized"
             message: "Invalid or missing bearer token"
@@ -546,7 +554,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             error: "Not Found"
             message: "The requested resource was not found"
@@ -556,7 +564,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             error: "Internal Server Error"
             message: "An unexpected error occurred"

docs/enterprise-api.en.yaml

@@ -35,7 +35,7 @@ info:
 
     1. **Discover inputs** using `GET /inputs`
     2. **Start execution** using `POST /kickoff`
-    3. **Monitor progress** using `GET /status/{kickoff_id}`
+    3. **Monitor progress** using `GET /{kickoff_id}/status`
   version: 1.0.0
   contact:
     name: CrewAI Support
@@ -63,7 +63,7 @@ paths:
         Use this endpoint to discover what inputs you need to provide when starting a crew execution.
       operationId: getRequiredInputs
       responses:
-        '200':
+        "200":
           description: Successfully retrieved required inputs
           content:
             application/json:
@@ -84,13 +84,21 @@ paths:
                 outreach_crew:
                   summary: Outreach crew inputs
                   value:
-                    inputs: ["name", "title", "company", "industry", "our_product", "linkedin_url"]
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
-          $ref: '#/components/responses/NotFoundError'
-        '500':
-          $ref: '#/components/responses/ServerError'
+                    inputs:
+                      [
+                        "name",
+                        "title",
+                        "company",
+                        "industry",
+                        "our_product",
+                        "linkedin_url",
+                      ]
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/ServerError"
 
   /kickoff:
     post:
@@ -170,7 +178,7 @@ paths:
                   taskWebhookUrl: "https://api.example.com/webhooks/task"
                   crewWebhookUrl: "https://api.example.com/webhooks/crew"
       responses:
-        '200':
+        "200":
           description: Crew execution started successfully
           content:
             application/json:
@@ -182,24 +190,24 @@ paths:
                     format: uuid
                     description: Unique identifier for tracking this execution
                     example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
-        '400':
+        "400":
           description: Invalid request body or missing required inputs
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '422':
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "422":
           description: Validation error - ensure all required inputs are provided
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ValidationError'
-        '500':
-          $ref: '#/components/responses/ServerError'
+                $ref: "#/components/schemas/ValidationError"
+        "500":
+          $ref: "#/components/responses/ServerError"
 
-  /status/{kickoff_id}:
+  /{kickoff_id}/status:
     get:
       summary: Get Execution Status
       description: |
@@ -222,15 +230,15 @@ paths:
             format: uuid
             example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
       responses:
-        '200':
+        "200":
           description: Successfully retrieved execution status
           content:
             application/json:
               schema:
                 oneOf:
-                  - $ref: '#/components/schemas/ExecutionRunning'
-                  - $ref: '#/components/schemas/ExecutionCompleted'
-                  - $ref: '#/components/schemas/ExecutionError'
+                  - $ref: "#/components/schemas/ExecutionRunning"
+                  - $ref: "#/components/schemas/ExecutionCompleted"
+                  - $ref: "#/components/schemas/ExecutionError"
               examples:
                 running:
                   summary: Execution in progress
@@ -262,19 +270,19 @@ paths:
                     status: "error"
                     error: "Task execution failed: Invalid API key for external service"
                     execution_time: 23.1
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
           description: Kickoff ID not found
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
               example:
                 error: "Execution not found"
                 message: "No execution found with ID: abcd1234-5678-90ef-ghij-klmnopqrstuv"
-        '500':
-          $ref: '#/components/responses/ServerError'
+        "500":
+          $ref: "#/components/responses/ServerError"
 
   /resume:
     post:
@@ -354,7 +362,7 @@ paths:
                   taskWebhookUrl: "https://api.example.com/webhooks/task"
                   crewWebhookUrl: "https://api.example.com/webhooks/crew"
       responses:
-        '200':
+        "200":
           description: Execution resumed successfully
           content:
             application/json:
@@ -381,28 +389,28 @@ paths:
                   value:
                     status: "retrying"
                     message: "Task will be retried with your feedback"
-        '400':
+        "400":
           description: Invalid request body or execution not in pending state
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
               example:
                 error: "Invalid Request"
                 message: "Execution is not in pending human input state"
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
           description: Execution ID or Task ID not found
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
               example:
                 error: "Not Found"
                 message: "Execution ID not found"
-        '500':
-          $ref: '#/components/responses/ServerError'
+        "500":
+          $ref: "#/components/responses/ServerError"
 
 components:
   securitySchemes:
@@ -458,7 +466,7 @@ components:
             tasks:
               type: array
               items:
-                $ref: '#/components/schemas/TaskResult'
+                $ref: "#/components/schemas/TaskResult"
         execution_time:
           type: number
           description: Total execution time in seconds
@@ -536,7 +544,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             error: "Unauthorized"
             message: "Invalid or missing bearer token"
@@ -546,7 +554,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             error: "Not Found"
             message: "The requested resource was not found"
@@ -556,7 +564,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             error: "Internal Server Error"
             message: "An unexpected error occurred"

docs/enterprise-api.ko.yaml

@@ -84,7 +84,7 @@ paths:
         '500':
           $ref: '#/components/responses/ServerError'
 
-  /status/{kickoff_id}:
+  /{kickoff_id}/status:
     get:
       summary: 실행 상태 조회
       description: |

docs/enterprise-api.pt-BR.yaml

@@ -35,7 +35,7 @@ info:
 
     1. **Descubra os inputs** usando `GET /inputs`
     2. **Inicie a execução** usando `POST /kickoff`
-    3. **Monitore o progresso** usando `GET /status/{kickoff_id}`
+    3. **Monitore o progresso** usando `GET /{kickoff_id}/status`
   version: 1.0.0
   contact:
     name: CrewAI Suporte
@@ -56,7 +56,7 @@ paths:
         Retorna a lista de parâmetros de entrada que sua crew espera.
       operationId: getRequiredInputs
       responses:
-        '200':
+        "200":
           description: Inputs requeridos obtidos com sucesso
           content:
             application/json:
@@ -69,12 +69,12 @@ paths:
                       type: string
                     description: Nomes dos parâmetros de entrada
                     example: ["budget", "interests", "duration", "age"]
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
-          $ref: '#/components/responses/NotFoundError'
-        '500':
-          $ref: '#/components/responses/ServerError'
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/ServerError"
 
   /kickoff:
     post:
@@ -104,7 +104,7 @@ paths:
                     age: "35"
 
       responses:
-        '200':
+        "200":
           description: Execução iniciada com sucesso
           content:
             application/json:
@@ -115,12 +115,12 @@ paths:
                     type: string
                     format: uuid
                     example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '500':
-          $ref: '#/components/responses/ServerError'
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "500":
+          $ref: "#/components/responses/ServerError"
 
-  /status/{kickoff_id}:
+  /{kickoff_id}/status:
     get:
       summary: Obter Status da Execução
       description: |
@@ -136,25 +136,25 @@ paths:
             type: string
             format: uuid
       responses:
-        '200':
+        "200":
           description: Status recuperado com sucesso
           content:
             application/json:
               schema:
                 oneOf:
-                  - $ref: '#/components/schemas/ExecutionRunning'
-                  - $ref: '#/components/schemas/ExecutionCompleted'
-                  - $ref: '#/components/schemas/ExecutionError'
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
+                  - $ref: "#/components/schemas/ExecutionRunning"
+                  - $ref: "#/components/schemas/ExecutionCompleted"
+                  - $ref: "#/components/schemas/ExecutionError"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
           description: Kickoff ID não encontrado
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '500':
-          $ref: '#/components/responses/ServerError'
+                $ref: "#/components/schemas/Error"
+        "500":
+          $ref: "#/components/responses/ServerError"
 
   /resume:
     post:
@@ -234,7 +234,7 @@ paths:
                   taskWebhookUrl: "https://api.example.com/webhooks/task"
                   crewWebhookUrl: "https://api.example.com/webhooks/crew"
       responses:
-        '200':
+        "200":
           description: Execution resumed successfully
           content:
             application/json:
@@ -261,28 +261,28 @@ paths:
                   value:
                     status: "retrying"
                     message: "Task will be retried with your feedback"
-        '400':
+        "400":
           description: Invalid request body or execution not in pending state
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
               example:
                 error: "Invalid Request"
                 message: "Execution is not in pending human input state"
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-        '404':
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
           description: Execution ID or Task ID not found
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
               example:
                 error: "Not Found"
                 message: "Execution ID not found"
-        '500':
-          $ref: '#/components/responses/ServerError'
+        "500":
+          $ref: "#/components/responses/ServerError"
 
 components:
   securitySchemes:
@@ -324,7 +324,7 @@ components:
             tasks:
               type: array
               items:
-                $ref: '#/components/schemas/TaskResult'
+                $ref: "#/components/schemas/TaskResult"
         execution_time:
           type: number
 
@@ -380,16 +380,16 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
     NotFoundError:
       description: Recurso não encontrado
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
     ServerError:
       description: Erro interno do servidor
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"

docs/ko/api-reference/introduction.mdx

@@ -16,16 +16,17 @@ CrewAI 엔터프라이즈 API 참고 자료에 오신 것을 환영합니다.
     CrewAI AOP 대시보드에서 자신의 crew 상세 페이지로 이동하여 Status 탭에서 Bearer Token을 복사하세요.
   </Step>
 
-  <Step title="필수 입력값 확인하기">
-    `GET /inputs` 엔드포인트를 사용하여 crew가 기대하는 파라미터를 확인하세요.
-  </Step>
+<Step title="필수 입력값 확인하기">
+  `GET /inputs` 엔드포인트를 사용하여 crew가 기대하는 파라미터를 확인하세요.
+</Step>
 
-  <Step title="Crew 실행 시작하기">
-    입력값과 함께 `POST /kickoff`를 호출하여 crew 실행을 시작하고 `kickoff_id`를 받으세요.
-  </Step>
+<Step title="Crew 실행 시작하기">
+  입력값과 함께 `POST /kickoff`를 호출하여 crew 실행을 시작하고 `kickoff_id`를
+  받으세요.
+</Step>
 
   <Step title="진행 상황 모니터링">
-    `GET /status/{kickoff_id}`를 사용하여 실행 상태를 확인하고 결과를 조회하세요.
+    `GET /{kickoff_id}/status`를 사용하여 실행 상태를 확인하고 결과를 조회하세요.
   </Step>
 </Steps>
 
@@ -40,13 +41,14 @@ curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \
 
 ### 토큰 유형
 
-| 토큰 유형 | 범위 | 사용 사례 |
-|:-----------|:--------|:----------|
-| **Bearer Token** | 조직 단위 접근 | 전체 crew 운영, 서버 간 통합에 이상적 |
-| **User Bearer Token** | 사용자 범위 접근 | 제한된 권한, 사용자별 작업에 적합 |
+| 토큰 유형             | 범위             | 사용 사례                             |
+| :-------------------- | :--------------- | :------------------------------------ |
+| **Bearer Token**      | 조직 단위 접근   | 전체 crew 운영, 서버 간 통합에 이상적 |
+| **User Bearer Token** | 사용자 범위 접근 | 제한된 권한, 사용자별 작업에 적합     |
 
 <Tip>
-두 토큰 유형 모두 CrewAI AOP 대시보드의 crew 상세 페이지 Status 탭에서 확인할 수 있습니다.
+  두 토큰 유형 모두 CrewAI AOP 대시보드의 crew 상세 페이지 Status 탭에서 확인할
+  수 있습니다.
 </Tip>
 
 ## 기본 URL
@@ -63,29 +65,33 @@ https://your-crew-name.crewai.com
 
 1. **탐색**: `GET /inputs`를 호출하여 crew가 필요한 것을 파악합니다.
 2. **실행**: `POST /kickoff`를 통해 입력값을 제출하여 처리를 시작합니다.
-3. **모니터링**: 완료될 때까지 `GET /status/{kickoff_id}`를 주기적으로 조회합니다.
+3. **모니터링**: 완료될 때까지 `GET /{kickoff_id}/status`를 주기적으로 조회합니다.
 4. **결과**: 완료된 응답에서 최종 출력을 추출합니다.
 
 ## 오류 처리
 
 API는 표준 HTTP 상태 코드를 사용합니다:
 
-| 코드 | 의미 |
-|------|:--------|
-| `200` | 성공 |
-| `400` | 잘못된 요청 - 잘못된 입력 형식 |
-| `401` | 인증 실패 - 잘못된 베어러 토큰 |
+| 코드  | 의미                                  |
+| ----- | :------------------------------------ |
+| `200` | 성공                                  |
+| `400` | 잘못된 요청 - 잘못된 입력 형식        |
+| `401` | 인증 실패 - 잘못된 베어러 토큰        |
 | `404` | 찾을 수 없음 - 리소스가 존재하지 않음 |
-| `422` | 유효성 검사 오류 - 필수 입력 누락 |
-| `500` | 서버 오류 - 지원팀에 문의하십시오 |
+| `422` | 유효성 검사 오류 - 필수 입력 누락     |
+| `500` | 서버 오류 - 지원팀에 문의하십시오     |
 
 ## 인터랙티브 테스트
 
 <Info>
-**왜 "전송" 버튼이 없나요?** 각 CrewAI AOP 사용자는 고유한 crew URL을 가지므로, 혼동을 피하기 위해 인터랙티브 플레이그라운드 대신 **참조 모드**를 사용합니다. 이를 통해 비작동 전송 버튼 없이 요청이 어떻게 생겼는지 정확히 보여줍니다.
+  **왜 "전송" 버튼이 없나요?** 각 CrewAI AOP 사용자는 고유한 crew URL을
+  가지므로, 혼동을 피하기 위해 인터랙티브 플레이그라운드 대신 **참조 모드**를
+  사용합니다. 이를 통해 비작동 전송 버튼 없이 요청이 어떻게 생겼는지 정확히
+  보여줍니다.
 </Info>
 
 각 엔드포인트 페이지에서는 다음을 확인할 수 있습니다:
+
 - ✅ 모든 파라미터가 포함된 **정확한 요청 형식**
 - ✅ 성공 및 오류 사례에 대한 **응답 예시**
 - ✅ 여러 언어(cURL, Python, JavaScript 등)로 제공되는 **코드 샘플**
@@ -103,6 +109,7 @@ API는 표준 HTTP 상태 코드를 사용합니다:
 </CardGroup>
 
 **예시 작업 흐름:**
+
 1. **cURL 예제를 복사**합니다 (엔드포인트 페이지에서)
 2. **`your-actual-crew-name.crewai.com`**을(를) 실제 crew URL로 교체합니다
 3. **Bearer 토큰을** 대시보드에서 복사한 실제 토큰으로 교체합니다
@@ -111,10 +118,18 @@ API는 표준 HTTP 상태 코드를 사용합니다:
 ## 도움이 필요하신가요?
 
 <CardGroup cols={2}>
-  <Card title="Enterprise Support" icon="headset" href="mailto:support@crewai.com">
+  <Card
+    title="Enterprise Support"
+    icon="headset"
+    href="mailto:support@crewai.com"
+  >
     API 통합 및 문제 해결에 대한 지원을 받으세요
   </Card>
-  <Card title="Enterprise Dashboard" icon="chart-line" href="https://app.crewai.com">
+  <Card
+    title="Enterprise Dashboard"
+    icon="chart-line"
+    href="https://app.crewai.com"
+  >
     crew를 관리하고 실행 로그를 확인하세요
   </Card>
 </CardGroup>

docs/ko/api-reference/status.mdx

@@ -1,8 +1,6 @@
 ---
-title: "GET /status/{kickoff_id}"
+title: "GET /{kickoff_id}/status"
 description: "실행 상태 조회"
-openapi: "/enterprise-api.ko.yaml GET /status/{kickoff_id}"
+openapi: "/enterprise-api.ko.yaml GET /{kickoff_id}/status"
 mode: "wide"
 ---
-
-

docs/ko/concepts/flows.mdx

@@ -565,6 +565,55 @@ Fourth method running
 
 이 Flow를 실행하면, `start_method`에서 생성된 랜덤 불리언 값에 따라 출력값이 달라집니다.
 
+### Human in the Loop (인간 피드백)
+
+`@human_feedback` 데코레이터는 인간의 피드백을 수집하기 위해 플로우 실행을 일시 중지하는 human-in-the-loop 워크플로우를 가능하게 합니다. 이는 승인 게이트, 품질 검토, 인간의 판단이 필요한 결정 지점에 유용합니다.
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
+
+class ReviewFlow(Flow):
+    @start()
+    @human_feedback(
+        message="이 콘텐츠를 승인하시겠습니까?",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+    )
+    def generate_content(self):
+        return "검토할 콘텐츠..."
+
+    @listen("approved")
+    def on_approval(self, result: HumanFeedbackResult):
+        print(f"승인됨! 피드백: {result.feedback}")
+
+    @listen("rejected")
+    def on_rejection(self, result: HumanFeedbackResult):
+        print(f"거부됨. 이유: {result.feedback}")
+```
+
+`emit`이 지정되면, 인간의 자유 형식 피드백이 LLM에 의해 해석되어 지정된 outcome 중 하나로 매핑되고, 해당 `@listen` 데코레이터를 트리거합니다.
+
+라우팅 없이 단순히 피드백만 수집할 수도 있습니다:
+
+```python Code
+@start()
+@human_feedback(message="이 출력에 대한 코멘트가 있으신가요?")
+def my_method(self):
+    return "검토할 출력"
+
+@listen(my_method)
+def next_step(self, result: HumanFeedbackResult):
+    # result.feedback로 피드백에 접근
+    # result.output으로 원래 출력에 접근
+    pass
+```
+
+플로우 실행 중 수집된 모든 피드백은 `self.last_human_feedback` (가장 최근) 또는 `self.human_feedback_history` (리스트 형태의 모든 피드백)를 통해 접근할 수 있습니다.
+
+플로우에서의 인간 피드백에 대한 완전한 가이드는 비동기/논블로킹 피드백과 커스텀 프로바이더(Slack, 웹훅 등)를 포함하여 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows)을 참조하세요.
+
 ## 플로우에 에이전트 추가하기
 
 에이전트는 플로우에 원활하게 통합할 수 있으며, 단순하고 집중된 작업 실행이 필요할 때 전체 Crew의 경량 대안으로 활용됩니다. 아래는 에이전트를 플로우 내에서 사용하여 시장 조사를 수행하는 예시입니다:

docs/ko/enterprise/guides/gmail-trigger.mdx

@@ -62,13 +62,13 @@ CrewAI CLI를 사용하여 Gmail 트리거 통합을 로컬에서 테스트하
 crewai triggers list
 
 # 실제 payload로 Gmail 트리거 시뮬레이션
-crewai triggers run gmail/new_email
+crewai triggers run gmail/new_email_received
 ```
 
 `crewai triggers run` 명령은 완전한 Gmail payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
 
 <Warning>
-  개발 중에는 `crewai triggers run gmail/new_email`을 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
+  개발 중에는 `crewai triggers run gmail/new_email_received`을 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
 </Warning>
 
 ## Monitoring Executions
@@ -83,6 +83,6 @@ Track history and performance of triggered runs:
 
 - Ensure Gmail is connected in Tools & Integrations
 - Verify the Gmail Trigger is enabled on the Triggers tab
-- `crewai triggers run gmail/new_email`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
+- `crewai triggers run gmail/new_email_received`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
 - Check the execution logs and confirm the payload is passed as `crewai_trigger_payload`
 - 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)

docs/ko/learn/human-feedback-in-flows.mdx

@@ -0,0 +1,581 @@
+---
+title: Flow에서 인간 피드백
+description: "@human_feedback 데코레이터를 사용하여 CrewAI Flow에 인간 피드백을 직접 통합하는 방법을 알아보세요"
+icon: user-check
+mode: "wide"
+---
+
+## 개요
+
+`@human_feedback` 데코레이터는 CrewAI Flow 내에서 직접 human-in-the-loop(HITL) 워크플로우를 가능하게 합니다. Flow 실행을 일시 중지하고, 인간에게 검토를 위해 출력을 제시하고, 피드백을 수집하고, 선택적으로 피드백 결과에 따라 다른 리스너로 라우팅할 수 있습니다.
+
+이는 특히 다음과 같은 경우에 유용합니다:
+
+- **품질 보증**: AI가 생성한 콘텐츠를 다운스트림에서 사용하기 전에 검토
+- **결정 게이트**: 자동화된 워크플로우에서 인간이 중요한 결정을 내리도록 허용
+- **승인 워크플로우**: 승인/거부/수정 패턴 구현
+- **대화형 개선**: 출력을 반복적으로 개선하기 위해 피드백 수집
+
+```mermaid
+flowchart LR
+    A[Flow 메서드] --> B[출력 생성됨]
+    B --> C[인간이 검토]
+    C --> D{피드백}
+    D -->|emit 지정됨| E[LLM이 Outcome으로 매핑]
+    D -->|emit 없음| F[HumanFeedbackResult]
+    E --> G["@listen('approved')"]
+    E --> H["@listen('rejected')"]
+    F --> I[다음 리스너]
+```
+
+## 빠른 시작
+
+Flow에 인간 피드백을 추가하는 가장 간단한 방법은 다음과 같습니다:
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback
+
+class SimpleReviewFlow(Flow):
+    @start()
+    @human_feedback(message="이 콘텐츠를 검토해 주세요:")
+    def generate_content(self):
+        return "검토가 필요한 AI 생성 콘텐츠입니다."
+
+    @listen(generate_content)
+    def process_feedback(self, result):
+        print(f"콘텐츠: {result.output}")
+        print(f"인간의 의견: {result.feedback}")
+
+flow = SimpleReviewFlow()
+flow.kickoff()
+```
+
+이 Flow를 실행하면:
+1. `generate_content`를 실행하고 문자열을 반환합니다
+2. 요청 메시지와 함께 사용자에게 출력을 표시합니다
+3. 사용자가 피드백을 입력할 때까지 대기합니다 (또는 Enter를 눌러 건너뜁니다)
+4. `HumanFeedbackResult` 객체를 `process_feedback`에 전달합니다
+
+## @human_feedback 데코레이터
+
+### 매개변수
+
+| 매개변수 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `message` | `str` | 예 | 메서드 출력과 함께 인간에게 표시되는 메시지 |
+| `emit` | `Sequence[str]` | 아니오 | 가능한 outcome 목록. 피드백이 이 중 하나로 매핑되어 `@listen` 데코레이터를 트리거합니다 |
+| `llm` | `str \| BaseLLM` | `emit` 지정 시 | 피드백을 해석하고 outcome에 매핑하는 데 사용되는 LLM |
+| `default_outcome` | `str` | 아니오 | 피드백이 제공되지 않을 때 사용할 outcome. `emit`에 있어야 합니다 |
+| `metadata` | `dict` | 아니오 | 엔터프라이즈 통합을 위한 추가 데이터 |
+| `provider` | `HumanFeedbackProvider` | 아니오 | 비동기/논블로킹 피드백을 위한 커스텀 프로바이더. [비동기 인간 피드백](#비동기-인간-피드백-논블로킹) 참조 |
+
+### 기본 사용법 (라우팅 없음)
+
+`emit`을 지정하지 않으면, 데코레이터는 단순히 피드백을 수집하고 다음 리스너에 `HumanFeedbackResult`를 전달합니다:
+
+```python Code
+@start()
+@human_feedback(message="이 분석에 대해 어떻게 생각하시나요?")
+def analyze_data(self):
+    return "분석 결과: 매출 15% 증가, 비용 8% 감소"
+
+@listen(analyze_data)
+def handle_feedback(self, result):
+    # result는 HumanFeedbackResult입니다
+    print(f"분석: {result.output}")
+    print(f"피드백: {result.feedback}")
+```
+
+### emit을 사용한 라우팅
+
+`emit`을 지정하면, 데코레이터는 라우터가 됩니다. 인간의 자유 형식 피드백이 LLM에 의해 해석되어 지정된 outcome 중 하나로 매핑됩니다:
+
+```python Code
+@start()
+@human_feedback(
+    message="이 콘텐츠의 출판을 승인하시겠습니까?",
+    emit=["approved", "rejected", "needs_revision"],
+    llm="gpt-4o-mini",
+    default_outcome="needs_revision",
+)
+def review_content(self):
+    return "블로그 게시물 초안 내용..."
+
+@listen("approved")
+def publish(self, result):
+    print(f"출판 중! 사용자 의견: {result.feedback}")
+
+@listen("rejected")
+def discard(self, result):
+    print(f"폐기됨. 이유: {result.feedback}")
+
+@listen("needs_revision")
+def revise(self, result):
+    print(f"다음을 기반으로 수정 중: {result.feedback}")
+```
+
+<Tip>
+LLM은 가능한 경우 구조화된 출력(function calling)을 사용하여 응답이 지정된 outcome 중 하나임을 보장합니다. 이로 인해 라우팅이 신뢰할 수 있고 예측 가능해집니다.
+</Tip>
+
+## HumanFeedbackResult
+
+`HumanFeedbackResult` 데이터클래스는 인간 피드백 상호작용에 대한 모든 정보를 포함합니다:
+
+```python Code
+from crewai.flow.human_feedback import HumanFeedbackResult
+
+@dataclass
+class HumanFeedbackResult:
+    output: Any              # 인간에게 표시된 원래 메서드 출력
+    feedback: str            # 인간의 원시 피드백 텍스트
+    outcome: str | None      # 매핑된 outcome (emit이 지정된 경우)
+    timestamp: datetime      # 피드백이 수신된 시간
+    method_name: str         # 데코레이터된 메서드의 이름
+    metadata: dict           # 데코레이터에 전달된 모든 메타데이터
+```
+
+### 리스너에서 접근하기
+
+`emit`이 있는 `@human_feedback` 메서드에 의해 리스너가 트리거되면, `HumanFeedbackResult`를 받습니다:
+
+```python Code
+@listen("approved")
+def on_approval(self, result: HumanFeedbackResult):
+    print(f"원래 출력: {result.output}")
+    print(f"사용자 피드백: {result.feedback}")
+    print(f"Outcome: {result.outcome}")  # "approved"
+    print(f"수신 시간: {result.timestamp}")
+```
+
+## 피드백 히스토리 접근하기
+
+`Flow` 클래스는 인간 피드백에 접근하기 위한 두 가지 속성을 제공합니다:
+
+### last_human_feedback
+
+가장 최근의 `HumanFeedbackResult`를 반환합니다:
+
+```python Code
+@listen(some_method)
+def check_feedback(self):
+    if self.last_human_feedback:
+        print(f"마지막 피드백: {self.last_human_feedback.feedback}")
+```
+
+### human_feedback_history
+
+Flow 동안 수집된 모든 `HumanFeedbackResult` 객체의 리스트입니다:
+
+```python Code
+@listen(final_step)
+def summarize(self):
+    print(f"수집된 총 피드백: {len(self.human_feedback_history)}")
+    for i, fb in enumerate(self.human_feedback_history):
+        print(f"{i+1}. {fb.method_name}: {fb.outcome or '라우팅 없음'}")
+```
+
+<Warning>
+각 `HumanFeedbackResult`는 `human_feedback_history`에 추가되므로, 여러 피드백 단계가 서로 덮어쓰지 않습니다. 이 리스트를 사용하여 Flow 동안 수집된 모든 피드백에 접근하세요.
+</Warning>
+
+## 완전한 예제: 콘텐츠 승인 워크플로우
+
+콘텐츠 검토 및 승인 워크플로우를 구현하는 전체 예제입니다:
+
+<CodeGroup>
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
+from pydantic import BaseModel
+
+
+class ContentState(BaseModel):
+    topic: str = ""
+    draft: str = ""
+    final_content: str = ""
+    revision_count: int = 0
+
+
+class ContentApprovalFlow(Flow[ContentState]):
+    """콘텐츠를 생성하고 인간의 승인을 받는 Flow입니다."""
+
+    @start()
+    def get_topic(self):
+        self.state.topic = input("어떤 주제에 대해 글을 쓸까요? ")
+        return self.state.topic
+
+    @listen(get_topic)
+    def generate_draft(self, topic):
+        # 실제 사용에서는 LLM을 호출합니다
+        self.state.draft = f"# {topic}\n\n{topic}에 대한 초안입니다..."
+        return self.state.draft
+
+    @listen(generate_draft)
+    @human_feedback(
+        message="이 초안을 검토해 주세요. 'approved', 'rejected'로 답하거나 수정 피드백을 제공해 주세요:",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+    )
+    def review_draft(self, draft):
+        return draft
+
+    @listen("approved")
+    def publish_content(self, result: HumanFeedbackResult):
+        self.state.final_content = result.output
+        print("\n✅ 콘텐츠가 승인되어 출판되었습니다!")
+        print(f"검토자 코멘트: {result.feedback}")
+        return "published"
+
+    @listen("rejected")
+    def handle_rejection(self, result: HumanFeedbackResult):
+        print("\n❌ 콘텐츠가 거부되었습니다")
+        print(f"이유: {result.feedback}")
+        return "rejected"
+
+    @listen("needs_revision")
+    def revise_content(self, result: HumanFeedbackResult):
+        self.state.revision_count += 1
+        print(f"\n📝 수정 #{self.state.revision_count} 요청됨")
+        print(f"피드백: {result.feedback}")
+
+        # 실제 Flow에서는 generate_draft로 돌아갈 수 있습니다
+        # 이 예제에서는 단순히 확인합니다
+        return "revision_requested"
+
+
+# Flow 실행
+flow = ContentApprovalFlow()
+result = flow.kickoff()
+print(f"\nFlow 완료. 요청된 수정: {flow.state.revision_count}")
+```
+
+```text Output
+어떤 주제에 대해 글을 쓸까요? AI 안전
+
+==================================================
+OUTPUT FOR REVIEW:
+==================================================
+# AI 안전
+
+AI 안전에 대한 초안입니다...
+==================================================
+
+이 초안을 검토해 주세요. 'approved', 'rejected'로 답하거나 수정 피드백을 제공해 주세요:
+(Press Enter to skip, or type your feedback)
+
+Your feedback: 좋아 보입니다, 승인!
+
+✅ 콘텐츠가 승인되어 출판되었습니다!
+검토자 코멘트: 좋아 보입니다, 승인!
+
+Flow 완료. 요청된 수정: 0
+```
+
+</CodeGroup>
+
+## 다른 데코레이터와 결합하기
+
+`@human_feedback` 데코레이터는 다른 Flow 데코레이터와 함께 작동합니다. 가장 안쪽 데코레이터(함수에 가장 가까운)로 배치하세요:
+
+```python Code
+# 올바름: @human_feedback이 가장 안쪽(함수에 가장 가까움)
+@start()
+@human_feedback(message="이것을 검토해 주세요:")
+def my_start_method(self):
+    return "content"
+
+@listen(other_method)
+@human_feedback(message="이것도 검토해 주세요:")
+def my_listener(self, data):
+    return f"processed: {data}"
+```
+
+<Tip>
+`@human_feedback`를 가장 안쪽 데코레이터(마지막/함수에 가장 가까움)로 배치하여 메서드를 직접 래핑하고 Flow 시스템에 전달하기 전에 반환 값을 캡처할 수 있도록 하세요.
+</Tip>
+
+## 모범 사례
+
+### 1. 명확한 요청 메시지 작성
+
+`message` 매개변수는 인간이 보는 것입니다. 실행 가능하게 만드세요:
+
+```python Code
+# ✅ 좋음 - 명확하고 실행 가능
+@human_feedback(message="이 요약이 핵심 포인트를 정확하게 캡처했나요? '예'로 답하거나 무엇이 빠졌는지 설명해 주세요:")
+
+# ❌ 나쁨 - 모호함
+@human_feedback(message="이것을 검토해 주세요:")
+```
+
+### 2. 의미 있는 Outcome 선택
+
+`emit`을 사용할 때, 인간의 응답에 자연스럽게 매핑되는 outcome을 선택하세요:
+
+```python Code
+# ✅ 좋음 - 자연어 outcome
+emit=["approved", "rejected", "needs_more_detail"]
+
+# ❌ 나쁨 - 기술적이거나 불명확
+emit=["state_1", "state_2", "state_3"]
+```
+
+### 3. 항상 기본 Outcome 제공
+
+사용자가 입력 없이 Enter를 누르는 경우를 처리하기 위해 `default_outcome`을 사용하세요:
+
+```python Code
+@human_feedback(
+    message="승인하시겠습니까? (수정 요청하려면 Enter 누르세요)",
+    emit=["approved", "needs_revision"],
+    llm="gpt-4o-mini",
+    default_outcome="needs_revision",  # 안전한 기본값
+)
+```
+
+### 4. 감사 추적을 위한 피드백 히스토리 사용
+
+감사 로그를 생성하기 위해 `human_feedback_history`에 접근하세요:
+
+```python Code
+@listen(final_step)
+def create_audit_log(self):
+    log = []
+    for fb in self.human_feedback_history:
+        log.append({
+            "step": fb.method_name,
+            "outcome": fb.outcome,
+            "feedback": fb.feedback,
+            "timestamp": fb.timestamp.isoformat(),
+        })
+    return log
+```
+
+### 5. 라우팅된 피드백과 라우팅되지 않은 피드백 모두 처리
+
+Flow를 설계할 때, 라우팅이 필요한지 고려하세요:
+
+| 시나리오 | 사용 |
+|----------|------|
+| 간단한 검토, 피드백 텍스트만 필요 | `emit` 없음 |
+| 응답에 따라 다른 경로로 분기 필요 | `emit` 사용 |
+| 승인/거부/수정이 있는 승인 게이트 | `emit` 사용 |
+| 로깅만을 위한 코멘트 수집 | `emit` 없음 |
+
+## 비동기 인간 피드백 (논블로킹)
+
+기본적으로 `@human_feedback`은 콘솔 입력을 기다리며 실행을 차단합니다. 프로덕션 애플리케이션에서는 Slack, 이메일, 웹훅 또는 API와 같은 외부 시스템과 통합되는 **비동기/논블로킹** 피드백이 필요할 수 있습니다.
+
+### Provider 추상화
+
+커스텀 피드백 수집 전략을 지정하려면 `provider` 매개변수를 사용하세요:
+
+```python Code
+from crewai.flow import Flow, start, human_feedback, HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext
+
+class WebhookProvider(HumanFeedbackProvider):
+    """웹훅 콜백을 기다리며 Flow를 일시 중지하는 Provider."""
+
+    def __init__(self, webhook_url: str):
+        self.webhook_url = webhook_url
+
+    def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str:
+        # 외부 시스템에 알림 (예: Slack 메시지 전송, 티켓 생성)
+        self.send_notification(context)
+
+        # 실행 일시 중지 - 프레임워크가 자동으로 영속성 처리
+        raise HumanFeedbackPending(
+            context=context,
+            callback_info={"webhook_url": f"{self.webhook_url}/{context.flow_id}"}
+        )
+
+class ReviewFlow(Flow):
+    @start()
+    @human_feedback(
+        message="이 콘텐츠를 검토해 주세요:",
+        emit=["approved", "rejected"],
+        llm="gpt-4o-mini",
+        provider=WebhookProvider("https://myapp.com/api"),
+    )
+    def generate_content(self):
+        return "AI가 생성한 콘텐츠..."
+
+    @listen("approved")
+    def publish(self, result):
+        return "출판됨!"
+```
+
+<Tip>
+Flow 프레임워크는 `HumanFeedbackPending`이 발생하면 **자동으로 상태를 영속화**합니다. Provider는 외부 시스템에 알리고 예외를 발생시키기만 하면 됩니다—수동 영속성 호출이 필요하지 않습니다.
+</Tip>
+
+### 일시 중지된 Flow 처리
+
+비동기 provider를 사용하면 `kickoff()`는 예외를 발생시키는 대신 `HumanFeedbackPending` 객체를 반환합니다:
+
+```python Code
+flow = ReviewFlow()
+result = flow.kickoff()
+
+if isinstance(result, HumanFeedbackPending):
+    # Flow가 일시 중지됨, 상태가 자동으로 영속화됨
+    print(f"피드백 대기 중: {result.callback_info['webhook_url']}")
+    print(f"Flow ID: {result.context.flow_id}")
+else:
+    # 정상 완료
+    print(f"Flow 완료: {result}")
+```
+
+### 일시 중지된 Flow 재개
+
+피드백이 도착하면 (예: 웹훅을 통해) Flow를 재개합니다:
+
+```python Code
+# 동기 핸들러:
+def handle_feedback_webhook(flow_id: str, feedback: str):
+    flow = ReviewFlow.from_pending(flow_id)
+    result = flow.resume(feedback)
+    return result
+
+# 비동기 핸들러 (FastAPI, aiohttp 등):
+async def handle_feedback_webhook(flow_id: str, feedback: str):
+    flow = ReviewFlow.from_pending(flow_id)
+    result = await flow.resume_async(feedback)
+    return result
+```
+
+### 주요 타입
+
+| 타입 | 설명 |
+|------|------|
+| `HumanFeedbackProvider` | 커스텀 피드백 provider를 위한 프로토콜 |
+| `PendingFeedbackContext` | 일시 중지된 Flow를 재개하는 데 필요한 모든 정보 포함 |
+| `HumanFeedbackPending` | Flow가 피드백을 위해 일시 중지되면 `kickoff()`에서 반환됨 |
+| `ConsoleProvider` | 기본 블로킹 콘솔 입력 provider |
+
+### PendingFeedbackContext
+
+컨텍스트는 재개에 필요한 모든 것을 포함합니다:
+
+```python Code
+@dataclass
+class PendingFeedbackContext:
+    flow_id: str           # 이 Flow 실행의 고유 식별자
+    flow_class: str        # 정규화된 클래스 이름
+    method_name: str       # 피드백을 트리거한 메서드
+    method_output: Any     # 인간에게 표시된 출력
+    message: str           # 요청 메시지
+    emit: list[str] | None # 라우팅을 위한 가능한 outcome
+    default_outcome: str | None
+    metadata: dict         # 커스텀 메타데이터
+    llm: str | None        # outcome 매핑을 위한 LLM
+    requested_at: datetime
+```
+
+### 완전한 비동기 Flow 예제
+
+```python Code
+from crewai.flow import (
+    Flow, start, listen, human_feedback,
+    HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext
+)
+
+class SlackNotificationProvider(HumanFeedbackProvider):
+    """Slack 알림을 보내고 비동기 피드백을 위해 일시 중지하는 Provider."""
+
+    def __init__(self, channel: str):
+        self.channel = channel
+
+    def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str:
+        # Slack 알림 전송 (직접 구현)
+        slack_thread_id = self.post_to_slack(
+            channel=self.channel,
+            message=f"검토 필요:\n\n{context.method_output}\n\n{context.message}",
+        )
+
+        # 실행 일시 중지 - 프레임워크가 자동으로 영속성 처리
+        raise HumanFeedbackPending(
+            context=context,
+            callback_info={
+                "slack_channel": self.channel,
+                "thread_id": slack_thread_id,
+            }
+        )
+
+class ContentPipeline(Flow):
+    @start()
+    @human_feedback(
+        message="이 콘텐츠의 출판을 승인하시겠습니까?",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+        provider=SlackNotificationProvider("#content-reviews"),
+    )
+    def generate_content(self):
+        return "AI가 생성한 블로그 게시물 콘텐츠..."
+
+    @listen("approved")
+    def publish(self, result):
+        print(f"출판 중! 검토자 의견: {result.feedback}")
+        return {"status": "published"}
+
+    @listen("rejected")
+    def archive(self, result):
+        print(f"보관됨. 이유: {result.feedback}")
+        return {"status": "archived"}
+
+    @listen("needs_revision")
+    def queue_revision(self, result):
+        print(f"수정 대기열에 추가됨: {result.feedback}")
+        return {"status": "revision_needed"}
+
+
+# Flow 시작 (Slack 응답을 기다리며 일시 중지)
+def start_content_pipeline():
+    flow = ContentPipeline()
+    result = flow.kickoff()
+
+    if isinstance(result, HumanFeedbackPending):
+        return {"status": "pending", "flow_id": result.context.flow_id}
+
+    return result
+
+
+# Slack 웹훅이 실행될 때 재개 (동기 핸들러)
+def on_slack_feedback(flow_id: str, slack_message: str):
+    flow = ContentPipeline.from_pending(flow_id)
+    result = flow.resume(slack_message)
+    return result
+
+
+# 핸들러가 비동기인 경우 (FastAPI, aiohttp, Slack Bolt 비동기 등)
+async def on_slack_feedback_async(flow_id: str, slack_message: str):
+    flow = ContentPipeline.from_pending(flow_id)
+    result = await flow.resume_async(slack_message)
+    return result
+```
+
+<Warning>
+비동기 웹 프레임워크(FastAPI, aiohttp, Slack Bolt 비동기 모드)를 사용하는 경우 `flow.resume()` 대신 `await flow.resume_async()`를 사용하세요. 실행 중인 이벤트 루프 내에서 `resume()`을 호출하면 `RuntimeError`가 발생합니다.
+</Warning>
+
+### 비동기 피드백 모범 사례
+
+1. **반환 타입 확인**: `kickoff()`는 일시 중지되면 `HumanFeedbackPending`을 반환합니다—try/except가 필요하지 않습니다
+2. **올바른 resume 메서드 사용**: 동기 코드에서는 `resume()`, 비동기 코드에서는 `await resume_async()` 사용
+3. **콜백 정보 저장**: `callback_info`를 사용하여 웹훅 URL, 티켓 ID 등을 저장
+4. **멱등성 구현**: 안전을 위해 resume 핸들러는 멱등해야 합니다
+5. **자동 영속성**: `HumanFeedbackPending`이 발생하면 상태가 자동으로 저장되며 기본적으로 `SQLiteFlowPersistence` 사용
+6. **커스텀 영속성**: 필요한 경우 `from_pending()`에 커스텀 영속성 인스턴스 전달
+
+## 관련 문서
+
+- [Flow 개요](/ko/concepts/flows) - CrewAI Flow에 대해 알아보기
+- [Flow 상태 관리](/ko/guides/flows/mastering-flow-state) - Flow에서 상태 관리하기
+- [Flow 영속성](/ko/concepts/flows#persistence) - Flow 상태 영속화
+- [@router를 사용한 라우팅](/ko/concepts/flows#router) - 조건부 라우팅에 대해 더 알아보기
+- [실행 시 인간 입력](/ko/learn/human-input-on-execution) - 태스크 수준 인간 입력

docs/pt-BR/api-reference/introduction.mdx

@@ -16,16 +16,17 @@ Bem-vindo à referência da API do CrewAI AOP. Esta API permite que você intera
     Navegue até a página de detalhes do seu crew no painel do CrewAI AOP e copie seu Bearer Token na aba Status.
   </Step>
 
-  <Step title="Descubra os Inputs Necessários">
-    Use o endpoint `GET /inputs` para ver quais parâmetros seu crew espera.
-  </Step>
+<Step title="Descubra os Inputs Necessários">
+  Use o endpoint `GET /inputs` para ver quais parâmetros seu crew espera.
+</Step>
 
-  <Step title="Inicie uma Execução de Crew">
-    Chame `POST /kickoff` com seus inputs para iniciar a execução do crew e receber um `kickoff_id`.
-  </Step>
+<Step title="Inicie uma Execução de Crew">
+  Chame `POST /kickoff` com seus inputs para iniciar a execução do crew e
+  receber um `kickoff_id`.
+</Step>
 
   <Step title="Monitore o Progresso">
-    Use `GET /status/{kickoff_id}` para checar o status da execução e recuperar os resultados.
+    Use `GET /{kickoff_id}/status` para checar o status da execução e recuperar os resultados.
   </Step>
 </Steps>
 
@@ -40,13 +41,14 @@ curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \
 
 ### Tipos de Token
 
-| Tipo de Token       | Escopo                   | Caso de Uso                                              |
-|:--------------------|:------------------------|:---------------------------------------------------------|
-| **Bearer Token**    | Acesso em nível de organização | Operações completas de crew, ideal para integração server-to-server |
-| **User Bearer Token** | Acesso com escopo de usuário         | Permissões limitadas, adequado para operações específicas de usuário   |
+| Tipo de Token         | Escopo                         | Caso de Uso                                                          |
+| :-------------------- | :----------------------------- | :------------------------------------------------------------------- |
+| **Bearer Token**      | Acesso em nível de organização | Operações completas de crew, ideal para integração server-to-server  |
+| **User Bearer Token** | Acesso com escopo de usuário   | Permissões limitadas, adequado para operações específicas de usuário |
 
 <Tip>
-Você pode encontrar ambos os tipos de token na aba Status da página de detalhes do seu crew no painel do CrewAI AOP.
+  Você pode encontrar ambos os tipos de token na aba Status da página de
+  detalhes do seu crew no painel do CrewAI AOP.
 </Tip>
 
 ## URL Base
@@ -63,29 +65,33 @@ Substitua `your-crew-name` pela URL real do seu crew no painel.
 
 1. **Descoberta**: Chame `GET /inputs` para entender o que seu crew precisa
 2. **Execução**: Envie os inputs via `POST /kickoff` para iniciar o processamento
-3. **Monitoramento**: Faça polling em `GET /status/{kickoff_id}` até a conclusão
+3. **Monitoramento**: Faça polling em `GET /{kickoff_id}/status` até a conclusão
 4. **Resultados**: Extraia o output final da resposta concluída
 
 ## Tratamento de Erros
 
 A API utiliza códigos de status HTTP padrão:
 
-| Código | Significado                           |
-|--------|:--------------------------------------|
-| `200`  | Sucesso                               |
-| `400`  | Requisição Inválida - Formato de input inválido |
-| `401`  | Não Autorizado - Bearer token inválido |
-| `404`  | Não Encontrado - Recurso não existe     |
+| Código | Significado                                      |
+| ------ | :----------------------------------------------- |
+| `200`  | Sucesso                                          |
+| `400`  | Requisição Inválida - Formato de input inválido  |
+| `401`  | Não Autorizado - Bearer token inválido           |
+| `404`  | Não Encontrado - Recurso não existe              |
 | `422`  | Erro de Validação - Inputs obrigatórios ausentes |
-| `500`  | Erro no Servidor - Contate o suporte    |
+| `500`  | Erro no Servidor - Contate o suporte             |
 
 ## Testes Interativos
 
 <Info>
-**Por que não há botão "Enviar"?** Como cada usuário do CrewAI AOP possui sua própria URL de crew, utilizamos o **modo referência** em vez de um playground interativo para evitar confusão. Isso mostra exatamente como as requisições devem ser feitas, sem botões de envio não funcionais.
+  **Por que não há botão "Enviar"?** Como cada usuário do CrewAI AOP possui sua
+  própria URL de crew, utilizamos o **modo referência** em vez de um playground
+  interativo para evitar confusão. Isso mostra exatamente como as requisições
+  devem ser feitas, sem botões de envio não funcionais.
 </Info>
 
 Cada página de endpoint mostra para você:
+
 - ✅ **Formato exato da requisição** com todos os parâmetros
 - ✅ **Exemplos de resposta** para casos de sucesso e erro
 - ✅ **Exemplos de código** em várias linguagens (cURL, Python, JavaScript, etc.)
@@ -103,6 +109,7 @@ Cada página de endpoint mostra para você:
 </CardGroup>
 
 **Exemplo de fluxo:**
+
 1. **Copie este exemplo cURL** de qualquer página de endpoint
 2. **Substitua `your-actual-crew-name.crewai.com`** pela URL real do seu crew
 3. **Substitua o Bearer token** pelo seu token real do painel
@@ -111,10 +118,18 @@ Cada página de endpoint mostra para você:
 ## Precisa de Ajuda?
 
 <CardGroup cols={2}>
-  <Card title="Suporte Enterprise" icon="headset" href="mailto:support@crewai.com">
+  <Card
+    title="Suporte Enterprise"
+    icon="headset"
+    href="mailto:support@crewai.com"
+  >
     Obtenha ajuda com integração da API e resolução de problemas
   </Card>
-  <Card title="Painel Enterprise" icon="chart-line" href="https://app.crewai.com">
+  <Card
+    title="Painel Enterprise"
+    icon="chart-line"
+    href="https://app.crewai.com"
+  >
     Gerencie seus crews e visualize logs de execução
   </Card>
 </CardGroup>

docs/pt-BR/api-reference/status.mdx

@@ -1,8 +1,6 @@
 ---
-title: "GET /status/{kickoff_id}"
+title: "GET /{kickoff_id}/status"
 description: "Obter o status da execução"
-openapi: "/enterprise-api.pt-BR.yaml GET /status/{kickoff_id}"
+openapi: "/enterprise-api.pt-BR.yaml GET /{kickoff_id}/status"
 mode: "wide"
 ---
-
-

docs/pt-BR/concepts/flows.mdx

@@ -307,6 +307,55 @@ Os métodos `third_method` e `fourth_method` escutam a saída do `second_method`
 
 Ao executar esse Flow, a saída será diferente dependendo do valor booleano aleatório gerado pelo `start_method`.
 
+### Human in the Loop (feedback humano)
+
+O decorador `@human_feedback` permite fluxos de trabalho human-in-the-loop, pausando a execução do flow para coletar feedback de um humano. Isso é útil para portões de aprovação, revisão de qualidade e pontos de decisão que requerem julgamento humano.
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
+
+class ReviewFlow(Flow):
+    @start()
+    @human_feedback(
+        message="Você aprova este conteúdo?",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+    )
+    def generate_content(self):
+        return "Conteúdo para revisão..."
+
+    @listen("approved")
+    def on_approval(self, result: HumanFeedbackResult):
+        print(f"Aprovado! Feedback: {result.feedback}")
+
+    @listen("rejected")
+    def on_rejection(self, result: HumanFeedbackResult):
+        print(f"Rejeitado. Motivo: {result.feedback}")
+```
+
+Quando `emit` é especificado, o feedback livre do humano é interpretado por um LLM e mapeado para um dos outcomes especificados, que então dispara o decorador `@listen` correspondente.
+
+Você também pode usar `@human_feedback` sem roteamento para simplesmente coletar feedback:
+
+```python Code
+@start()
+@human_feedback(message="Algum comentário sobre esta saída?")
+def my_method(self):
+    return "Saída para revisão"
+
+@listen(my_method)
+def next_step(self, result: HumanFeedbackResult):
+    # Acesse o feedback via result.feedback
+    # Acesse a saída original via result.output
+    pass
+```
+
+Acesse todo o feedback coletado durante um flow via `self.last_human_feedback` (mais recente) ou `self.human_feedback_history` (todo o feedback em uma lista).
+
+Para um guia completo sobre feedback humano em flows, incluindo feedback assíncrono/não-bloqueante com providers customizados (Slack, webhooks, etc.), veja [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows).
+
 ## Adicionando Agentes aos Flows
 
 Os agentes podem ser integrados facilmente aos seus flows, oferecendo uma alternativa leve às crews completas quando você precisar executar tarefas simples e focadas. Veja um exemplo de como utilizar um agente em um flow para realizar uma pesquisa de mercado:

docs/pt-BR/enterprise/guides/gmail-trigger.mdx

@@ -62,13 +62,13 @@ Teste sua integração de trigger do Gmail localmente usando a CLI da CrewAI:
 crewai triggers list
 
 # Simule um trigger do Gmail com payload realista
-crewai triggers run gmail/new_email
+crewai triggers run gmail/new_email_received
 ```
 
 O comando `crewai triggers run` executará sua crew com um payload completo do Gmail, permitindo que você teste sua lógica de parsing antes do deployment.
 
 <Warning>
-  Use `crewai triggers run gmail/new_email` (não `crewai run`) para simular execução de trigger durante o desenvolvimento. Após o deployment, sua crew receberá automaticamente o payload do trigger.
+  Use `crewai triggers run gmail/new_email_received` (não `crewai run`) para simular execução de trigger durante o desenvolvimento. Após o deployment, sua crew receberá automaticamente o payload do trigger.
 </Warning>
 
 ## Monitoring Executions
@@ -83,6 +83,6 @@ Track history and performance of triggered runs:
 
 - Ensure Gmail is connected in Tools & Integrations
 - Verify the Gmail Trigger is enabled on the Triggers tab
-- Teste localmente com `crewai triggers run gmail/new_email` para ver a estrutura exata do payload
+- Teste localmente com `crewai triggers run gmail/new_email_received` para ver a estrutura exata do payload
 - Check the execution logs and confirm the payload is passed as `crewai_trigger_payload`
 - Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger

docs/pt-BR/learn/human-feedback-in-flows.mdx

@@ -0,0 +1,581 @@
+---
+title: Feedback Humano em Flows
+description: Aprenda como integrar feedback humano diretamente nos seus CrewAI Flows usando o decorador @human_feedback
+icon: user-check
+mode: "wide"
+---
+
+## Visão Geral
+
+O decorador `@human_feedback` permite fluxos de trabalho human-in-the-loop (HITL) diretamente nos CrewAI Flows. Ele permite pausar a execução do flow, apresentar a saída para um humano revisar, coletar seu feedback e, opcionalmente, rotear para diferentes listeners com base no resultado do feedback.
+
+Isso é particularmente valioso para:
+
+- **Garantia de qualidade**: Revisar conteúdo gerado por IA antes de ser usado downstream
+- **Portões de decisão**: Deixar humanos tomarem decisões críticas em fluxos automatizados
+- **Fluxos de aprovação**: Implementar padrões de aprovar/rejeitar/revisar
+- **Refinamento interativo**: Coletar feedback para melhorar saídas iterativamente
+
+```mermaid
+flowchart LR
+    A[Método do Flow] --> B[Saída Gerada]
+    B --> C[Humano Revisa]
+    C --> D{Feedback}
+    D -->|emit especificado| E[LLM Mapeia para Outcome]
+    D -->|sem emit| F[HumanFeedbackResult]
+    E --> G["@listen('approved')"]
+    E --> H["@listen('rejected')"]
+    F --> I[Próximo Listener]
+```
+
+## Início Rápido
+
+Aqui está a maneira mais simples de adicionar feedback humano a um flow:
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback
+
+class SimpleReviewFlow(Flow):
+    @start()
+    @human_feedback(message="Por favor, revise este conteúdo:")
+    def generate_content(self):
+        return "Este é um conteúdo gerado por IA que precisa de revisão."
+
+    @listen(generate_content)
+    def process_feedback(self, result):
+        print(f"Conteúdo: {result.output}")
+        print(f"Humano disse: {result.feedback}")
+
+flow = SimpleReviewFlow()
+flow.kickoff()
+```
+
+Quando este flow é executado, ele irá:
+1. Executar `generate_content` e retornar a string
+2. Exibir a saída para o usuário com a mensagem de solicitação
+3. Aguardar o usuário digitar o feedback (ou pressionar Enter para pular)
+4. Passar um objeto `HumanFeedbackResult` para `process_feedback`
+
+## O Decorador @human_feedback
+
+### Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|-----------|------|-------------|-----------|
+| `message` | `str` | Sim | A mensagem mostrada ao humano junto com a saída do método |
+| `emit` | `Sequence[str]` | Não | Lista de possíveis outcomes. O feedback é mapeado para um destes, que dispara decoradores `@listen` |
+| `llm` | `str \| BaseLLM` | Quando `emit` especificado | LLM usado para interpretar o feedback e mapear para um outcome |
+| `default_outcome` | `str` | Não | Outcome a usar se nenhum feedback for fornecido. Deve estar em `emit` |
+| `metadata` | `dict` | Não | Dados adicionais para integrações enterprise |
+| `provider` | `HumanFeedbackProvider` | Não | Provider customizado para feedback assíncrono/não-bloqueante. Veja [Feedback Humano Assíncrono](#feedback-humano-assíncrono-não-bloqueante) |
+
+### Uso Básico (Sem Roteamento)
+
+Quando você não especifica `emit`, o decorador simplesmente coleta o feedback e passa um `HumanFeedbackResult` para o próximo listener:
+
+```python Code
+@start()
+@human_feedback(message="O que você acha desta análise?")
+def analyze_data(self):
+    return "Resultados da análise: Receita aumentou 15%, custos diminuíram 8%"
+
+@listen(analyze_data)
+def handle_feedback(self, result):
+    # result é um HumanFeedbackResult
+    print(f"Análise: {result.output}")
+    print(f"Feedback: {result.feedback}")
+```
+
+### Roteamento com emit
+
+Quando você especifica `emit`, o decorador se torna um roteador. O feedback livre do humano é interpretado por um LLM e mapeado para um dos outcomes especificados:
+
+```python Code
+@start()
+@human_feedback(
+    message="Você aprova este conteúdo para publicação?",
+    emit=["approved", "rejected", "needs_revision"],
+    llm="gpt-4o-mini",
+    default_outcome="needs_revision",
+)
+def review_content(self):
+    return "Rascunho do post do blog aqui..."
+
+@listen("approved")
+def publish(self, result):
+    print(f"Publicando! Usuário disse: {result.feedback}")
+
+@listen("rejected")
+def discard(self, result):
+    print(f"Descartando. Motivo: {result.feedback}")
+
+@listen("needs_revision")
+def revise(self, result):
+    print(f"Revisando baseado em: {result.feedback}")
+```
+
+<Tip>
+O LLM usa saídas estruturadas (function calling) quando disponível para garantir que a resposta seja um dos seus outcomes especificados. Isso torna o roteamento confiável e previsível.
+</Tip>
+
+## HumanFeedbackResult
+
+O dataclass `HumanFeedbackResult` contém todas as informações sobre uma interação de feedback humano:
+
+```python Code
+from crewai.flow.human_feedback import HumanFeedbackResult
+
+@dataclass
+class HumanFeedbackResult:
+    output: Any              # A saída original do método mostrada ao humano
+    feedback: str            # O texto bruto do feedback do humano
+    outcome: str | None      # O outcome mapeado (se emit foi especificado)
+    timestamp: datetime      # Quando o feedback foi recebido
+    method_name: str         # Nome do método decorado
+    metadata: dict           # Qualquer metadata passado ao decorador
+```
+
+### Acessando em Listeners
+
+Quando um listener é disparado por um método `@human_feedback` com `emit`, ele recebe o `HumanFeedbackResult`:
+
+```python Code
+@listen("approved")
+def on_approval(self, result: HumanFeedbackResult):
+    print(f"Saída original: {result.output}")
+    print(f"Feedback do usuário: {result.feedback}")
+    print(f"Outcome: {result.outcome}")  # "approved"
+    print(f"Recebido em: {result.timestamp}")
+```
+
+## Acessando o Histórico de Feedback
+
+A classe `Flow` fornece dois atributos para acessar o feedback humano:
+
+### last_human_feedback
+
+Retorna o `HumanFeedbackResult` mais recente:
+
+```python Code
+@listen(some_method)
+def check_feedback(self):
+    if self.last_human_feedback:
+        print(f"Último feedback: {self.last_human_feedback.feedback}")
+```
+
+### human_feedback_history
+
+Uma lista de todos os objetos `HumanFeedbackResult` coletados durante o flow:
+
+```python Code
+@listen(final_step)
+def summarize(self):
+    print(f"Total de feedbacks coletados: {len(self.human_feedback_history)}")
+    for i, fb in enumerate(self.human_feedback_history):
+        print(f"{i+1}. {fb.method_name}: {fb.outcome or 'sem roteamento'}")
+```
+
+<Warning>
+Cada `HumanFeedbackResult` é adicionado a `human_feedback_history`, então múltiplos passos de feedback não sobrescrevem uns aos outros. Use esta lista para acessar todo o feedback coletado durante o flow.
+</Warning>
+
+## Exemplo Completo: Fluxo de Aprovação de Conteúdo
+
+Aqui está um exemplo completo implementando um fluxo de revisão e aprovação de conteúdo:
+
+<CodeGroup>
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
+from pydantic import BaseModel
+
+
+class ContentState(BaseModel):
+    topic: str = ""
+    draft: str = ""
+    final_content: str = ""
+    revision_count: int = 0
+
+
+class ContentApprovalFlow(Flow[ContentState]):
+    """Um flow que gera conteúdo e obtém aprovação humana."""
+
+    @start()
+    def get_topic(self):
+        self.state.topic = input("Sobre qual tópico devo escrever? ")
+        return self.state.topic
+
+    @listen(get_topic)
+    def generate_draft(self, topic):
+        # Em uso real, isso chamaria um LLM
+        self.state.draft = f"# {topic}\n\nEste é um rascunho sobre {topic}..."
+        return self.state.draft
+
+    @listen(generate_draft)
+    @human_feedback(
+        message="Por favor, revise este rascunho. Responda 'approved', 'rejected', ou forneça feedback de revisão:",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+    )
+    def review_draft(self, draft):
+        return draft
+
+    @listen("approved")
+    def publish_content(self, result: HumanFeedbackResult):
+        self.state.final_content = result.output
+        print("\n✅ Conteúdo aprovado e publicado!")
+        print(f"Comentário do revisor: {result.feedback}")
+        return "published"
+
+    @listen("rejected")
+    def handle_rejection(self, result: HumanFeedbackResult):
+        print("\n❌ Conteúdo rejeitado")
+        print(f"Motivo: {result.feedback}")
+        return "rejected"
+
+    @listen("needs_revision")
+    def revise_content(self, result: HumanFeedbackResult):
+        self.state.revision_count += 1
+        print(f"\n📝 Revisão #{self.state.revision_count} solicitada")
+        print(f"Feedback: {result.feedback}")
+
+        # Em um flow real, você pode voltar para generate_draft
+        # Para este exemplo, apenas reconhecemos
+        return "revision_requested"
+
+
+# Executar o flow
+flow = ContentApprovalFlow()
+result = flow.kickoff()
+print(f"\nFlow concluído. Revisões solicitadas: {flow.state.revision_count}")
+```
+
+```text Output
+Sobre qual tópico devo escrever? Segurança em IA
+
+==================================================
+OUTPUT FOR REVIEW:
+==================================================
+# Segurança em IA
+
+Este é um rascunho sobre Segurança em IA...
+==================================================
+
+Por favor, revise este rascunho. Responda 'approved', 'rejected', ou forneça feedback de revisão:
+(Press Enter to skip, or type your feedback)
+
+Your feedback: Parece bom, aprovado!
+
+✅ Conteúdo aprovado e publicado!
+Comentário do revisor: Parece bom, aprovado!
+
+Flow concluído. Revisões solicitadas: 0
+```
+
+</CodeGroup>
+
+## Combinando com Outros Decoradores
+
+O decorador `@human_feedback` funciona com outros decoradores de flow. Coloque-o como o decorador mais interno (mais próximo da função):
+
+```python Code
+# Correto: @human_feedback é o mais interno (mais próximo da função)
+@start()
+@human_feedback(message="Revise isto:")
+def my_start_method(self):
+    return "content"
+
+@listen(other_method)
+@human_feedback(message="Revise isto também:")
+def my_listener(self, data):
+    return f"processed: {data}"
+```
+
+<Tip>
+Coloque `@human_feedback` como o decorador mais interno (último/mais próximo da função) para que ele envolva o método diretamente e possa capturar o valor de retorno antes de passar para o sistema de flow.
+</Tip>
+
+## Melhores Práticas
+
+### 1. Escreva Mensagens de Solicitação Claras
+
+O parâmetro `message` é o que o humano vê. Torne-o acionável:
+
+```python Code
+# ✅ Bom - claro e acionável
+@human_feedback(message="Este resumo captura com precisão os pontos-chave? Responda 'sim' ou explique o que está faltando:")
+
+# ❌ Ruim - vago
+@human_feedback(message="Revise isto:")
+```
+
+### 2. Escolha Outcomes Significativos
+
+Ao usar `emit`, escolha outcomes que mapeiem naturalmente para respostas humanas:
+
+```python Code
+# ✅ Bom - outcomes em linguagem natural
+emit=["approved", "rejected", "needs_more_detail"]
+
+# ❌ Ruim - técnico ou pouco claro
+emit=["state_1", "state_2", "state_3"]
+```
+
+### 3. Sempre Forneça um Outcome Padrão
+
+Use `default_outcome` para lidar com casos onde usuários pressionam Enter sem digitar:
+
+```python Code
+@human_feedback(
+    message="Aprovar? (pressione Enter para solicitar revisão)",
+    emit=["approved", "needs_revision"],
+    llm="gpt-4o-mini",
+    default_outcome="needs_revision",  # Padrão seguro
+)
+```
+
+### 4. Use o Histórico de Feedback para Trilhas de Auditoria
+
+Acesse `human_feedback_history` para criar logs de auditoria:
+
+```python Code
+@listen(final_step)
+def create_audit_log(self):
+    log = []
+    for fb in self.human_feedback_history:
+        log.append({
+            "step": fb.method_name,
+            "outcome": fb.outcome,
+            "feedback": fb.feedback,
+            "timestamp": fb.timestamp.isoformat(),
+        })
+    return log
+```
+
+### 5. Trate Feedback Roteado e Não Roteado
+
+Ao projetar flows, considere se você precisa de roteamento:
+
+| Cenário | Use |
+|---------|-----|
+| Revisão simples, só precisa do texto do feedback | Sem `emit` |
+| Precisa ramificar para caminhos diferentes baseado na resposta | Use `emit` |
+| Portões de aprovação com aprovar/rejeitar/revisar | Use `emit` |
+| Coletando comentários apenas para logging | Sem `emit` |
+
+## Feedback Humano Assíncrono (Não-Bloqueante - Human in the loop)
+
+Por padrão, `@human_feedback` bloqueia a execução aguardando entrada no console. Para aplicações de produção, você pode precisar de feedback **assíncrono/não-bloqueante** que se integre com sistemas externos como Slack, email, webhooks ou APIs.
+
+### A Abstração de Provider
+
+Use o parâmetro `provider` para especificar uma estratégia customizada de coleta de feedback:
+
+```python Code
+from crewai.flow import Flow, start, human_feedback, HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext
+
+class WebhookProvider(HumanFeedbackProvider):
+    """Provider que pausa o flow e aguarda callback de webhook."""
+
+    def __init__(self, webhook_url: str):
+        self.webhook_url = webhook_url
+
+    def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str:
+        # Notifica sistema externo (ex: envia mensagem Slack, cria ticket)
+        self.send_notification(context)
+
+        # Pausa execução - framework cuida da persistência automaticamente
+        raise HumanFeedbackPending(
+            context=context,
+            callback_info={"webhook_url": f"{self.webhook_url}/{context.flow_id}"}
+        )
+
+class ReviewFlow(Flow):
+    @start()
+    @human_feedback(
+        message="Revise este conteúdo:",
+        emit=["approved", "rejected"],
+        llm="gpt-4o-mini",
+        provider=WebhookProvider("https://myapp.com/api"),
+    )
+    def generate_content(self):
+        return "Conteúdo gerado por IA..."
+
+    @listen("approved")
+    def publish(self, result):
+        return "Publicado!"
+```
+
+<Tip>
+O framework de flow **persiste automaticamente o estado** quando `HumanFeedbackPending` é lançado. Seu provider só precisa notificar o sistema externo e lançar a exceção—não são necessárias chamadas manuais de persistência.
+</Tip>
+
+### Tratando Flows Pausados
+
+Ao usar um provider assíncrono, `kickoff()` retorna um objeto `HumanFeedbackPending` em vez de lançar uma exceção:
+
+```python Code
+flow = ReviewFlow()
+result = flow.kickoff()
+
+if isinstance(result, HumanFeedbackPending):
+    # Flow está pausado, estado é automaticamente persistido
+    print(f"Aguardando feedback em: {result.callback_info['webhook_url']}")
+    print(f"Flow ID: {result.context.flow_id}")
+else:
+    # Conclusão normal
+    print(f"Flow concluído: {result}")
+```
+
+### Retomando um Flow Pausado
+
+Quando o feedback chega (ex: via webhook), retome o flow:
+
+```python Code
+# Handler síncrono:
+def handle_feedback_webhook(flow_id: str, feedback: str):
+    flow = ReviewFlow.from_pending(flow_id)
+    result = flow.resume(feedback)
+    return result
+
+# Handler assíncrono (FastAPI, aiohttp, etc.):
+async def handle_feedback_webhook(flow_id: str, feedback: str):
+    flow = ReviewFlow.from_pending(flow_id)
+    result = await flow.resume_async(feedback)
+    return result
+```
+
+### Tipos Principais
+
+| Tipo | Descrição |
+|------|-----------|
+| `HumanFeedbackProvider` | Protocolo para providers de feedback customizados |
+| `PendingFeedbackContext` | Contém todas as informações necessárias para retomar um flow pausado |
+| `HumanFeedbackPending` | Retornado por `kickoff()` quando o flow está pausado para feedback |
+| `ConsoleProvider` | Provider padrão de entrada bloqueante no console |
+
+### PendingFeedbackContext
+
+O contexto contém tudo necessário para retomar:
+
+```python Code
+@dataclass
+class PendingFeedbackContext:
+    flow_id: str           # Identificador único desta execução de flow
+    flow_class: str        # Nome qualificado completo da classe
+    method_name: str       # Método que disparou o feedback
+    method_output: Any     # Saída mostrada ao humano
+    message: str           # A mensagem de solicitação
+    emit: list[str] | None # Outcomes possíveis para roteamento
+    default_outcome: str | None
+    metadata: dict         # Metadata customizado
+    llm: str | None        # LLM para mapeamento de outcome
+    requested_at: datetime
+```
+
+### Exemplo Completo de Flow Assíncrono
+
+```python Code
+from crewai.flow import (
+    Flow, start, listen, human_feedback,
+    HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext
+)
+
+class SlackNotificationProvider(HumanFeedbackProvider):
+    """Provider que envia notificações Slack e pausa para feedback assíncrono."""
+
+    def __init__(self, channel: str):
+        self.channel = channel
+
+    def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str:
+        # Envia notificação Slack (implemente você mesmo)
+        slack_thread_id = self.post_to_slack(
+            channel=self.channel,
+            message=f"Revisão necessária:\n\n{context.method_output}\n\n{context.message}",
+        )
+
+        # Pausa execução - framework cuida da persistência automaticamente
+        raise HumanFeedbackPending(
+            context=context,
+            callback_info={
+                "slack_channel": self.channel,
+                "thread_id": slack_thread_id,
+            }
+        )
+
+class ContentPipeline(Flow):
+    @start()
+    @human_feedback(
+        message="Aprova este conteúdo para publicação?",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+        provider=SlackNotificationProvider("#content-reviews"),
+    )
+    def generate_content(self):
+        return "Conteúdo de blog post gerado por IA..."
+
+    @listen("approved")
+    def publish(self, result):
+        print(f"Publicando! Revisor disse: {result.feedback}")
+        return {"status": "published"}
+
+    @listen("rejected")
+    def archive(self, result):
+        print(f"Arquivado. Motivo: {result.feedback}")
+        return {"status": "archived"}
+
+    @listen("needs_revision")
+    def queue_revision(self, result):
+        print(f"Na fila para revisão: {result.feedback}")
+        return {"status": "revision_needed"}
+
+
+# Iniciando o flow (vai pausar e aguardar resposta do Slack)
+def start_content_pipeline():
+    flow = ContentPipeline()
+    result = flow.kickoff()
+
+    if isinstance(result, HumanFeedbackPending):
+        return {"status": "pending", "flow_id": result.context.flow_id}
+
+    return result
+
+
+# Retomando quando webhook do Slack dispara (handler síncrono)
+def on_slack_feedback(flow_id: str, slack_message: str):
+    flow = ContentPipeline.from_pending(flow_id)
+    result = flow.resume(slack_message)
+    return result
+
+
+# Se seu handler é assíncrono (FastAPI, aiohttp, Slack Bolt async, etc.)
+async def on_slack_feedback_async(flow_id: str, slack_message: str):
+    flow = ContentPipeline.from_pending(flow_id)
+    result = await flow.resume_async(slack_message)
+    return result
+```
+
+<Warning>
+Se você está usando um framework web assíncrono (FastAPI, aiohttp, Slack Bolt modo async), use `await flow.resume_async()` em vez de `flow.resume()`. Chamar `resume()` de dentro de um event loop em execução vai lançar um `RuntimeError`.
+</Warning>
+
+### Melhores Práticas para Feedback Assíncrono
+
+1. **Verifique o tipo de retorno**: `kickoff()` retorna `HumanFeedbackPending` quando pausado—não precisa de try/except
+2. **Use o método resume correto**: Use `resume()` em código síncrono, `await resume_async()` em código assíncrono
+3. **Armazene informações de callback**: Use `callback_info` para armazenar URLs de webhook, IDs de tickets, etc.
+4. **Implemente idempotência**: Seu handler de resume deve ser idempotente por segurança
+5. **Persistência automática**: O estado é automaticamente salvo quando `HumanFeedbackPending` é lançado e usa `SQLiteFlowPersistence` por padrão
+6. **Persistência customizada**: Passe uma instância de persistência customizada para `from_pending()` se necessário
+
+## Documentação Relacionada
+
+- [Visão Geral de Flows](/pt-BR/concepts/flows) - Aprenda sobre CrewAI Flows
+- [Gerenciamento de Estado em Flows](/pt-BR/guides/flows/mastering-flow-state) - Gerenciando estado em flows
+- [Persistência de Flows](/pt-BR/concepts/flows#persistence) - Persistindo estado de flows
+- [Roteamento com @router](/pt-BR/concepts/flows#router) - Mais sobre roteamento condicional
+- [Input Humano na Execução](/pt-BR/learn/human-input-on-execution) - Input humano no nível de task

lib/crewai-tools/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
     "pytube~=15.0.0",
     "requests~=2.32.5",
     "docker~=7.1.0",
-    "crewai==1.7.0",
+    "crewai==1.7.2",
     "lancedb~=0.5.4",
     "tiktoken~=0.8.0",
     "beautifulsoup4~=4.13.4",

lib/crewai-tools/src/crewai_tools/__init__.py

@@ -291,4 +291,4 @@ __all__ = [
     "ZapierActionTools",
 ]
 
-__version__ = "1.7.0"
+__version__ = "1.7.2"

lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/crewai_platform_action_tool.py

@@ -1,5 +1,5 @@
 """Crewai Enterprise Tools."""
-
+import os
 import json
 import re
 from typing import Any, Optional, Union, cast, get_origin
@@ -432,7 +432,11 @@ class CrewAIPlatformActionTool(BaseTool):
             payload = cleaned_kwargs
 
             response = requests.post(
-                url=api_url, headers=headers, json=payload, timeout=60
+                url=api_url,
+                headers=headers,
+                json=payload,
+                timeout=60,
+                verify=os.environ.get("CREWAI_FACTORY", "false").lower() != "true",
             )
 
             data = response.json()

lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/crewai_platform_tool_builder.py

@@ -1,5 +1,5 @@
 from typing import Any
-
+import os
 from crewai.tools import BaseTool
 import requests
 
@@ -37,6 +37,7 @@ class CrewaiPlatformToolBuilder:
                 headers=headers,
                 timeout=30,
                 params={"apps": ",".join(self._apps)},
+                verify=os.environ.get("CREWAI_FACTORY", "false").lower() != "true",
             )
             response.raise_for_status()
         except Exception:

lib/crewai-tools/tests/tools/crewai_platform_tools/test_crewai_platform_action_tool.py

@@ -1,4 +1,6 @@
 from typing import Union, get_args, get_origin
+from unittest.mock import patch, Mock
+import os
 
 from crewai_tools.tools.crewai_platform_tools.crewai_platform_action_tool import (
     CrewAIPlatformActionTool,
@@ -249,3 +251,109 @@ class TestSchemaProcessing:
         result_type = tool._process_schema_type(test_schema, "TestFieldAllOfMixed")
 
         assert result_type is str
+
+class TestCrewAIPlatformActionToolVerify:
+    """Test suite for SSL verification behavior based on CREWAI_FACTORY environment variable"""
+
+    def setup_method(self):
+        self.action_schema = {
+            "function": {
+                "name": "test_action",
+                "parameters": {
+                    "properties": {
+                        "test_param": {
+                            "type": "string",
+                            "description": "Test parameter"
+                        }
+                    },
+                    "required": []
+                }
+            }
+        }
+
+    def create_test_tool(self):
+        return CrewAIPlatformActionTool(
+            description="Test action tool",
+            action_name="test_action",
+            action_schema=self.action_schema
+        )
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token"}, clear=True)
+    @patch("crewai_tools.tools.crewai_platform_tools.crewai_platform_action_tool.requests.post")
+    def test_run_with_ssl_verification_default(self, mock_post):
+        """Test that _run uses SSL verification by default when CREWAI_FACTORY is not set"""
+        mock_response = Mock()
+        mock_response.ok = True
+        mock_response.json.return_value = {"result": "success"}
+        mock_post.return_value = mock_response
+
+        tool = self.create_test_tool()
+        tool._run(test_param="test_value")
+
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        assert call_args.kwargs["verify"] is True
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token", "CREWAI_FACTORY": "false"}, clear=True)
+    @patch("crewai_tools.tools.crewai_platform_tools.crewai_platform_action_tool.requests.post")
+    def test_run_with_ssl_verification_factory_false(self, mock_post):
+        """Test that _run uses SSL verification when CREWAI_FACTORY is 'false'"""
+        mock_response = Mock()
+        mock_response.ok = True
+        mock_response.json.return_value = {"result": "success"}
+        mock_post.return_value = mock_response
+
+        tool = self.create_test_tool()
+        tool._run(test_param="test_value")
+
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        assert call_args.kwargs["verify"] is True
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token", "CREWAI_FACTORY": "FALSE"}, clear=True)
+    @patch("crewai_tools.tools.crewai_platform_tools.crewai_platform_action_tool.requests.post")
+    def test_run_with_ssl_verification_factory_false_uppercase(self, mock_post):
+        """Test that _run uses SSL verification when CREWAI_FACTORY is 'FALSE' (case-insensitive)"""
+        mock_response = Mock()
+        mock_response.ok = True
+        mock_response.json.return_value = {"result": "success"}
+        mock_post.return_value = mock_response
+
+        tool = self.create_test_tool()
+        tool._run(test_param="test_value")
+
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        assert call_args.kwargs["verify"] is True
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token", "CREWAI_FACTORY": "true"}, clear=True)
+    @patch("crewai_tools.tools.crewai_platform_tools.crewai_platform_action_tool.requests.post")
+    def test_run_without_ssl_verification_factory_true(self, mock_post):
+        """Test that _run disables SSL verification when CREWAI_FACTORY is 'true'"""
+        mock_response = Mock()
+        mock_response.ok = True
+        mock_response.json.return_value = {"result": "success"}
+        mock_post.return_value = mock_response
+
+        tool = self.create_test_tool()
+        tool._run(test_param="test_value")
+
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        assert call_args.kwargs["verify"] is False
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token", "CREWAI_FACTORY": "TRUE"}, clear=True)
+    @patch("crewai_tools.tools.crewai_platform_tools.crewai_platform_action_tool.requests.post")
+    def test_run_without_ssl_verification_factory_true_uppercase(self, mock_post):
+        """Test that _run disables SSL verification when CREWAI_FACTORY is 'TRUE' (case-insensitive)"""
+        mock_response = Mock()
+        mock_response.ok = True
+        mock_response.json.return_value = {"result": "success"}
+        mock_post.return_value = mock_response
+
+        tool = self.create_test_tool()
+        tool._run(test_param="test_value")
+
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        assert call_args.kwargs["verify"] is False

lib/crewai-tools/tests/tools/crewai_platform_tools/test_crewai_platform_tool_builder.py

@@ -258,3 +258,98 @@ class TestCrewaiPlatformToolBuilder(unittest.TestCase):
         assert "simple_string" in description_text
         assert "nested_object" in description_text
         assert "array_prop" in description_text
+
+
+
+class TestCrewaiPlatformToolBuilderVerify(unittest.TestCase):
+    """Test suite for SSL verification behavior in CrewaiPlatformToolBuilder"""
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token"}, clear=True)
+    @patch(
+        "crewai_tools.tools.crewai_platform_tools.crewai_platform_tool_builder.requests.get"
+    )
+    def test_fetch_actions_with_ssl_verification_default(self, mock_get):
+        """Test that _fetch_actions uses SSL verification by default when CREWAI_FACTORY is not set"""
+        mock_response = Mock()
+        mock_response.raise_for_status.return_value = None
+        mock_response.json.return_value = {"actions": {}}
+        mock_get.return_value = mock_response
+
+        builder = CrewaiPlatformToolBuilder(apps=["github"])
+        builder._fetch_actions()
+
+        mock_get.assert_called_once()
+        call_args = mock_get.call_args
+        assert call_args.kwargs["verify"] is True
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token", "CREWAI_FACTORY": "false"}, clear=True)
+    @patch(
+        "crewai_tools.tools.crewai_platform_tools.crewai_platform_tool_builder.requests.get"
+    )
+    def test_fetch_actions_with_ssl_verification_factory_false(self, mock_get):
+        """Test that _fetch_actions uses SSL verification when CREWAI_FACTORY is 'false'"""
+        mock_response = Mock()
+        mock_response.raise_for_status.return_value = None
+        mock_response.json.return_value = {"actions": {}}
+        mock_get.return_value = mock_response
+
+        builder = CrewaiPlatformToolBuilder(apps=["github"])
+        builder._fetch_actions()
+
+        mock_get.assert_called_once()
+        call_args = mock_get.call_args
+        assert call_args.kwargs["verify"] is True
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token", "CREWAI_FACTORY": "FALSE"}, clear=True)
+    @patch(
+        "crewai_tools.tools.crewai_platform_tools.crewai_platform_tool_builder.requests.get"
+    )
+    def test_fetch_actions_with_ssl_verification_factory_false_uppercase(self, mock_get):
+        """Test that _fetch_actions uses SSL verification when CREWAI_FACTORY is 'FALSE' (case-insensitive)"""
+        mock_response = Mock()
+        mock_response.raise_for_status.return_value = None
+        mock_response.json.return_value = {"actions": {}}
+        mock_get.return_value = mock_response
+
+        builder = CrewaiPlatformToolBuilder(apps=["github"])
+        builder._fetch_actions()
+
+        mock_get.assert_called_once()
+        call_args = mock_get.call_args
+        assert call_args.kwargs["verify"] is True
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token", "CREWAI_FACTORY": "true"}, clear=True)
+    @patch(
+        "crewai_tools.tools.crewai_platform_tools.crewai_platform_tool_builder.requests.get"
+    )
+    def test_fetch_actions_without_ssl_verification_factory_true(self, mock_get):
+        """Test that _fetch_actions disables SSL verification when CREWAI_FACTORY is 'true'"""
+        mock_response = Mock()
+        mock_response.raise_for_status.return_value = None
+        mock_response.json.return_value = {"actions": {}}
+        mock_get.return_value = mock_response
+
+        builder = CrewaiPlatformToolBuilder(apps=["github"])
+        builder._fetch_actions()
+
+        mock_get.assert_called_once()
+        call_args = mock_get.call_args
+        assert call_args.kwargs["verify"] is False
+
+    @patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token", "CREWAI_FACTORY": "TRUE"}, clear=True)
+    @patch(
+        "crewai_tools.tools.crewai_platform_tools.crewai_platform_tool_builder.requests.get"
+    )
+    def test_fetch_actions_without_ssl_verification_factory_true_uppercase(self, mock_get):
+        """Test that _fetch_actions disables SSL verification when CREWAI_FACTORY is 'TRUE' (case-insensitive)"""
+        mock_response = Mock()
+        mock_response.raise_for_status.return_value = None
+        mock_response.json.return_value = {"actions": {}}
+        mock_get.return_value = mock_response
+
+        builder = CrewaiPlatformToolBuilder(apps=["github"])
+        builder._fetch_actions()
+
+        mock_get.assert_called_once()
+        call_args = mock_get.call_args
+        assert call_args.kwargs["verify"] is False

lib/crewai/pyproject.toml

@@ -49,7 +49,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.7.0",
+    "crewai-tools==1.7.2",
 ]
 embeddings = [
     "tiktoken~=0.8.0"

lib/crewai/src/crewai/__init__.py

@@ -40,7 +40,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-__version__ = "1.7.0"
+__version__ = "1.7.2"
 _telemetry_submitted = False
 
 

lib/crewai/src/crewai/agent/utils.py

@@ -16,7 +16,7 @@ from crewai.events.types.knowledge_events import (
     KnowledgeSearchQueryFailedEvent,
 )
 from crewai.knowledge.utils.knowledge_utils import extract_knowledge_context
-from crewai.utilities.converter import generate_model_description
+from crewai.utilities.pydantic_schema_utils import generate_model_description
 
 
 if TYPE_CHECKING:

lib/crewai/src/crewai/agents/agent_adapters/base_converter_adapter.py

@@ -5,10 +5,9 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 import json
 import re
-from typing import TYPE_CHECKING, Final, Literal
-
-from crewai.utilities.converter import generate_model_description
+from typing import TYPE_CHECKING, Any, Final, Literal
 
+from crewai.utilities.pydantic_schema_utils import generate_model_description
 
 
 if TYPE_CHECKING:
@@ -42,7 +41,7 @@ class BaseConverterAdapter(ABC):
         """
         self.agent_adapter = agent_adapter
         self._output_format: Literal["json", "pydantic"] | None = None
-        self._schema: str | None = None
+        self._schema: dict[str, Any] | None = None
 
     @abstractmethod
     def configure_structured_output(self, task: Task) -> None:
@@ -129,7 +128,7 @@ class BaseConverterAdapter(ABC):
     @staticmethod
     def _configure_format_from_task(
         task: Task,
-    ) -> tuple[Literal["json", "pydantic"] | None, str | None]:
+    ) -> tuple[Literal["json", "pydantic"] | None, dict[str, Any] | None]:
         """Determine output format and schema from task requirements.
 
         This is a helper method that examines the task's output requirements

lib/crewai/src/crewai/agents/agent_adapters/openai_agents/structured_output_converter.py

@@ -4,6 +4,7 @@ This module contains the OpenAIConverterAdapter class that handles structured
 output conversion for OpenAI agents, supporting JSON and Pydantic model formats.
 """
 
+import json
 from typing import Any
 
 from crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapter
@@ -61,7 +62,7 @@ class OpenAIConverterAdapter(BaseConverterAdapter):
         output_schema: str = (
             get_i18n()
             .slice("formatted_task_instructions")
-            .format(output_format=self._schema)
+            .format(output_format=json.dumps(self._schema, indent=2))
         )
 
         return f"{base_prompt}\n\n{output_schema}"

lib/crewai/src/crewai/cli/authentication/main.py

@@ -149,7 +149,9 @@ class AuthenticationCommand:
                 return
 
             if token_data["error"] not in ("authorization_pending", "slow_down"):
-                raise requests.HTTPError(token_data["error_description"])
+                raise requests.HTTPError(
+                    token_data.get("error_description") or token_data.get("error")
+                )
 
             time.sleep(device_code_data["interval"])
             attempts += 1

lib/crewai/src/crewai/cli/plus_api.py

@@ -1,6 +1,6 @@
 from typing import Any
 from urllib.parse import urljoin
-
+import os
 import requests
 
 from crewai.cli.config import Settings
@@ -33,9 +33,7 @@ class PlusAPI:
         if settings.org_uuid:
             self.headers["X-Crewai-Organization-Id"] = settings.org_uuid
 
-        self.base_url = (
-            str(settings.enterprise_base_url) or DEFAULT_CREWAI_ENTERPRISE_URL
-        )
+        self.base_url = os.getenv("CREWAI_PLUS_URL") or str(settings.enterprise_base_url) or DEFAULT_CREWAI_ENTERPRISE_URL
 
     def _make_request(
         self, method: str, endpoint: str, **kwargs: Any

lib/crewai/src/crewai/cli/templates/crew/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.7.0"
+    "crewai[tools]==1.7.2"
 ]
 
 [project.scripts]

lib/crewai/src/crewai/cli/templates/flow/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.7.0"
+    "crewai[tools]==1.7.2"
 ]
 
 [project.scripts]

lib/crewai/src/crewai/cli/tools/main.py

@@ -1,4 +1,5 @@
 import base64
+from json import JSONDecodeError
 import os
 from pathlib import Path
 import subprocess
@@ -11,6 +12,7 @@ from rich.console import Console
 from crewai.cli import git
 from crewai.cli.command import BaseCommand, PlusAPIMixin
 from crewai.cli.config import Settings
+from crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
 from crewai.cli.utils import (
     build_env_with_tool_repository_credentials,
     extract_available_exports,
@@ -130,10 +132,13 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
         self._validate_response(publish_response)
 
         published_handle = publish_response.json()["handle"]
+        settings = Settings()
+        base_url = settings.enterprise_base_url or DEFAULT_CREWAI_ENTERPRISE_URL
+
         console.print(
             f"Successfully published `{published_handle}` ({project_version}).\n\n"
             + "⚠️ Security checks are running in the background. Your tool will be available once these are complete.\n"
-            + f"You can monitor the status or access your tool here:\nhttps://app.crewai.com/crewai_plus/tools/{published_handle}",
+            + f"You can monitor the status or access your tool here:\n{base_url}/crewai_plus/tools/{published_handle}",
             style="bold green",
         )
 
@@ -162,9 +167,19 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
 
         if login_response.status_code != 200:
             console.print(
-                "Authentication failed. Verify if the currently active organization access to the tool repository, and run 'crewai login' again. ",
+                "Authentication failed. Verify if the currently active organization can access the tool repository, and run 'crewai login' again.",
                 style="bold red",
             )
+            try:
+                console.print(
+                    f"[{login_response.status_code} error - {login_response.json().get('message', 'Unknown error')}]",
+                    style="bold red italic",
+                )
+            except JSONDecodeError:
+                console.print(
+                    f"[{login_response.status_code} error - Unknown error - Invalid JSON response]",
+                    style="bold red italic",
+                )
             raise SystemExit
 
         login_response_json = login_response.json()

lib/crewai/src/crewai/crew.py

@@ -1017,10 +1017,26 @@ class Crew(FlowTrackable, BaseModel):
             tasks=self.tasks, planning_agent_llm=self.planning_llm
         )._handle_crew_planning()
 
-        for task, step_plan in zip(
-            self.tasks, result.list_of_plans_per_task, strict=False
-        ):
-            task.description += step_plan.plan
+        plan_map: dict[int, str] = {}
+        for step_plan in result.list_of_plans_per_task:
+            if step_plan.task_number in plan_map:
+                self._logger.log(
+                    "warning",
+                    f"Duplicate plan for Task Number {step_plan.task_number}, "
+                    "using the first plan",
+                )
+            else:
+                plan_map[step_plan.task_number] = step_plan.plan
+
+        for idx, task in enumerate(self.tasks):
+            task_number = idx + 1
+            if task_number in plan_map:
+                task.description += plan_map[task_number]
+            else:
+                self._logger.log(
+                    "warning",
+                    f"No plan found for Task Number {task_number}",
+                )
 
     def _store_execution_log(
         self,

lib/crewai/src/crewai/events/event_listener.py

@@ -38,9 +38,11 @@ from crewai.events.types.crew_events import (
 from crewai.events.types.flow_events import (
     FlowCreatedEvent,
     FlowFinishedEvent,
+    FlowPausedEvent,
     FlowStartedEvent,
     MethodExecutionFailedEvent,
     MethodExecutionFinishedEvent,
+    MethodExecutionPausedEvent,
     MethodExecutionStartedEvent,
 )
 from crewai.events.types.knowledge_events import (
@@ -363,6 +365,28 @@ class EventListener(BaseEventListener):
             )
             self.method_branches[event.method_name] = updated_branch
 
+        @crewai_event_bus.on(MethodExecutionPausedEvent)
+        def on_method_execution_paused(
+            _: Any, event: MethodExecutionPausedEvent
+        ) -> None:
+            method_branch = self.method_branches.get(event.method_name)
+            updated_branch = self.formatter.update_method_status(
+                method_branch,
+                self.formatter.current_flow_tree,
+                event.method_name,
+                "paused",
+            )
+            self.method_branches[event.method_name] = updated_branch
+
+        @crewai_event_bus.on(FlowPausedEvent)
+        def on_flow_paused(_: Any, event: FlowPausedEvent) -> None:
+            self.formatter.update_flow_status(
+                self.formatter.current_flow_tree,
+                event.flow_name,
+                event.flow_id,
+                "paused",
+            )
+
         # ----------- TOOL USAGE EVENTS -----------
 
         @crewai_event_bus.on(ToolUsageStartedEvent)

lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py

@@ -9,6 +9,8 @@ from rich.console import Console
 from rich.panel import Panel
 
 from crewai.cli.authentication.token import AuthError, get_auth_token
+from crewai.cli.config import Settings
+from crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
 from crewai.cli.plus_api import PlusAPI
 from crewai.cli.version import get_crewai_version
 from crewai.events.listeners.tracing.types import TraceEvent
@@ -16,7 +18,6 @@ from crewai.events.listeners.tracing.utils import (
     is_tracing_enabled_in_context,
     should_auto_collect_first_time_traces,
 )
-from crewai.utilities.constants import CREWAI_BASE_URL
 
 
 logger = getLogger(__name__)
@@ -326,10 +327,12 @@ class TraceBatchManager:
             if response.status_code == 200:
                 access_code = response.json().get("access_code", None)
                 console = Console()
+                settings = Settings()
+                base_url = settings.enterprise_base_url or DEFAULT_CREWAI_ENTERPRISE_URL
                 return_link = (
-                    f"{CREWAI_BASE_URL}/crewai_plus/trace_batches/{self.trace_batch_id}"
+                    f"{base_url}/crewai_plus/trace_batches/{self.trace_batch_id}"
                     if not self.is_current_batch_ephemeral and access_code is None
-                    else f"{CREWAI_BASE_URL}/crewai_plus/ephemeral_trace_batches/{self.trace_batch_id}?access_code={access_code}"
+                    else f"{base_url}/crewai_plus/ephemeral_trace_batches/{self.trace_batch_id}?access_code={access_code}"
                 )
 
                 if self.is_current_batch_ephemeral:

lib/crewai/src/crewai/events/types/flow_events.py

@@ -58,6 +58,29 @@ class MethodExecutionFailedEvent(FlowEvent):
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
 
+class MethodExecutionPausedEvent(FlowEvent):
+    """Event emitted when a flow method is paused waiting for human feedback.
+
+    This event is emitted when a @human_feedback decorated method with an
+    async provider raises HumanFeedbackPending to pause execution.
+
+    Attributes:
+        flow_name: Name of the flow that is paused.
+        method_name: Name of the method waiting for feedback.
+        state: Current flow state when paused.
+        flow_id: Unique identifier for this flow execution.
+        message: The message shown when requesting feedback.
+        emit: Optional list of possible outcomes for routing.
+    """
+
+    method_name: str
+    state: dict[str, Any] | BaseModel
+    flow_id: str
+    message: str
+    emit: list[str] | None = None
+    type: str = "method_execution_paused"
+
+
 class FlowFinishedEvent(FlowEvent):
     """Event emitted when a flow completes execution"""
 
@@ -67,8 +90,71 @@ class FlowFinishedEvent(FlowEvent):
     state: dict[str, Any] | BaseModel
 
 
+class FlowPausedEvent(FlowEvent):
+    """Event emitted when a flow is paused waiting for human feedback.
+
+    This event is emitted when a flow is paused due to a @human_feedback
+    decorated method with an async provider raising HumanFeedbackPending.
+
+    Attributes:
+        flow_name: Name of the flow that is paused.
+        flow_id: Unique identifier for this flow execution.
+        method_name: Name of the method waiting for feedback.
+        state: Current flow state when paused.
+        message: The message shown when requesting feedback.
+        emit: Optional list of possible outcomes for routing.
+    """
+
+    flow_id: str
+    method_name: str
+    state: dict[str, Any] | BaseModel
+    message: str
+    emit: list[str] | None = None
+    type: str = "flow_paused"
+
+
 class FlowPlotEvent(FlowEvent):
     """Event emitted when a flow plot is created"""
 
     flow_name: str
     type: str = "flow_plot"
+
+
+class HumanFeedbackRequestedEvent(FlowEvent):
+    """Event emitted when human feedback is requested.
+
+    This event is emitted when a @human_feedback decorated method
+    requires input from a human reviewer.
+
+    Attributes:
+        flow_name: Name of the flow requesting feedback.
+        method_name: Name of the method decorated with @human_feedback.
+        output: The method output shown to the human for review.
+        message: The message displayed when requesting feedback.
+        emit: Optional list of possible outcomes for routing.
+    """
+
+    method_name: str
+    output: Any
+    message: str
+    emit: list[str] | None = None
+    type: str = "human_feedback_requested"
+
+
+class HumanFeedbackReceivedEvent(FlowEvent):
+    """Event emitted when human feedback is received.
+
+    This event is emitted after a human provides feedback in response
+    to a @human_feedback decorated method.
+
+    Attributes:
+        flow_name: Name of the flow that received feedback.
+        method_name: Name of the method that received feedback.
+        feedback: The raw text feedback provided by the human.
+        outcome: The collapsed outcome string (if emit was specified).
+    """
+
+    method_name: str
+    feedback: str
+    outcome: str | None = None
+    type: str = "human_feedback_received"

lib/crewai/src/crewai/events/utils/console_formatter.py

@@ -453,41 +453,48 @@ To enable tracing, do any one of these:
         if flow_tree is None:
             return
 
+        # Determine status-specific labels and styles
+        if status == "completed":
+            label_prefix = "✅ Flow Finished:"
+            style = "green"
+            node_text = "✅ Flow Completed"
+            content_text = "Flow Execution Completed"
+            panel_title = "Flow Completion"
+        elif status == "paused":
+            label_prefix = "⏳ Flow Paused:"
+            style = "cyan"
+            node_text = "⏳ Waiting for Human Feedback"
+            content_text = "Flow Paused - Waiting for Feedback"
+            panel_title = "Flow Paused"
+        else:
+            label_prefix = "❌ Flow Failed:"
+            style = "red"
+            node_text = "❌ Flow Failed"
+            content_text = "Flow Execution Failed"
+            panel_title = "Flow Failure"
+
         # Update main flow label
         self.update_tree_label(
             flow_tree,
-            "✅ Flow Finished:" if status == "completed" else "❌ Flow Failed:",
+            label_prefix,
             flow_name,
-            "green" if status == "completed" else "red",
+            style,
         )
 
         # Update initialization node status
         for child in flow_tree.children:
             if "Starting Flow" in str(child.label):
-                child.label = Text(
-                    (
-                        "✅ Flow Completed"
-                        if status == "completed"
-                        else "❌ Flow Failed"
-                    ),
-                    style="green" if status == "completed" else "red",
-                )
+                child.label = Text(node_text, style=style)
                 break
 
         content = self.create_status_content(
-            (
-                "Flow Execution Completed"
-                if status == "completed"
-                else "Flow Execution Failed"
-            ),
+            content_text,
             flow_name,
-            "green" if status == "completed" else "red",
+            style,
             ID=flow_id,
         )
         self.print(flow_tree)
-        self.print_panel(
-            content, "Flow Completion", "green" if status == "completed" else "red"
-        )
+        self.print_panel(content, panel_title, style)
 
     def update_method_status(
         self,
@@ -508,6 +515,12 @@ To enable tracing, do any one of these:
                 if "Starting Flow" in str(child.label):
                     child.label = Text("Flow Method Step", style="white")
                     break
+        elif status == "paused":
+            prefix, style = "⏳ Paused:", "cyan"
+            for child in flow_tree.children:
+                if "Starting Flow" in str(child.label):
+                    child.label = Text("⏳ Waiting for Feedback", style="cyan")
+                    break
         else:
             prefix, style = "❌ Failed:", "red"
             for child in flow_tree.children:

lib/crewai/src/crewai/flow/__init__.py

@@ -1,4 +1,11 @@
+from crewai.flow.async_feedback import (
+    ConsoleProvider,
+    HumanFeedbackPending,
+    HumanFeedbackProvider,
+    PendingFeedbackContext,
+)
 from crewai.flow.flow import Flow, and_, listen, or_, router, start
+from crewai.flow.human_feedback import HumanFeedbackResult, human_feedback
 from crewai.flow.persistence import persist
 from crewai.flow.visualization import (
     FlowStructure,
@@ -8,10 +15,16 @@ from crewai.flow.visualization import (
 
 
 __all__ = [
+    "ConsoleProvider",
     "Flow",
     "FlowStructure",
+    "HumanFeedbackPending",
+    "HumanFeedbackProvider",
+    "HumanFeedbackResult",
+    "PendingFeedbackContext",
     "and_",
     "build_flow_structure",
+    "human_feedback",
     "listen",
     "or_",
     "persist",

lib/crewai/src/crewai/flow/async_feedback/__init__.py

@@ -0,0 +1,41 @@
+"""Async human feedback support for CrewAI Flows.
+
+This module provides abstractions for non-blocking human-in-the-loop workflows,
+allowing integration with external systems like Slack, Teams, webhooks, or APIs.
+
+Example:
+    ```python
+    from crewai.flow import Flow, start, human_feedback
+    from crewai.flow.async_feedback import HumanFeedbackProvider, HumanFeedbackPending
+
+    class SlackProvider(HumanFeedbackProvider):
+        def request_feedback(self, context, flow):
+            self.send_slack_notification(context)
+            raise HumanFeedbackPending(context=context)
+
+    class MyFlow(Flow):
+        @start()
+        @human_feedback(
+            message="Review this:",
+            emit=["approved", "rejected"],
+            llm="gpt-4o-mini",
+            provider=SlackProvider(),
+        )
+        def review(self):
+            return "Content to review"
+    ```
+"""
+
+from crewai.flow.async_feedback.types import (
+    HumanFeedbackPending,
+    HumanFeedbackProvider,
+    PendingFeedbackContext,
+)
+from crewai.flow.async_feedback.providers import ConsoleProvider
+
+__all__ = [
+    "ConsoleProvider",
+    "HumanFeedbackPending",
+    "HumanFeedbackProvider",
+    "PendingFeedbackContext",
+]

lib/crewai/src/crewai/flow/async_feedback/providers.py

@@ -0,0 +1,124 @@
+"""Default provider implementations for human feedback.
+
+This module provides the ConsoleProvider, which is the default synchronous
+provider that collects feedback via console input.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from crewai.flow.async_feedback.types import PendingFeedbackContext
+
+if TYPE_CHECKING:
+    from crewai.flow.flow import Flow
+
+
+class ConsoleProvider:
+    """Default synchronous console-based feedback provider.
+
+    This provider blocks execution and waits for console input from the user.
+    It displays the method output with formatting and prompts for feedback.
+
+    This is the default provider used when no custom provider is specified
+    in the @human_feedback decorator.
+
+    Example:
+        ```python
+        from crewai.flow.async_feedback import ConsoleProvider
+
+        # Explicitly use console provider
+        @human_feedback(
+            message="Review this:",
+            provider=ConsoleProvider(),
+        )
+        def my_method(self):
+            return "Content to review"
+        ```
+    """
+
+    def __init__(self, verbose: bool = True):
+        """Initialize the console provider.
+
+        Args:
+            verbose: Whether to display formatted output. If False, only
+                shows the prompt message.
+        """
+        self.verbose = verbose
+
+    def request_feedback(
+        self,
+        context: PendingFeedbackContext,
+        flow: Flow,
+    ) -> str:
+        """Request feedback via console input (blocking).
+
+        Displays the method output with formatting and waits for the user
+        to type their feedback. Press Enter to skip (returns empty string).
+
+        Args:
+            context: The pending feedback context with output and message.
+            flow: The Flow instance (used for event emission).
+
+        Returns:
+            The user's feedback as a string, or empty string if skipped.
+        """
+        from crewai.events.event_bus import crewai_event_bus
+        from crewai.events.event_listener import event_listener
+        from crewai.events.types.flow_events import (
+            HumanFeedbackReceivedEvent,
+            HumanFeedbackRequestedEvent,
+        )
+
+        # Emit feedback requested event
+        crewai_event_bus.emit(
+            flow,
+            HumanFeedbackRequestedEvent(
+                type="human_feedback_requested",
+                flow_name=flow.name or flow.__class__.__name__,
+                method_name=context.method_name,
+                output=context.method_output,
+                message=context.message,
+                emit=context.emit,
+            ),
+        )
+
+        # Pause live updates during human input
+        formatter = event_listener.formatter
+        formatter.pause_live_updates()
+
+        try:
+            console = formatter.console
+
+            if self.verbose:
+                # Display output with formatting using Rich console
+                console.print("\n" + "═" * 50, style="bold cyan")
+                console.print("  OUTPUT FOR REVIEW", style="bold cyan")
+                console.print("═" * 50 + "\n", style="bold cyan")
+                console.print(context.method_output)
+                console.print("\n" + "═" * 50 + "\n", style="bold cyan")
+
+            # Show message and prompt for feedback
+            console.print(context.message, style="yellow")
+            console.print(
+                "(Press Enter to skip, or type your feedback)\n", style="cyan"
+            )
+
+            feedback = input("Your feedback: ").strip()
+
+            # Emit feedback received event
+            crewai_event_bus.emit(
+                flow,
+                HumanFeedbackReceivedEvent(
+                    type="human_feedback_received",
+                    flow_name=flow.name or flow.__class__.__name__,
+                    method_name=context.method_name,
+                    feedback=feedback,
+                    outcome=None,  # Will be determined after collapsing
+                ),
+            )
+
+            return feedback
+        finally:
+            # Resume live updates
+            formatter.resume_live_updates()

lib/crewai/src/crewai/flow/async_feedback/types.py

@@ -0,0 +1,264 @@
+"""Core types for async human feedback in Flows.
+
+This module defines the protocol, exception, and context types used for
+non-blocking human-in-the-loop workflows.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from crewai.flow.flow import Flow
+
+
+@dataclass
+class PendingFeedbackContext:
+    """Context capturing everything needed to resume a paused flow.
+
+    When a flow is paused waiting for async human feedback, this dataclass
+    stores all the information needed to:
+    1. Identify which flow execution is waiting
+    2. What method triggered the feedback request
+    3. What was shown to the human
+    4. How to route the response when it arrives
+
+    Attributes:
+        flow_id: Unique identifier for the flow instance (from state.id)
+        flow_class: Fully qualified class name (e.g., "myapp.flows.ReviewFlow")
+        method_name: Name of the method that triggered feedback request
+        method_output: The output that was shown to the human for review
+        message: The message displayed when requesting feedback
+        emit: Optional list of outcome strings for routing
+        default_outcome: Outcome to use when no feedback is provided
+        metadata: Optional metadata for external system integration
+        llm: LLM model string for outcome collapsing
+        requested_at: When the feedback was requested
+
+    Example:
+        ```python
+        context = PendingFeedbackContext(
+            flow_id="abc-123",
+            flow_class="myapp.ReviewFlow",
+            method_name="review_content",
+            method_output={"title": "Draft", "body": "..."},
+            message="Please review and approve or reject:",
+            emit=["approved", "rejected"],
+            llm="gpt-4o-mini",
+        )
+        ```
+    """
+
+    flow_id: str
+    flow_class: str
+    method_name: str
+    method_output: Any
+    message: str
+    emit: list[str] | None = None
+    default_outcome: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    llm: str | None = None
+    requested_at: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize context to a dictionary for persistence.
+
+        Returns:
+            Dictionary representation suitable for JSON serialization.
+        """
+        return {
+            "flow_id": self.flow_id,
+            "flow_class": self.flow_class,
+            "method_name": self.method_name,
+            "method_output": self.method_output,
+            "message": self.message,
+            "emit": self.emit,
+            "default_outcome": self.default_outcome,
+            "metadata": self.metadata,
+            "llm": self.llm,
+            "requested_at": self.requested_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PendingFeedbackContext:
+        """Deserialize context from a dictionary.
+
+        Args:
+            data: Dictionary representation of the context.
+
+        Returns:
+            Reconstructed PendingFeedbackContext instance.
+        """
+        requested_at = data.get("requested_at")
+        if isinstance(requested_at, str):
+            requested_at = datetime.fromisoformat(requested_at)
+        elif requested_at is None:
+            requested_at = datetime.now()
+
+        return cls(
+            flow_id=data["flow_id"],
+            flow_class=data["flow_class"],
+            method_name=data["method_name"],
+            method_output=data.get("method_output"),
+            message=data.get("message", ""),
+            emit=data.get("emit"),
+            default_outcome=data.get("default_outcome"),
+            metadata=data.get("metadata", {}),
+            llm=data.get("llm"),
+            requested_at=requested_at,
+        )
+
+
+class HumanFeedbackPending(Exception):  # noqa: N818 - Not an error, a control flow signal
+    """Signal that flow execution should pause for async human feedback.
+
+    When raised by a provider, the flow framework will:
+    1. Stop execution at the current method
+    2. Automatically persist state and context (if persistence is configured)
+    3. Return this object to the caller (not re-raise it)
+
+    The caller receives this as a return value from `flow.kickoff()`, enabling
+    graceful handling of the paused state without try/except blocks:
+
+        ```python
+        result = flow.kickoff()
+        if isinstance(result, HumanFeedbackPending):
+            # Flow is paused, handle async feedback
+            print(f"Waiting for feedback: {result.context.flow_id}")
+        else:
+            # Normal completion
+            print(f"Flow completed: {result}")
+        ```
+
+    Note:
+        The flow framework automatically saves pending feedback when this
+        exception is raised. Providers do NOT need to call `save_pending_feedback`
+        manually - just raise this exception and the framework handles persistence.
+
+    Attributes:
+        context: The PendingFeedbackContext with all details needed to resume
+        callback_info: Optional dict with information for external systems
+            (e.g., webhook URL, ticket ID, Slack thread ID)
+
+    Example:
+        ```python
+        class SlackProvider(HumanFeedbackProvider):
+            def request_feedback(self, context, flow):
+                # Send notification to external system
+                ticket_id = self.create_slack_thread(context)
+
+                # Raise to pause - framework handles persistence automatically
+                raise HumanFeedbackPending(
+                    context=context,
+                    callback_info={
+                        "slack_channel": "#reviews",
+                        "thread_id": ticket_id,
+                    }
+                )
+        ```
+    """
+
+    def __init__(
+        self,
+        context: PendingFeedbackContext,
+        callback_info: dict[str, Any] | None = None,
+        message: str | None = None,
+    ):
+        """Initialize the pending feedback exception.
+
+        Args:
+            context: The pending feedback context with flow details
+            callback_info: Optional information for external system callbacks
+            message: Optional custom message (defaults to descriptive message)
+        """
+        self.context = context
+        self.callback_info = callback_info or {}
+
+        if message is None:
+            message = (
+                f"Human feedback pending for flow '{context.flow_id}' "
+                f"at method '{context.method_name}'"
+            )
+        super().__init__(message)
+
+
+@runtime_checkable
+class HumanFeedbackProvider(Protocol):
+    """Protocol for human feedback collection strategies.
+
+    Implement this protocol to create custom feedback providers that integrate
+    with external systems like Slack, Teams, email, or custom APIs.
+
+    Providers can be either:
+    - **Synchronous (blocking)**: Return feedback string directly
+    - **Asynchronous (non-blocking)**: Raise HumanFeedbackPending to pause
+
+    The default ConsoleProvider is synchronous and blocks waiting for input.
+    For async workflows, implement a provider that raises HumanFeedbackPending.
+
+    Note:
+        The flow framework automatically handles state persistence when
+        HumanFeedbackPending is raised. Providers only need to:
+        1. Notify the external system (Slack, email, webhook, etc.)
+        2. Raise HumanFeedbackPending with the context and callback info
+
+    Example synchronous provider:
+        ```python
+        class ConsoleProvider(HumanFeedbackProvider):
+            def request_feedback(self, context, flow):
+                print(context.method_output)
+                return input("Your feedback: ")
+        ```
+
+    Example async provider:
+        ```python
+        class SlackProvider(HumanFeedbackProvider):
+            def __init__(self, channel: str):
+                self.channel = channel
+
+            def request_feedback(self, context, flow):
+                # Send notification to Slack
+                thread_id = self.post_to_slack(
+                    channel=self.channel,
+                    message=context.message,
+                    content=context.method_output,
+                )
+
+                # Raise to pause - framework handles persistence automatically
+                raise HumanFeedbackPending(
+                    context=context,
+                    callback_info={
+                        "channel": self.channel,
+                        "thread_id": thread_id,
+                    }
+                )
+        ```
+    """
+
+    def request_feedback(
+        self,
+        context: PendingFeedbackContext,
+        flow: Flow,
+    ) -> str:
+        """Request feedback from a human.
+
+        For synchronous providers, block and return the feedback string.
+        For async providers, notify the external system and raise
+        HumanFeedbackPending to pause the flow.
+
+        Args:
+            context: The pending feedback context containing all details
+                about what feedback is needed and how to route the response.
+            flow: The Flow instance, providing access to state and name.
+
+        Returns:
+            The human's feedback as a string (synchronous providers only).
+
+        Raises:
+            HumanFeedbackPending: To signal that the flow should pause and
+                wait for external feedback. The framework will automatically
+                persist state when this is raised.
+        """
+        ...

lib/crewai/src/crewai/flow/flow.py

@@ -7,12 +7,13 @@ for building event-driven workflows with conditional execution and routing.
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from concurrent.futures import Future
 import copy
 import inspect
 import logging
 from typing import (
+    TYPE_CHECKING,
     Any,
     ClassVar,
     Generic,
@@ -41,10 +42,12 @@ from crewai.events.listeners.tracing.utils import (
 from crewai.events.types.flow_events import (
     FlowCreatedEvent,
     FlowFinishedEvent,
+    FlowPausedEvent,
     FlowPlotEvent,
     FlowStartedEvent,
     MethodExecutionFailedEvent,
     MethodExecutionFinishedEvent,
+    MethodExecutionPausedEvent,
     MethodExecutionStartedEvent,
 )
 from crewai.flow.constants import AND_CONDITION, OR_CONDITION
@@ -69,9 +72,14 @@ from crewai.flow.utils import (
     is_flow_method_name,
     is_simple_flow_condition,
 )
+
+if TYPE_CHECKING:
+    from crewai.flow.async_feedback.types import PendingFeedbackContext
+    from crewai.flow.human_feedback import HumanFeedbackResult
+    from crewai.llms.base_llm import BaseLLM
+
 from crewai.flow.visualization import build_flow_structure, render_interactive
 from crewai.types.streaming import CrewStreamingOutput, FlowStreamingOutput
-from crewai.utilities.printer import Printer, PrinterColor
 from crewai.utilities.streaming import (
     TaskInfo,
     create_async_chunk_generator,
@@ -443,6 +451,23 @@ class FlowMeta(type):
                         else:
                             router_paths[attr_name] = []
 
+                # Handle start methods that are also routers (e.g., @human_feedback with emit)
+                if (
+                    hasattr(attr_value, "__is_start_method__")
+                    and hasattr(attr_value, "__is_router__")
+                    and attr_value.__is_router__
+                ):
+                    routers.add(attr_name)
+                    # Get router paths from the decorator attribute
+                    if hasattr(attr_value, "__router_paths__") and attr_value.__router_paths__:
+                        router_paths[attr_name] = attr_value.__router_paths__
+                    else:
+                        possible_returns = get_possible_return_constants(attr_value)
+                        if possible_returns:
+                            router_paths[attr_name] = possible_returns
+                        else:
+                            router_paths[attr_name] = []
+
         cls._start_methods = start_methods  # type: ignore[attr-defined]
         cls._listeners = listeners  # type: ignore[attr-defined]
         cls._routers = routers  # type: ignore[attr-defined]
@@ -456,8 +481,6 @@ class Flow(Generic[T], metaclass=FlowMeta):
 
     type parameter T must be either dict[str, Any] or a subclass of BaseModel."""
 
-    _printer: ClassVar[Printer] = Printer()
-
     _start_methods: ClassVar[list[FlowMethodName]] = []
     _listeners: ClassVar[dict[FlowMethodName, SimpleFlowCondition | FlowCondition]] = {}
     _routers: ClassVar[set[FlowMethodName]] = set()
@@ -499,6 +522,11 @@ class Flow(Generic[T], metaclass=FlowMeta):
         self._is_execution_resuming: bool = False
         self._event_futures: list[Future[None]] = []
 
+        # Human feedback storage
+        self.human_feedback_history: list[HumanFeedbackResult] = []
+        self.last_human_feedback: HumanFeedbackResult | None = None
+        self._pending_feedback_context: PendingFeedbackContext | None = None
+
         # Initialize state with initial values
         self._state = self._create_initial_state()
         self.tracing = tracing
@@ -529,6 +557,295 @@ class Flow(Generic[T], metaclass=FlowMeta):
                         method = method.__get__(self, self.__class__)
                     self._methods[method.__name__] = method
 
+    @classmethod
+    def from_pending(
+        cls,
+        flow_id: str,
+        persistence: FlowPersistence | None = None,
+        **kwargs: Any,
+    ) -> "Flow[Any]":
+        """Create a Flow instance from a pending feedback state.
+
+        This classmethod is used to restore a flow that was paused waiting
+        for async human feedback. It loads the persisted state and pending
+        feedback context, then returns a flow instance ready to resume.
+
+        Args:
+            flow_id: The unique identifier of the paused flow (from state.id)
+            persistence: The persistence backend where the state was saved.
+                If not provided, defaults to SQLiteFlowPersistence().
+            **kwargs: Additional keyword arguments passed to the Flow constructor
+
+        Returns:
+            A new Flow instance with restored state, ready to call resume()
+
+        Raises:
+            ValueError: If no pending feedback exists for the given flow_id
+
+        Example:
+            ```python
+            # Simple usage with default persistence:
+            flow = MyFlow.from_pending("abc-123")
+            result = flow.resume("looks good!")
+
+            # Or with custom persistence:
+            persistence = SQLiteFlowPersistence("custom.db")
+            flow = MyFlow.from_pending("abc-123", persistence)
+            result = flow.resume("looks good!")
+            ```
+        """
+        if persistence is None:
+            from crewai.flow.persistence import SQLiteFlowPersistence
+
+            persistence = SQLiteFlowPersistence()
+
+        # Load pending feedback context and state
+        loaded = persistence.load_pending_feedback(flow_id)
+        if loaded is None:
+            raise ValueError(f"No pending feedback found for flow_id: {flow_id}")
+
+        state_data, pending_context = loaded
+
+        # Create flow instance with persistence
+        instance = cls(persistence=persistence, **kwargs)
+
+        # Restore state
+        instance._initialize_state(state_data)
+
+        # Store pending context for resume
+        instance._pending_feedback_context = pending_context
+
+        # Mark that we're resuming execution
+        instance._is_execution_resuming = True
+
+        # Mark the method as completed (it ran before pausing)
+        instance._completed_methods.add(FlowMethodName(pending_context.method_name))
+
+        return instance
+
+    @property
+    def pending_feedback(self) -> "PendingFeedbackContext | None":
+        """Get the pending feedback context if this flow is waiting for feedback.
+
+        Returns:
+            The PendingFeedbackContext if the flow is paused waiting for feedback,
+            None otherwise.
+
+        Example:
+            ```python
+            flow = MyFlow.from_pending("abc-123", persistence)
+            if flow.pending_feedback:
+                print(f"Waiting for feedback on: {flow.pending_feedback.method_name}")
+            ```
+        """
+        return self._pending_feedback_context
+
+    def resume(self, feedback: str = "") -> Any:
+        """Resume flow execution, optionally with human feedback.
+
+        This method continues flow execution after a flow was paused for
+        async human feedback. It processes the feedback (including LLM-based
+        outcome collapsing if emit was specified), stores the result, and
+        triggers downstream listeners.
+
+        Note:
+            If called from within an async context (running event loop),
+            use `await flow.resume_async(feedback)` instead.
+
+        Args:
+            feedback: The human's feedback as a string. If empty, uses
+                default_outcome or the first emit option.
+
+        Returns:
+            The final output from the flow execution, or HumanFeedbackPending
+            if another feedback point is reached.
+
+        Raises:
+            ValueError: If no pending feedback context exists (flow wasn't paused)
+            RuntimeError: If called from within a running event loop (use resume_async instead)
+
+        Example:
+            ```python
+            # In a sync webhook handler:
+            def handle_feedback(flow_id: str, feedback: str):
+                flow = MyFlow.from_pending(flow_id)
+                result = flow.resume(feedback)
+                return result
+
+            # In an async handler, use resume_async instead:
+            async def handle_feedback_async(flow_id: str, feedback: str):
+                flow = MyFlow.from_pending(flow_id)
+                result = await flow.resume_async(feedback)
+                return result
+            ```
+        """
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is not None:
+            raise RuntimeError(
+                "resume() cannot be called from within an async context. "
+                "Use 'await flow.resume_async(feedback)' instead."
+            )
+
+        return asyncio.run(self.resume_async(feedback))
+
+    async def resume_async(self, feedback: str = "") -> Any:
+        """Async version of resume.
+
+        Resume flow execution, optionally with human feedback asynchronously.
+
+        Args:
+            feedback: The human's feedback as a string. If empty, uses
+                default_outcome or the first emit option.
+
+        Returns:
+            The final output from the flow execution, or HumanFeedbackPending
+            if another feedback point is reached.
+
+        Raises:
+            ValueError: If no pending feedback context exists
+        """
+        from crewai.flow.human_feedback import HumanFeedbackResult
+        from datetime import datetime
+
+        if self._pending_feedback_context is None:
+            raise ValueError(
+                "No pending feedback context. Use from_pending() to restore a paused flow."
+            )
+
+        context = self._pending_feedback_context
+        emit = context.emit
+        default_outcome = context.default_outcome
+        llm = context.llm
+
+        # Determine outcome
+        collapsed_outcome: str | None = None
+
+        if not feedback.strip():
+            # Empty feedback
+            if default_outcome:
+                collapsed_outcome = default_outcome
+            elif emit:
+                # No default and no feedback - use first outcome
+                collapsed_outcome = emit[0]
+        elif emit:
+            # Collapse feedback to outcome using LLM
+            collapsed_outcome = self._collapse_to_outcome(
+                feedback=feedback,
+                outcomes=emit,
+                llm=llm,
+            )
+
+        # Create result
+        result = HumanFeedbackResult(
+            output=context.method_output,
+            feedback=feedback,
+            outcome=collapsed_outcome,
+            timestamp=datetime.now(),
+            method_name=context.method_name,
+            metadata=context.metadata,
+        )
+
+        # Store in flow instance
+        self.human_feedback_history.append(result)
+        self.last_human_feedback = result
+
+        # Clear pending context after processing
+        self._pending_feedback_context = None
+
+        # Clear pending feedback from persistence
+        if self._persistence:
+            self._persistence.clear_pending_feedback(context.flow_id)
+
+        # Emit feedback received event
+        crewai_event_bus.emit(
+            self,
+            MethodExecutionFinishedEvent(
+                type="method_execution_finished",
+                flow_name=self.name or self.__class__.__name__,
+                method_name=context.method_name,
+                result=collapsed_outcome if emit else result,
+                state=self._state,
+            ),
+        )
+
+        # Clear resumption flag before triggering listeners
+        # This allows methods to re-execute in loops (e.g., implement_changes → suggest_changes → implement_changes)
+        self._is_execution_resuming = False
+
+        # Determine what to pass to listeners
+        try:
+            if emit and collapsed_outcome:
+                # Router behavior - the outcome itself triggers listeners
+                # First, add the outcome to method outputs as a router would
+                self._method_outputs.append(collapsed_outcome)
+
+                # Then trigger listeners for the outcome (e.g., "approved" triggers @listen("approved"))
+                final_result = await self._execute_listeners(
+                    FlowMethodName(collapsed_outcome),  # Use outcome as trigger
+                    result,  # Pass HumanFeedbackResult to listeners
+                )
+            else:
+                # Normal behavior - pass the HumanFeedbackResult
+                final_result = await self._execute_listeners(
+                    FlowMethodName(context.method_name),
+                    result,
+                )
+        except Exception as e:
+            # Check if flow was paused again for human feedback (loop case)
+            from crewai.flow.async_feedback.types import HumanFeedbackPending
+
+            if isinstance(e, HumanFeedbackPending):
+                # Auto-save pending feedback (create default persistence if needed)
+                if self._persistence is None:
+                    from crewai.flow.persistence import SQLiteFlowPersistence
+
+                    self._persistence = SQLiteFlowPersistence()
+
+                state_data = (
+                    self._state
+                    if isinstance(self._state, dict)
+                    else self._state.model_dump()
+                )
+                self._persistence.save_pending_feedback(
+                    flow_uuid=e.context.flow_id,
+                    context=e.context,
+                    state_data=state_data,
+                )
+
+                # Emit flow paused event
+                crewai_event_bus.emit(
+                    self,
+                    FlowPausedEvent(
+                        type="flow_paused",
+                        flow_name=self.name or self.__class__.__name__,
+                        flow_id=e.context.flow_id,
+                        method_name=e.context.method_name,
+                        state=self._copy_and_serialize_state(),
+                        message=e.context.message,
+                        emit=e.context.emit,
+                    ),
+                )
+                # Return the pending exception instead of raising
+                return e
+            raise
+
+        # Emit flow finished
+        crewai_event_bus.emit(
+            self,
+            FlowFinishedEvent(
+                type="flow_finished",
+                flow_name=self.name or self.__class__.__name__,
+                result=final_result,
+                state=self._state,
+            ),
+        )
+
+        return final_result
+
     def _create_initial_state(self) -> T:
         """Create and initialize flow state with UUID and default values.
 
@@ -544,19 +861,21 @@ class Flow(Generic[T], metaclass=FlowMeta):
             state_type = self._initial_state_t
             if isinstance(state_type, type):
                 if issubclass(state_type, FlowState):
-                    # Create instance without id, then set it
+                    # Create instance - FlowState auto-generates id via default_factory
                     instance = state_type()
-                    if not hasattr(instance, "id"):
-                        instance.id = str(uuid4())
+                    # Ensure id is set - generate UUID if empty
+                    if not getattr(instance, "id", None):
+                        object.__setattr__(instance, "id", str(uuid4()))
                     return cast(T, instance)
                 if issubclass(state_type, BaseModel):
-                    # Create a new type that includes the ID field
-                    class StateWithId(state_type, FlowState):  # type: ignore
+                    # Create a new type with FlowState first for proper id default
+                    class StateWithId(FlowState, state_type):  # type: ignore
                         pass
 
                     instance = StateWithId()
-                    if not hasattr(instance, "id"):
-                        instance.id = str(uuid4())
+                    # Ensure id is set - generate UUID if empty
+                    if not getattr(instance, "id", None):
+                        object.__setattr__(instance, "id", str(uuid4()))
                     return cast(T, instance)
                 if state_type is dict:
                     return cast(T, {"id": str(uuid4())})
@@ -574,7 +893,11 @@ class Flow(Generic[T], metaclass=FlowMeta):
                 model_fields = getattr(self.initial_state, "model_fields", None)
                 if not model_fields or "id" not in model_fields:
                     raise ValueError("Flow state model must have an 'id' field")
-                return self.initial_state()  # Uses model defaults
+                instance = self.initial_state()
+                # Ensure id is set - generate UUID if empty
+                if not getattr(instance, "id", None):
+                    object.__setattr__(instance, "id", str(uuid4()))
+                return instance
             if self.initial_state is dict:
                 return cast(T, {"id": str(uuid4())})
 
@@ -604,6 +927,10 @@ class Flow(Generic[T], metaclass=FlowMeta):
                     k: v for k, v in model.__dict__.items() if not k.startswith("_")
                 }
 
+            # Ensure id is set - generate UUID if empty
+            if not state_dict.get("id"):
+                state_dict["id"] = str(uuid4())
+
             # Create new instance of the same class
             model_class = type(model)
             return cast(T, model_class(**state_dict))
@@ -686,16 +1013,22 @@ class Flow(Generic[T], metaclass=FlowMeta):
             TypeError: If state is neither BaseModel nor dictionary
         """
         if isinstance(self._state, dict):
-            # For dict states, preserve existing fields unless overridden
+            # For dict states, update with inputs
+            # If inputs contains an id, use it (for restoring from persistence)
+            # Otherwise preserve the current id or generate a new one
             current_id = self._state.get("id")
-            # Only update specified fields
+            inputs_has_id = "id" in inputs
+
+            # Update specified fields
             for k, v in inputs.items():
                 self._state[k] = v
-            # Ensure ID is preserved or generated
-            if current_id:
-                self._state["id"] = current_id
-            elif "id" not in self._state:
-                self._state["id"] = str(uuid4())
+
+            # Ensure ID is set: prefer inputs id, then current id, then generate
+            if not inputs_has_id:
+                if current_id:
+                    self._state["id"] = current_id
+                elif "id" not in self._state:
+                    self._state["id"] = str(uuid4())
         elif isinstance(self._state, BaseModel):
             # For BaseModel states, preserve existing fields unless overridden
             try:
@@ -985,17 +1318,73 @@ class Flow(Generic[T], metaclass=FlowMeta):
             if future:
                 self._event_futures.append(future)
             self._log_flow_event(
-                f"Flow started with ID: {self.flow_id}", color="bold_magenta"
+                f"Flow started with ID: {self.flow_id}", color="bold magenta"
             )
 
             if inputs is not None and "id" not in inputs:
                 self._initialize_state(inputs)
 
-            tasks = [
-                self._execute_start_method(start_method)
-                for start_method in self._start_methods
-            ]
-            await asyncio.gather(*tasks)
+            try:
+                tasks = [
+                    self._execute_start_method(start_method)
+                    for start_method in self._start_methods
+                ]
+                await asyncio.gather(*tasks)
+            except Exception as e:
+                # Check if flow was paused for human feedback
+                from crewai.flow.async_feedback.types import HumanFeedbackPending
+
+                if isinstance(e, HumanFeedbackPending):
+                    # Auto-save pending feedback (create default persistence if needed)
+                    if self._persistence is None:
+                        from crewai.flow.persistence import SQLiteFlowPersistence
+
+                        self._persistence = SQLiteFlowPersistence()
+
+                    state_data = (
+                        self._state
+                        if isinstance(self._state, dict)
+                        else self._state.model_dump()
+                    )
+                    self._persistence.save_pending_feedback(
+                        flow_uuid=e.context.flow_id,
+                        context=e.context,
+                        state_data=state_data,
+                    )
+
+                    # Emit flow paused event
+                    future = crewai_event_bus.emit(
+                        self,
+                        FlowPausedEvent(
+                            type="flow_paused",
+                            flow_name=self.name or self.__class__.__name__,
+                            flow_id=e.context.flow_id,
+                            method_name=e.context.method_name,
+                            state=self._copy_and_serialize_state(),
+                            message=e.context.message,
+                            emit=e.context.emit,
+                        ),
+                    )
+                    if future and isinstance(future, Future):
+                        self._event_futures.append(future)
+
+                    # Wait for events to be processed
+                    if self._event_futures:
+                        await asyncio.gather(
+                            *[
+                                asyncio.wrap_future(f)
+                                for f in self._event_futures
+                                if isinstance(f, Future)
+                            ]
+                        )
+                        self._event_futures.clear()
+
+                    # Return the pending exception instead of raising
+                    # This allows the caller to handle the paused state gracefully
+                    return e
+
+                # Re-raise other exceptions
+                raise
 
             # Clear the resumption flag after initial execution completes
             self._is_execution_resuming = False
@@ -1075,7 +1464,30 @@ class Flow(Generic[T], metaclass=FlowMeta):
         enhanced_method = self._inject_trigger_payload_for_start_method(method)
 
         result = await self._execute_method(start_method_name, enhanced_method)
-        await self._execute_listeners(start_method_name, result)
+
+        # If start method is a router, use its result as an additional trigger
+        if start_method_name in self._routers and result is not None:
+            # Execute listeners for the start method name first
+            await self._execute_listeners(start_method_name, result)
+            # Then execute listeners for the router result (e.g., "approved")
+            router_result_trigger = FlowMethodName(str(result))
+            listeners_for_result = self._find_triggered_methods(
+                router_result_trigger, router_only=False
+            )
+            if listeners_for_result:
+                # Pass the HumanFeedbackResult if available
+                listener_result = (
+                    self.last_human_feedback
+                    if self.last_human_feedback is not None
+                    else result
+                )
+                tasks = [
+                    self._execute_single_listener(listener_name, listener_result)
+                    for listener_name in listeners_for_result
+                ]
+                await asyncio.gather(*tasks)
+        else:
+            await self._execute_listeners(start_method_name, result)
 
     def _inject_trigger_payload_for_start_method(
         self, original_method: Callable[..., Any]
@@ -1166,6 +1578,28 @@ class Flow(Generic[T], metaclass=FlowMeta):
 
             return result
         except Exception as e:
+            # Check if this is a HumanFeedbackPending exception (paused, not failed)
+            from crewai.flow.async_feedback.types import HumanFeedbackPending
+
+            if isinstance(e, HumanFeedbackPending):
+                # Emit paused event instead of failed
+                future = crewai_event_bus.emit(
+                    self,
+                    MethodExecutionPausedEvent(
+                        type="method_execution_paused",
+                        method_name=method_name,
+                        flow_name=self.name or self.__class__.__name__,
+                        state=self._copy_and_serialize_state(),
+                        flow_id=e.context.flow_id,
+                        message=e.context.message,
+                        emit=e.context.emit,
+                    ),
+                )
+                if future:
+                    self._event_futures.append(future)
+                raise e
+
+            # Regular failure
             future = crewai_event_bus.emit(
                 self,
                 MethodExecutionFailedEvent(
@@ -1210,7 +1644,9 @@ class Flow(Generic[T], metaclass=FlowMeta):
         """
         # First, handle routers repeatedly until no router triggers anymore
         router_results = []
+        router_result_to_feedback: dict[str, Any] = {}  # Map outcome -> HumanFeedbackResult
         current_trigger = trigger_method
+        current_result = result  # Track the result to pass to each router
 
         while True:
             routers_triggered = self._find_triggered_methods(
@@ -1220,13 +1656,22 @@ class Flow(Generic[T], metaclass=FlowMeta):
                 break
 
             for router_name in routers_triggered:
-                await self._execute_single_listener(router_name, result)
+                # For routers triggered by a router outcome, pass the HumanFeedbackResult
+                router_input = router_result_to_feedback.get(
+                    str(current_trigger), current_result
+                )
+                await self._execute_single_listener(router_name, router_input)
                 # After executing router, the router's result is the path
                 router_result = (
                     self._method_outputs[-1] if self._method_outputs else None
                 )
                 if router_result:  # Only add non-None results
                     router_results.append(router_result)
+                    # If this was a human_feedback router, map the outcome to the feedback
+                    if self.last_human_feedback is not None:
+                        router_result_to_feedback[str(router_result)] = (
+                            self.last_human_feedback
+                        )
                 current_trigger = (
                     FlowMethodName(str(router_result))
                     if router_result is not None
@@ -1242,8 +1687,13 @@ class Flow(Generic[T], metaclass=FlowMeta):
                     current_trigger, router_only=False
                 )
                 if listeners_triggered:
+                    # Determine what result to pass to listeners
+                    # For router outcomes, pass the HumanFeedbackResult if available
+                    listener_result = router_result_to_feedback.get(
+                        str(current_trigger), result
+                    )
                     tasks = [
-                        self._execute_single_listener(listener_name, result)
+                        self._execute_single_listener(listener_name, listener_result)
                         for listener_name in listeners_triggered
                     ]
                     await asyncio.gather(*tasks)
@@ -1435,14 +1885,223 @@ class Flow(Generic[T], metaclass=FlowMeta):
             # Execute listeners (and possibly routers) of this listener
             await self._execute_listeners(listener_name, listener_result)
 
+            # If this listener is also a router (e.g., has @human_feedback with emit),
+            # we need to trigger listeners for the router result as well
+            if listener_name in self._routers and listener_result is not None:
+                router_result_trigger = FlowMethodName(str(listener_result))
+                listeners_for_result = self._find_triggered_methods(
+                    router_result_trigger, router_only=False
+                )
+                if listeners_for_result:
+                    # Pass the HumanFeedbackResult if available
+                    feedback_result = (
+                        self.last_human_feedback
+                        if self.last_human_feedback is not None
+                        else listener_result
+                    )
+                    tasks = [
+                        self._execute_single_listener(name, feedback_result)
+                        for name in listeners_for_result
+                    ]
+                    await asyncio.gather(*tasks)
+
         except Exception as e:
-            logger.error(f"Error executing listener {listener_name}: {e}")
+            # Don't log HumanFeedbackPending as an error - it's expected control flow
+            from crewai.flow.async_feedback.types import HumanFeedbackPending
+
+            if not isinstance(e, HumanFeedbackPending):
+                logger.error(f"Error executing listener {listener_name}: {e}")
             raise
 
+    def _request_human_feedback(
+        self,
+        message: str,
+        output: Any,
+        metadata: dict[str, Any] | None = None,
+        emit: Sequence[str] | None = None,
+    ) -> str:
+        """Request feedback from a human.
+        Args:
+            message: The message to display when requesting feedback.
+            output: The method output to show the human for review.
+            metadata: Optional metadata for enterprise integrations.
+            emit: Optional list of possible outcomes for routing.
+
+        Returns:
+            The human's feedback as a string. Empty string if no feedback provided.
+        """
+        from crewai.events.event_listener import event_listener
+        from crewai.events.types.flow_events import (
+            HumanFeedbackReceivedEvent,
+            HumanFeedbackRequestedEvent,
+        )
+
+        # Emit feedback requested event
+        crewai_event_bus.emit(
+            self,
+            HumanFeedbackRequestedEvent(
+                type="human_feedback_requested",
+                flow_name=self.name or self.__class__.__name__,
+                method_name="",  # Will be set by decorator if needed
+                output=output,
+                message=message,
+                emit=list(emit) if emit else None,
+            ),
+        )
+
+        # Pause live updates during human input
+        formatter = event_listener.formatter
+        formatter.pause_live_updates()
+
+        try:
+            # Display output with formatting using centralized Rich console
+            formatter.console.print("\n" + "═" * 50, style="bold cyan")
+            formatter.console.print("  OUTPUT FOR REVIEW", style="bold cyan")
+            formatter.console.print("═" * 50 + "\n", style="bold cyan")
+            formatter.console.print(output)
+            formatter.console.print("\n" + "═" * 50 + "\n", style="bold cyan")
+
+            # Show message and prompt for feedback
+            formatter.console.print(message, style="yellow")
+            formatter.console.print("(Press Enter to skip, or type your feedback)\n", style="cyan")
+
+            feedback = input("Your feedback: ").strip()
+
+            # Emit feedback received event
+            crewai_event_bus.emit(
+                self,
+                HumanFeedbackReceivedEvent(
+                    type="human_feedback_received",
+                    flow_name=self.name or self.__class__.__name__,
+                    method_name="",  # Will be set by decorator if needed
+                    feedback=feedback,
+                    outcome=None,  # Will be determined after collapsing
+                ),
+            )
+
+            return feedback
+        finally:
+            # Resume live updates
+            formatter.resume_live_updates()
+
+    def _collapse_to_outcome(
+        self,
+        feedback: str,
+        outcomes: Sequence[str],
+        llm: str | BaseLLM,
+    ) -> str:
+        """Collapse free-form feedback to a predefined outcome using LLM.
+
+        This method uses the specified LLM to interpret the human's feedback
+        and map it to one of the predefined outcomes for routing purposes.
+
+        Uses structured outputs (function calling) when supported by the LLM
+        to guarantee the response is one of the valid outcomes. Falls back
+        to simple prompting if structured outputs fail.
+
+        Args:
+            feedback: The raw human feedback text.
+            outcomes: Sequence of valid outcome strings to choose from.
+            llm: The LLM model to use. Can be a model string or BaseLLM instance.
+
+        Returns:
+            One of the outcome strings that best matches the feedback intent.
+        """
+        from typing import Literal
+
+        from pydantic import BaseModel, Field
+
+        from crewai.llm import LLM
+        from crewai.llms.base_llm import BaseLLM as BaseLLMClass
+        from crewai.utilities.i18n import get_i18n
+
+        # Get or create LLM instance
+        if isinstance(llm, str):
+            llm_instance = LLM(model=llm)
+        elif isinstance(llm, BaseLLMClass):
+            llm_instance = llm
+        else:
+            raise ValueError(f"Invalid llm type: {type(llm)}. Expected str or BaseLLM.")
+
+        # Dynamically create a Pydantic model with constrained outcomes
+        outcomes_tuple = tuple(outcomes)
+
+        class FeedbackOutcome(BaseModel):
+            """The outcome that best matches the human's feedback intent."""
+
+            outcome: Literal[outcomes_tuple] = Field(  # type: ignore[valid-type]
+                description=f"The outcome that best matches the feedback. Must be one of: {', '.join(outcomes)}"
+            )
+
+        # Load prompt from translations (using cached instance)
+        i18n = get_i18n()
+        prompt_template = i18n.slice("human_feedback_collapse")
+
+        prompt = prompt_template.format(
+            feedback=feedback,
+            outcomes=", ".join(outcomes),
+        )
+
+        try:
+            # Try structured output first (function calling)
+            # Note: LLM.call with response_model returns JSON string, not Pydantic model
+            response = llm_instance.call(
+                messages=[{"role": "user", "content": prompt}],
+                response_model=FeedbackOutcome,
+            )
+
+            # Parse the response - LLM returns JSON string when using response_model
+            if isinstance(response, str):
+                import json
+
+                try:
+                    parsed = json.loads(response)
+                    return parsed.get("outcome", outcomes[0])
+                except json.JSONDecodeError:
+                    # Not valid JSON, might be raw outcome string
+                    response_clean = response.strip()
+                    for outcome in outcomes:
+                        if outcome.lower() == response_clean.lower():
+                            return outcome
+                    return outcomes[0]
+            elif isinstance(response, FeedbackOutcome):
+                return response.outcome
+            elif hasattr(response, "outcome"):
+                return response.outcome
+            else:
+                # Unexpected type, fall back to first outcome
+                logger.warning(f"Unexpected response type: {type(response)}")
+                return outcomes[0]
+
+        except Exception as e:
+            # Fallback to simple prompting if structured output fails
+            logger.warning(
+                f"Structured output failed, falling back to simple prompting: {e}"
+            )
+            response = llm_instance.call(messages=prompt)
+            response_clean = str(response).strip()
+
+            # Exact match (case-insensitive)
+            for outcome in outcomes:
+                if outcome.lower() == response_clean.lower():
+                    return outcome
+
+            # Partial match
+            for outcome in outcomes:
+                if outcome.lower() in response_clean.lower():
+                    return outcome
+
+            # Fallback to first outcome
+            logger.warning(
+                f"Could not match LLM response '{response_clean}' to outcomes {list(outcomes)}. "
+                f"Falling back to first outcome: {outcomes[0]}"
+            )
+            return outcomes[0]
+
     def _log_flow_event(
         self,
         message: str,
-        color: PrinterColor = "yellow",
+        color: str = "yellow",
         level: Literal["info", "warning"] = "info",
     ) -> None:
         """Centralized logging method for flow events.
@@ -1452,20 +2111,22 @@ class Flow(Generic[T], metaclass=FlowMeta):
 
         Args:
             message: The message to log
-            color: Color to use for console output (default: yellow)
-                  Available colors: purple, red, bold_green, bold_purple,
-                  bold_blue, yellow, yellow
+            color: Rich style for console output (default: "yellow")
+                  Examples: "yellow", "red", "bold green", "bold magenta"
             level: Log level to use (default: info)
                   Supported levels: info, warning
 
         Note:
-            This method uses the Printer utility for colored console output
+            This method uses the centralized Rich console formatter for output
             and the standard logging module for log level support.
         """
-        self._printer.print(message, color=color)
+        from crewai.events.event_listener import event_listener
+
+        event_listener.formatter.console.print(message, style=color)
         if level == "info":
             logger.info(message)
-        logger.warning(message)
+        else:
+            logger.warning(message)
 
     def plot(self, filename: str = "crewai_flow.html", show: bool = True) -> str:
         """Create interactive HTML visualization of Flow structure.

lib/crewai/src/crewai/flow/flow_wrappers.py

@@ -70,6 +70,15 @@ class FlowMethod(Generic[P, R]):
 
                 self._is_coroutine = asyncio.coroutines._is_coroutine  # type: ignore[attr-defined]
 
+        # Preserve flow-related attributes from wrapped method (e.g., from @human_feedback)
+        for attr in [
+            "__is_router__",
+            "__router_paths__",
+            "__human_feedback_config__",
+        ]:
+            if hasattr(meth, attr):
+                setattr(self, attr, getattr(meth, attr))
+
     def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
         """Call the wrapped method.
 

lib/crewai/src/crewai/flow/human_feedback.py

@@ -0,0 +1,400 @@
+"""Human feedback decorator for Flow methods.
+
+This module provides the @human_feedback decorator that enables human-in-the-loop
+workflows within CrewAI Flows. It allows collecting human feedback on method outputs
+and optionally routing to different listeners based on the feedback.
+
+Supports both synchronous (blocking) and asynchronous (non-blocking) feedback
+collection through the provider parameter.
+
+Example (synchronous, default):
+    ```python
+    from crewai.flow import Flow, start, listen, human_feedback
+
+    class ReviewFlow(Flow):
+        @start()
+        @human_feedback(
+            message="Please review this content:",
+            emit=["approved", "rejected"],
+            llm="gpt-4o-mini",
+        )
+        def generate_content(self):
+            return {"title": "Article", "body": "Content..."}
+
+        @listen("approved")
+        def publish(self):
+            result = self.human_feedback
+            print(f"Publishing: {result.output}")
+    ```
+
+Example (asynchronous with custom provider):
+    ```python
+    from crewai.flow import Flow, start, human_feedback
+    from crewai.flow.async_feedback import HumanFeedbackProvider, HumanFeedbackPending
+
+    class SlackProvider(HumanFeedbackProvider):
+        def request_feedback(self, context, flow):
+            self.send_notification(context)
+            raise HumanFeedbackPending(context=context)
+
+    class ReviewFlow(Flow):
+        @start()
+        @human_feedback(
+            message="Review this:",
+            emit=["approved", "rejected"],
+            llm="gpt-4o-mini",
+            provider=SlackProvider(),
+        )
+        def generate_content(self):
+            return "Content..."
+    ```
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime
+from functools import wraps
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from crewai.flow.flow_wrappers import FlowMethod
+
+
+if TYPE_CHECKING:
+    from crewai.flow.async_feedback.types import HumanFeedbackProvider
+    from crewai.flow.flow import Flow
+    from crewai.llms.base_llm import BaseLLM
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass
+class HumanFeedbackResult:
+    """Result from a @human_feedback decorated method.
+
+    This dataclass captures all information about a human feedback interaction,
+    including the original method output, the human's feedback, and any
+    collapsed outcome for routing purposes.
+
+    Attributes:
+        output: The original return value from the decorated method that was
+            shown to the human for review.
+        feedback: The raw text feedback provided by the human. Empty string
+            if no feedback was provided.
+        outcome: The collapsed outcome string when emit is specified.
+            This is determined by the LLM based on the human's feedback.
+            None if emit was not specified.
+        timestamp: When the feedback was received.
+        method_name: The name of the decorated method that triggered feedback.
+        metadata: Optional metadata for enterprise integrations. Can be used
+            to pass additional context like channel, assignee, etc.
+
+    Example:
+        ```python
+        @listen("approved")
+        def handle_approval(self):
+            result = self.human_feedback
+            print(f"Output: {result.output}")
+            print(f"Feedback: {result.feedback}")
+            print(f"Outcome: {result.outcome}")  # "approved"
+        ```
+    """
+
+    output: Any
+    feedback: str
+    outcome: str | None = None
+    timestamp: datetime = field(default_factory=datetime.now)
+    method_name: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HumanFeedbackConfig:
+    """Configuration for the @human_feedback decorator.
+
+    Stores the parameters passed to the decorator for later use during
+    method execution and for introspection by visualization tools.
+
+    Attributes:
+        message: The message shown to the human when requesting feedback.
+        emit: Optional sequence of outcome strings for routing.
+        llm: The LLM model to use for collapsing feedback to outcomes.
+        default_outcome: The outcome to use when no feedback is provided.
+        metadata: Optional metadata for enterprise integrations.
+        provider: Optional custom feedback provider for async workflows.
+    """
+
+    message: str
+    emit: Sequence[str] | None = None
+    llm: str | BaseLLM | None = None
+    default_outcome: str | None = None
+    metadata: dict[str, Any] | None = None
+    provider: HumanFeedbackProvider | None = None
+
+
+class HumanFeedbackMethod(FlowMethod[Any, Any]):
+    """Wrapper for methods decorated with @human_feedback.
+
+    This wrapper extends FlowMethod to add human feedback specific attributes
+    that are used by FlowMeta for routing and by visualization tools.
+
+    Attributes:
+        __is_router__: True when emit is specified, enabling router behavior.
+        __router_paths__: List of possible outcomes when acting as a router.
+        __human_feedback_config__: The HumanFeedbackConfig for this method.
+    """
+
+    __is_router__: bool = False
+    __router_paths__: list[str] | None = None
+    __human_feedback_config__: HumanFeedbackConfig | None = None
+
+
+def human_feedback(
+    message: str,
+    emit: Sequence[str] | None = None,
+    llm: str | BaseLLM | None = None,
+    default_outcome: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    provider: HumanFeedbackProvider | None = None,
+) -> Callable[[F], F]:
+    """Decorator for Flow methods that require human feedback.
+
+    This decorator wraps a Flow method to:
+    1. Execute the method and capture its output
+    2. Display the output to the human with a feedback request
+    3. Collect the human's free-form feedback
+    4. Optionally collapse the feedback to a predefined outcome using an LLM
+    5. Store the result for access by downstream methods
+
+    When `emit` is specified, the decorator acts as a router, and the
+    collapsed outcome triggers the appropriate @listen decorated method.
+
+    Supports both synchronous (blocking) and asynchronous (non-blocking)
+    feedback collection through the `provider` parameter. If no provider
+    is specified, defaults to synchronous console input.
+
+    Args:
+        message: The message shown to the human when requesting feedback.
+            This should clearly explain what kind of feedback is expected.
+        emit: Optional sequence of outcome strings. When provided, the
+            human's feedback will be collapsed to one of these outcomes
+            using the specified LLM. The outcome then triggers @listen
+            methods that match.
+        llm: The LLM model to use for collapsing feedback to outcomes.
+            Required when emit is specified. Can be a model string
+            like "gpt-4o-mini" or a BaseLLM instance.
+        default_outcome: The outcome to use when the human provides no
+            feedback (empty input). Must be one of the emit values
+            if emit is specified.
+        metadata: Optional metadata for enterprise integrations. This is
+            passed through to the HumanFeedbackResult and can be used
+            by enterprise forks for features like Slack/Teams integration.
+        provider: Optional HumanFeedbackProvider for custom feedback
+            collection. Use this for async workflows that integrate with
+            external systems like Slack, Teams, or webhooks. When the
+            provider raises HumanFeedbackPending, the flow pauses and
+            can be resumed later with Flow.resume().
+
+    Returns:
+        A decorator function that wraps the method with human feedback
+        collection logic.
+
+    Raises:
+        ValueError: If emit is specified but llm is not provided.
+        ValueError: If default_outcome is specified but emit is not.
+        ValueError: If default_outcome is not in the emit list.
+        HumanFeedbackPending: When an async provider pauses execution.
+
+    Example:
+        Basic feedback without routing:
+        ```python
+        @start()
+        @human_feedback(message="Please review this output:")
+        def generate_content(self):
+            return "Generated content..."
+        ```
+
+        With routing based on feedback:
+        ```python
+        @start()
+        @human_feedback(
+            message="Review and approve or reject:",
+            emit=["approved", "rejected", "needs_revision"],
+            llm="gpt-4o-mini",
+            default_outcome="needs_revision",
+        )
+        def review_document(self):
+            return document_content
+
+        @listen("approved")
+        def publish(self):
+            print(f"Publishing: {self.last_human_feedback.output}")
+        ```
+
+        Async feedback with custom provider:
+        ```python
+        @start()
+        @human_feedback(
+            message="Review this content:",
+            emit=["approved", "rejected"],
+            llm="gpt-4o-mini",
+            provider=SlackProvider(channel="#reviews"),
+        )
+        def generate_content(self):
+            return "Content to review..."
+        ```
+    """
+    # Validation at decoration time
+    if emit is not None:
+        if not llm:
+            raise ValueError(
+                "llm is required when emit is specified. "
+                "Provide an LLM model string (e.g., 'gpt-4o-mini') or a BaseLLM instance."
+            )
+        if default_outcome is not None and default_outcome not in emit:
+            raise ValueError(
+                f"default_outcome '{default_outcome}' must be one of the "
+                f"emit options: {list(emit)}"
+            )
+    elif default_outcome is not None:
+        raise ValueError("default_outcome requires emit to be specified.")
+
+    def decorator(func: F) -> F:
+        """Inner decorator that wraps the function."""
+
+        def _request_feedback(flow_instance: Flow, method_output: Any) -> str:
+            """Request feedback using provider or default console."""
+            from crewai.flow.async_feedback.types import PendingFeedbackContext
+
+            # Build context for provider
+            # Use flow_id property which handles both dict and BaseModel states
+            context = PendingFeedbackContext(
+                flow_id=flow_instance.flow_id or "unknown",
+                flow_class=f"{flow_instance.__class__.__module__}.{flow_instance.__class__.__name__}",
+                method_name=func.__name__,
+                method_output=method_output,
+                message=message,
+                emit=list(emit) if emit else None,
+                default_outcome=default_outcome,
+                metadata=metadata or {},
+                llm=llm if isinstance(llm, str) else None,
+            )
+
+            if provider is not None:
+                # Use custom provider (may raise HumanFeedbackPending)
+                return provider.request_feedback(context, flow_instance)
+            else:
+                # Use default console input
+                return flow_instance._request_human_feedback(
+                    message=message,
+                    output=method_output,
+                    metadata=metadata,
+                    emit=emit,
+                )
+
+        def _process_feedback(
+            flow_instance: Flow,
+            method_output: Any,
+            raw_feedback: str,
+        ) -> HumanFeedbackResult | str:
+            """Process feedback and return result or outcome."""
+            # Determine outcome
+            collapsed_outcome: str | None = None
+
+            if not raw_feedback.strip():
+                # Empty feedback
+                if default_outcome:
+                    collapsed_outcome = default_outcome
+                elif emit:
+                    # No default and no feedback - use first outcome
+                    collapsed_outcome = emit[0]
+            elif emit:
+                # Collapse feedback to outcome using LLM
+                collapsed_outcome = flow_instance._collapse_to_outcome(
+                    feedback=raw_feedback,
+                    outcomes=emit,
+                    llm=llm,
+                )
+
+            # Create result
+            result = HumanFeedbackResult(
+                output=method_output,
+                feedback=raw_feedback,
+                outcome=collapsed_outcome,
+                timestamp=datetime.now(),
+                method_name=func.__name__,
+                metadata=metadata or {},
+            )
+
+            # Store in flow instance
+            flow_instance.human_feedback_history.append(result)
+            flow_instance.last_human_feedback = result
+
+            # Return based on mode
+            if emit:
+                # Return outcome for routing
+                return collapsed_outcome  # type: ignore[return-value]
+            return result
+
+        if asyncio.iscoroutinefunction(func):
+            # Async wrapper
+            @wraps(func)
+            async def async_wrapper(self: Flow, *args: Any, **kwargs: Any) -> Any:
+                # Execute the original method
+                method_output = await func(self, *args, **kwargs)
+
+                # Request human feedback (may raise HumanFeedbackPending)
+                raw_feedback = _request_feedback(self, method_output)
+
+                # Process and return
+                return _process_feedback(self, method_output, raw_feedback)
+
+            wrapper: Any = async_wrapper
+        else:
+            # Sync wrapper
+            @wraps(func)
+            def sync_wrapper(self: Flow, *args: Any, **kwargs: Any) -> Any:
+                # Execute the original method
+                method_output = func(self, *args, **kwargs)
+
+                # Request human feedback (may raise HumanFeedbackPending)
+                raw_feedback = _request_feedback(self, method_output)
+
+                # Process and return
+                return _process_feedback(self, method_output, raw_feedback)
+
+            wrapper = sync_wrapper
+
+        # Preserve existing Flow decorator attributes
+        for attr in [
+            "__is_start_method__",
+            "__trigger_methods__",
+            "__condition_type__",
+            "__trigger_condition__",
+            "__is_flow_method__",
+        ]:
+            if hasattr(func, attr):
+                setattr(wrapper, attr, getattr(func, attr))
+
+        # Add human feedback specific attributes (create config inline to avoid race conditions)
+        wrapper.__human_feedback_config__ = HumanFeedbackConfig(
+            message=message,
+            emit=emit,
+            llm=llm,
+            default_outcome=default_outcome,
+            metadata=metadata,
+            provider=provider,
+        )
+        wrapper.__is_flow_method__ = True
+
+        # Make it a router if emit specified
+        if emit:
+            wrapper.__is_router__ = True
+            wrapper.__router_paths__ = list(emit)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

lib/crewai/src/crewai/flow/persistence/base.py

@@ -1,16 +1,26 @@
 """Base class for flow state persistence."""
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel
 
+if TYPE_CHECKING:
+    from crewai.flow.async_feedback.types import PendingFeedbackContext
+
 
 class FlowPersistence(ABC):
     """Abstract base class for flow state persistence.
 
     This class defines the interface that all persistence implementations must follow.
     It supports both structured (Pydantic BaseModel) and unstructured (dict) states.
+
+    For async human feedback support, implementations can optionally override:
+    - save_pending_feedback(): Saves state with pending feedback context
+    - load_pending_feedback(): Loads state and pending feedback context
+    - clear_pending_feedback(): Clears pending feedback after resume
     """
 
     @abstractmethod
@@ -45,3 +55,52 @@ class FlowPersistence(ABC):
         Returns:
             The most recent state as a dictionary, or None if no state exists
         """
+
+    def save_pending_feedback(
+        self,
+        flow_uuid: str,
+        context: PendingFeedbackContext,
+        state_data: dict[str, Any] | BaseModel,
+    ) -> None:
+        """Save state with a pending feedback marker.
+
+        This method is called when a flow is paused waiting for async human
+        feedback. The default implementation just saves the state without
+        the pending feedback context. Override to store the context.
+
+        Args:
+            flow_uuid: Unique identifier for the flow instance
+            context: The pending feedback context with all resume information
+            state_data: Current state data
+        """
+        # Default: just save the state without pending context
+        self.save_state(flow_uuid, context.method_name, state_data)
+
+    def load_pending_feedback(
+        self,
+        flow_uuid: str,
+    ) -> tuple[dict[str, Any], PendingFeedbackContext] | None:
+        """Load state and pending feedback context.
+
+        This method is called when resuming a paused flow. Override to
+        load both the state and the pending feedback context.
+
+        Args:
+            flow_uuid: Unique identifier for the flow instance
+
+        Returns:
+            Tuple of (state_data, pending_context) if pending feedback exists,
+            None otherwise.
+        """
+        return None
+
+    def clear_pending_feedback(self, flow_uuid: str) -> None:  # noqa: B027
+        """Clear the pending feedback marker after successful resume.
+
+        This is called after feedback is received and the flow resumes.
+        Optional override to remove the pending feedback marker.
+
+        Args:
+            flow_uuid: Unique identifier for the flow instance
+        """
+        pass

lib/crewai/src/crewai/flow/persistence/sqlite.py

@@ -2,17 +2,22 @@
 SQLite-based implementation of flow state persistence.
 """
 
+from __future__ import annotations
+
 from datetime import datetime, timezone
 import json
 from pathlib import Path
 import sqlite3
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel
 
 from crewai.flow.persistence.base import FlowPersistence
 from crewai.utilities.paths import db_storage_path
 
+if TYPE_CHECKING:
+    from crewai.flow.async_feedback.types import PendingFeedbackContext
+
 
 class SQLiteFlowPersistence(FlowPersistence):
     """SQLite-based implementation of flow state persistence.
@@ -20,6 +25,28 @@ class SQLiteFlowPersistence(FlowPersistence):
     This class provides a simple, file-based persistence implementation using SQLite.
     It's suitable for development and testing, or for production use cases with
     moderate performance requirements.
+
+    This implementation supports async human feedback by storing pending feedback
+    context in a separate table. When a flow is paused waiting for feedback,
+    use save_pending_feedback() to persist the context. Later, use
+    load_pending_feedback() to retrieve it when resuming.
+
+    Example:
+        ```python
+        persistence = SQLiteFlowPersistence("flows.db")
+
+        # Start a flow with async feedback
+        try:
+            flow = MyFlow(persistence=persistence)
+            result = flow.kickoff()
+        except HumanFeedbackPending as e:
+            # Flow is paused, state is already persisted
+            print(f"Waiting for feedback: {e.context.flow_id}")
+
+        # Later, resume with feedback
+        flow = MyFlow.from_pending("abc-123", persistence)
+        result = flow.resume("looks good!")
+        ```
     """
 
     def __init__(self, db_path: str | None = None) -> None:
@@ -45,6 +72,7 @@ class SQLiteFlowPersistence(FlowPersistence):
     def init_db(self) -> None:
         """Create the necessary tables if they don't exist."""
         with sqlite3.connect(self.db_path) as conn:
+            # Main state table
             conn.execute(
                 """
             CREATE TABLE IF NOT EXISTS flow_states (
@@ -64,6 +92,26 @@ class SQLiteFlowPersistence(FlowPersistence):
             """
             )
 
+            # Pending feedback table for async HITL
+            conn.execute(
+                """
+            CREATE TABLE IF NOT EXISTS pending_feedback (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                flow_uuid TEXT NOT NULL UNIQUE,
+                context_json TEXT NOT NULL,
+                state_json TEXT NOT NULL,
+                created_at DATETIME NOT NULL
+            )
+            """
+            )
+            # Add index for faster UUID lookups on pending feedback
+            conn.execute(
+                """
+            CREATE INDEX IF NOT EXISTS idx_pending_feedback_uuid
+            ON pending_feedback(flow_uuid)
+            """
+            )
+
     def save_state(
         self,
         flow_uuid: str,
@@ -130,3 +178,104 @@ class SQLiteFlowPersistence(FlowPersistence):
         if row:
             return json.loads(row[0])
         return None
+
+    def save_pending_feedback(
+        self,
+        flow_uuid: str,
+        context: PendingFeedbackContext,
+        state_data: dict[str, Any] | BaseModel,
+    ) -> None:
+        """Save state with a pending feedback marker.
+
+        This method stores both the flow state and the pending feedback context,
+        allowing the flow to be resumed later when feedback is received.
+
+        Args:
+            flow_uuid: Unique identifier for the flow instance
+            context: The pending feedback context with all resume information
+            state_data: Current state data
+        """
+        # Import here to avoid circular imports
+        from crewai.flow.async_feedback.types import PendingFeedbackContext
+
+        # Convert state_data to dict
+        if isinstance(state_data, BaseModel):
+            state_dict = state_data.model_dump()
+        elif isinstance(state_data, dict):
+            state_dict = state_data
+        else:
+            raise ValueError(
+                f"state_data must be either a Pydantic BaseModel or dict, got {type(state_data)}"
+            )
+
+        # Also save to regular state table for consistency
+        self.save_state(flow_uuid, context.method_name, state_data)
+
+        # Save pending feedback context
+        with sqlite3.connect(self.db_path) as conn:
+            # Use INSERT OR REPLACE to handle re-triggering feedback on same flow
+            conn.execute(
+                """
+            INSERT OR REPLACE INTO pending_feedback (
+                flow_uuid,
+                context_json,
+                state_json,
+                created_at
+            ) VALUES (?, ?, ?, ?)
+            """,
+                (
+                    flow_uuid,
+                    json.dumps(context.to_dict()),
+                    json.dumps(state_dict),
+                    datetime.now(timezone.utc).isoformat(),
+                ),
+            )
+
+    def load_pending_feedback(
+        self,
+        flow_uuid: str,
+    ) -> tuple[dict[str, Any], PendingFeedbackContext] | None:
+        """Load state and pending feedback context.
+
+        Args:
+            flow_uuid: Unique identifier for the flow instance
+
+        Returns:
+            Tuple of (state_data, pending_context) if pending feedback exists,
+            None otherwise.
+        """
+        # Import here to avoid circular imports
+        from crewai.flow.async_feedback.types import PendingFeedbackContext
+
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.execute(
+                """
+            SELECT state_json, context_json
+            FROM pending_feedback
+            WHERE flow_uuid = ?
+            """,
+                (flow_uuid,),
+            )
+            row = cursor.fetchone()
+
+        if row:
+            state_dict = json.loads(row[0])
+            context_dict = json.loads(row[1])
+            context = PendingFeedbackContext.from_dict(context_dict)
+            return (state_dict, context)
+        return None
+
+    def clear_pending_feedback(self, flow_uuid: str) -> None:
+        """Clear the pending feedback marker after successful resume.
+
+        Args:
+            flow_uuid: Unique identifier for the flow instance
+        """
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute(
+                """
+            DELETE FROM pending_feedback
+            WHERE flow_uuid = ?
+            """,
+                (flow_uuid,),
+            )

lib/crewai/src/crewai/llms/providers/azure/completion.py

@@ -9,10 +9,10 @@ from pydantic import BaseModel
 from typing_extensions import Self
 
 from crewai.utilities.agent_utils import is_context_length_exceeded
-from crewai.utilities.converter import generate_model_description
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
     LLMContextLengthExceededError,
 )
+from crewai.utilities.pydantic_schema_utils import generate_model_description
 from crewai.utilities.types import LLMMessage
 
 

lib/crewai/src/crewai/llms/providers/openai/completion.py

@@ -18,10 +18,10 @@ from crewai.events.types.llm_events import LLMCallType
 from crewai.llms.base_llm import BaseLLM
 from crewai.llms.hooks.transport import AsyncHTTPTransport, HTTPTransport
 from crewai.utilities.agent_utils import is_context_length_exceeded
-from crewai.utilities.converter import generate_model_description
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
     LLMContextLengthExceededError,
 )
+from crewai.utilities.pydantic_schema_utils import generate_model_description
 from crewai.utilities.types import LLMMessage
 
 

lib/crewai/src/crewai/task.py

@@ -494,8 +494,11 @@ class Task(BaseModel):
         future: Future[TaskOutput],
     ) -> None:
         """Execute the task asynchronously with context handling."""
-        result = self._execute_core(agent, context, tools)
-        future.set_result(result)
+        try:
+          result = self._execute_core(agent, context, tools)
+          future.set_result(result)
+        except Exception as e:
+          future.set_exception(e)
 
     async def aexecute_sync(
         self,

lib/crewai/src/crewai/tools/base_tool.py

@@ -3,15 +3,13 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 import asyncio
 from collections.abc import Awaitable, Callable
-from inspect import signature
+from inspect import Parameter, signature
+import json
 from typing import (
     Any,
     Generic,
     ParamSpec,
     TypeVar,
-    cast,
-    get_args,
-    get_origin,
     overload,
 )
 
@@ -27,6 +25,7 @@ from typing_extensions import TypeIs
 
 from crewai.tools.structured_tool import CrewStructuredTool
 from crewai.utilities.printer import Printer
+from crewai.utilities.pydantic_schema_utils import generate_model_description
 
 
 _printer = Printer()
@@ -103,20 +102,40 @@ class BaseTool(BaseModel, ABC):
         if v != cls._ArgsSchemaPlaceholder:
             return v
 
-        return cast(
-            type[PydanticBaseModel],
-            type(
-                f"{cls.__name__}Schema",
-                (PydanticBaseModel,),
-                {
-                    "__annotations__": {
-                        k: v
-                        for k, v in cls._run.__annotations__.items()
-                        if k != "return"
-                    },
-                },
-            ),
-        )
+        run_sig = signature(cls._run)
+        fields: dict[str, Any] = {}
+
+        for param_name, param in run_sig.parameters.items():
+            if param_name in ("self", "return"):
+                continue
+            if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
+                continue
+
+            annotation = param.annotation if param.annotation != param.empty else Any
+
+            if param.default is param.empty:
+                fields[param_name] = (annotation, ...)
+            else:
+                fields[param_name] = (annotation, param.default)
+
+        if not fields:
+            arun_sig = signature(cls._arun)
+            for param_name, param in arun_sig.parameters.items():
+                if param_name in ("self", "return"):
+                    continue
+                if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
+                    continue
+
+                annotation = (
+                    param.annotation if param.annotation != param.empty else Any
+                )
+
+                if param.default is param.empty:
+                    fields[param_name] = (annotation, ...)
+                else:
+                    fields[param_name] = (annotation, param.default)
+
+        return create_model(f"{cls.__name__}Schema", **fields)
 
     @field_validator("max_usage_count", mode="before")
     @classmethod
@@ -226,24 +245,23 @@ class BaseTool(BaseModel, ABC):
         args_schema = getattr(tool, "args_schema", None)
 
         if args_schema is None:
-            # Infer args_schema from the function signature if not provided
             func_signature = signature(tool.func)
-            annotations = func_signature.parameters
-            args_fields: dict[str, Any] = {}
-            for name, param in annotations.items():
-                if name != "self":
-                    param_annotation = (
-                        param.annotation if param.annotation != param.empty else Any
-                    )
-                    field_info = Field(
-                        default=...,
-                        description="",
-                    )
-                    args_fields[name] = (param_annotation, field_info)
-            if args_fields:
-                args_schema = create_model(f"{tool.name}Input", **args_fields)
+            fields: dict[str, Any] = {}
+            for name, param in func_signature.parameters.items():
+                if name == "self":
+                    continue
+                if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
+                    continue
+                param_annotation = (
+                    param.annotation if param.annotation != param.empty else Any
+                )
+                if param.default is param.empty:
+                    fields[name] = (param_annotation, ...)
+                else:
+                    fields[name] = (param_annotation, param.default)
+            if fields:
+                args_schema = create_model(f"{tool.name}Input", **fields)
             else:
-                # Create a default schema with no fields if no parameters are found
                 args_schema = create_model(
                     f"{tool.name}Input", __base__=PydanticBaseModel
                 )
@@ -257,53 +275,37 @@ class BaseTool(BaseModel, ABC):
 
     def _set_args_schema(self) -> None:
         if self.args_schema is None:
-            class_name = f"{self.__class__.__name__}Schema"
-            self.args_schema = cast(
-                type[PydanticBaseModel],
-                type(
-                    class_name,
-                    (PydanticBaseModel,),
-                    {
-                        "__annotations__": {
-                            k: v
-                            for k, v in self._run.__annotations__.items()
-                            if k != "return"
-                        },
-                    },
-                ),
+            run_sig = signature(self._run)
+            fields: dict[str, Any] = {}
+
+            for param_name, param in run_sig.parameters.items():
+                if param_name in ("self", "return"):
+                    continue
+                if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
+                    continue
+
+                annotation = (
+                    param.annotation if param.annotation != param.empty else Any
+                )
+
+                if param.default is param.empty:
+                    fields[param_name] = (annotation, ...)
+                else:
+                    fields[param_name] = (annotation, param.default)
+
+            self.args_schema = create_model(
+                f"{self.__class__.__name__}Schema", **fields
             )
 
     def _generate_description(self) -> None:
-        args_schema = {
-            name: {
-                "description": field.description,
-                "type": BaseTool._get_arg_annotations(field.annotation),
-            }
-            for name, field in self.args_schema.model_fields.items()
-        }
-
-        self.description = f"Tool Name: {self.name}\nTool Arguments: {args_schema}\nTool Description: {self.description}"
-
-    @staticmethod
-    def _get_arg_annotations(annotation: type[Any] | None) -> str:
-        if annotation is None:
-            return "None"
-
-        origin = get_origin(annotation)
-        args = get_args(annotation)
-
-        if origin is None:
-            return (
-                annotation.__name__
-                if hasattr(annotation, "__name__")
-                else str(annotation)
-            )
-
-        if args:
-            args_str = ", ".join(BaseTool._get_arg_annotations(arg) for arg in args)
-            return str(f"{origin.__name__}[{args_str}]")
-
-        return str(origin.__name__)
+        """Generate the tool description with a JSON schema for arguments."""
+        schema = generate_model_description(self.args_schema)
+        args_json = json.dumps(schema["json_schema"]["schema"], indent=2)
+        self.description = (
+            f"Tool Name: {self.name}\n"
+            f"Tool Arguments: {args_json}\n"
+            f"Tool Description: {self.description}"
+        )
 
 
 class Tool(BaseTool, Generic[P, R]):
@@ -406,24 +408,23 @@ class Tool(BaseTool, Generic[P, R]):
         args_schema = getattr(tool, "args_schema", None)
 
         if args_schema is None:
-            # Infer args_schema from the function signature if not provided
             func_signature = signature(tool.func)
-            annotations = func_signature.parameters
-            args_fields: dict[str, Any] = {}
-            for name, param in annotations.items():
-                if name != "self":
-                    param_annotation = (
-                        param.annotation if param.annotation != param.empty else Any
-                    )
-                    field_info = Field(
-                        default=...,
-                        description="",
-                    )
-                    args_fields[name] = (param_annotation, field_info)
-            if args_fields:
-                args_schema = create_model(f"{tool.name}Input", **args_fields)
+            fields: dict[str, Any] = {}
+            for name, param in func_signature.parameters.items():
+                if name == "self":
+                    continue
+                if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
+                    continue
+                param_annotation = (
+                    param.annotation if param.annotation != param.empty else Any
+                )
+                if param.default is param.empty:
+                    fields[name] = (param_annotation, ...)
+                else:
+                    fields[name] = (param_annotation, param.default)
+            if fields:
+                args_schema = create_model(f"{tool.name}Input", **fields)
             else:
-                # Create a default schema with no fields if no parameters are found
                 args_schema = create_model(
                     f"{tool.name}Input", __base__=PydanticBaseModel
                 )
@@ -502,32 +503,38 @@ def tool(
         def _make_tool(f: Callable[P2, R2]) -> Tool[P2, R2]:
             if f.__doc__ is None:
                 raise ValueError("Function must have a docstring")
-
-            func_annotations = getattr(f, "__annotations__", None)
-            if func_annotations is None:
+            if f.__annotations__ is None:
                 raise ValueError("Function must have type annotations")
 
+            func_sig = signature(f)
+            fields: dict[str, Any] = {}
+
+            for param_name, param in func_sig.parameters.items():
+                if param_name == "return":
+                    continue
+                if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
+                    continue
+
+                annotation = (
+                    param.annotation if param.annotation != param.empty else Any
+                )
+
+                if param.default is param.empty:
+                    fields[param_name] = (annotation, ...)
+                else:
+                    fields[param_name] = (annotation, param.default)
+
             class_name = "".join(tool_name.split()).title()
-            tool_args_schema = cast(
-                type[PydanticBaseModel],
-                type(
-                    class_name,
-                    (PydanticBaseModel,),
-                    {
-                        "__annotations__": {
-                            k: v for k, v in func_annotations.items() if k != "return"
-                        },
-                    },
-                ),
-            )
+            args_schema = create_model(class_name, **fields)
 
             return Tool(
                 name=tool_name,
                 description=f.__doc__,
                 func=f,
-                args_schema=tool_args_schema,
+                args_schema=args_schema,
                 result_as_answer=result_as_answer,
                 max_usage_count=max_usage_count,
+                current_usage_count=0,
             )
 
         return _make_tool

lib/crewai/src/crewai/translations/en.json

@@ -29,7 +29,8 @@
     "lite_agent_system_prompt_without_tools": "You are {role}. {backstory}\nYour personal goal is: {goal}\n\nTo give my best complete final answer to the task respond using the exact following format:\n\nThought: I now can give a great answer\nFinal Answer: Your final answer must be the great and the most complete as possible, it must be outcome described.\n\nI MUST use these formats, my job depends on it!",
     "lite_agent_response_format": "Ensure your final answer strictly adheres to the following OpenAPI schema: {response_format}\n\nDo not include the OpenAPI schema in the final output. Ensure the final output does not include any code block markers like ```json or ```python.",
     "knowledge_search_query": "The original query is: {task_prompt}.",
-    "knowledge_search_query_system_prompt": "Your goal is to rewrite the user query so that it is optimized for retrieval from a vector database. Consider how the query will be used to find relevant documents, and aim to make it more specific and context-aware. \n\n Do not include any other text than the rewritten query, especially any preamble or postamble and only add expected output format if its relevant to the rewritten query. \n\n Focus on the key words of the intended task and to retrieve the most relevant information. \n\n There will be some extra context provided that might need to be removed such as expected_output formats structured_outputs and other instructions."
+    "knowledge_search_query_system_prompt": "Your goal is to rewrite the user query so that it is optimized for retrieval from a vector database. Consider how the query will be used to find relevant documents, and aim to make it more specific and context-aware. \n\n Do not include any other text than the rewritten query, especially any preamble or postamble and only add expected output format if its relevant to the rewritten query. \n\n Focus on the key words of the intended task and to retrieve the most relevant information. \n\n There will be some extra context provided that might need to be removed such as expected_output formats structured_outputs and other instructions.",
+    "human_feedback_collapse": "Based on the following human feedback, determine which outcome best matches their intent.\n\nFeedback: {feedback}\n\nPossible outcomes: {outcomes}\n\nRespond with ONLY one of the exact outcome values listed above, nothing else."
   },
   "errors": {
     "force_final_answer_error": "You can't keep going, here is the best final answer you generated:\n\n {formatted_answer}",

lib/crewai/src/crewai/utilities/constants.py

@@ -30,4 +30,3 @@ NOT_SPECIFIED: Final[
         "allows us to distinguish between 'not passed at all' and 'explicitly passed None' or '[]'.",
     ]
 ] = _NotSpecified()
-CREWAI_BASE_URL: Final[str] = "https://app.crewai.com"

lib/crewai/src/crewai/utilities/converter.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-from collections.abc import Callable
-from copy import deepcopy
 import json
 import re
 from typing import TYPE_CHECKING, Any, Final, TypedDict
@@ -13,6 +11,7 @@ from crewai.agents.agent_builder.utilities.base_output_converter import OutputCo
 from crewai.utilities.i18n import get_i18n
 from crewai.utilities.internal_instructor import InternalInstructor
 from crewai.utilities.printer import Printer
+from crewai.utilities.pydantic_schema_utils import generate_model_description
 
 
 if TYPE_CHECKING:
@@ -421,221 +420,3 @@ def create_converter(
         raise Exception("No output converter found or set.")
 
     return converter  # type: ignore[no-any-return]
-
-
-def resolve_refs(schema: dict[str, Any]) -> dict[str, Any]:
-    """Recursively resolve all local $refs in the given JSON Schema using $defs as the source.
-
-    This is needed because Pydantic generates $ref-based schemas that
-    some consumers (e.g. LLMs, tool frameworks) don't handle well.
-
-    Args:
-        schema: JSON Schema dict that may contain "$refs" and "$defs".
-
-    Returns:
-        A new schema dictionary with all local $refs replaced by their definitions.
-    """
-    defs = schema.get("$defs", {})
-    schema_copy = deepcopy(schema)
-
-    def _resolve(node: Any) -> Any:
-        if isinstance(node, dict):
-            ref = node.get("$ref")
-            if isinstance(ref, str) and ref.startswith("#/$defs/"):
-                def_name = ref.replace("#/$defs/", "")
-                if def_name in defs:
-                    return _resolve(deepcopy(defs[def_name]))
-                raise KeyError(f"Definition '{def_name}' not found in $defs.")
-            return {k: _resolve(v) for k, v in node.items()}
-
-        if isinstance(node, list):
-            return [_resolve(i) for i in node]
-
-        return node
-
-    return _resolve(schema_copy)  # type: ignore[no-any-return]
-
-
-def add_key_in_dict_recursively(
-    d: dict[str, Any], key: str, value: Any, criteria: Callable[[dict[str, Any]], bool]
-) -> dict[str, Any]:
-    """Recursively adds a key/value pair to all nested dicts matching `criteria`."""
-    if isinstance(d, dict):
-        if criteria(d) and key not in d:
-            d[key] = value
-        for v in d.values():
-            add_key_in_dict_recursively(v, key, value, criteria)
-    elif isinstance(d, list):
-        for i in d:
-            add_key_in_dict_recursively(i, key, value, criteria)
-    return d
-
-
-def fix_discriminator_mappings(schema: dict[str, Any]) -> dict[str, Any]:
-    """Replace '#/$defs/...' references in discriminator.mapping with just the model name."""
-    output = schema.get("properties", {}).get("output")
-    if not output:
-        return schema
-
-    disc = output.get("discriminator")
-    if not disc or "mapping" not in disc:
-        return schema
-
-    disc["mapping"] = {k: v.split("/")[-1] for k, v in disc["mapping"].items()}
-    return schema
-
-
-def add_const_to_oneof_variants(schema: dict[str, Any]) -> dict[str, Any]:
-    """Add const fields to oneOf variants for discriminated unions.
-
-    The json_schema_to_pydantic library requires each oneOf variant to have
-    a const field for the discriminator property. This function adds those
-    const fields based on the discriminator mapping.
-
-    Args:
-        schema: JSON Schema dict that may contain discriminated unions
-
-    Returns:
-        Modified schema with const fields added to oneOf variants
-    """
-
-    def _process_oneof(node: dict[str, Any]) -> dict[str, Any]:
-        """Process a single node that might contain a oneOf with discriminator."""
-        if not isinstance(node, dict):
-            return node
-
-        if "oneOf" in node and "discriminator" in node:
-            discriminator = node["discriminator"]
-            property_name = discriminator.get("propertyName")
-            mapping = discriminator.get("mapping", {})
-
-            if property_name and mapping:
-                one_of_variants = node.get("oneOf", [])
-
-                for variant in one_of_variants:
-                    if isinstance(variant, dict) and "properties" in variant:
-                        variant_title = variant.get("title", "")
-
-                        matched_disc_value = None
-                        for disc_value, schema_name in mapping.items():
-                            if variant_title == schema_name or variant_title.endswith(
-                                schema_name
-                            ):
-                                matched_disc_value = disc_value
-                                break
-
-                        if matched_disc_value is not None:
-                            props = variant["properties"]
-                            if property_name in props:
-                                props[property_name]["const"] = matched_disc_value
-
-        for key, value in node.items():
-            if isinstance(value, dict):
-                node[key] = _process_oneof(value)
-            elif isinstance(value, list):
-                node[key] = [
-                    _process_oneof(item) if isinstance(item, dict) else item
-                    for item in value
-                ]
-
-        return node
-
-    return _process_oneof(deepcopy(schema))
-
-
-def convert_oneof_to_anyof(schema: dict[str, Any]) -> dict[str, Any]:
-    """Convert oneOf to anyOf for OpenAI compatibility.
-
-    OpenAI's Structured Outputs support anyOf better than oneOf.
-    This recursively converts all oneOf occurrences to anyOf.
-
-    Args:
-        schema: JSON schema dictionary.
-
-    Returns:
-        Modified schema with anyOf instead of oneOf.
-    """
-    if isinstance(schema, dict):
-        if "oneOf" in schema:
-            schema["anyOf"] = schema.pop("oneOf")
-
-        for value in schema.values():
-            if isinstance(value, dict):
-                convert_oneof_to_anyof(value)
-            elif isinstance(value, list):
-                for item in value:
-                    if isinstance(item, dict):
-                        convert_oneof_to_anyof(item)
-
-    return schema
-
-
-def ensure_all_properties_required(schema: dict[str, Any]) -> dict[str, Any]:
-    """Ensure all properties are in the required array for OpenAI strict mode.
-
-    OpenAI's strict structured outputs require all properties to be listed
-    in the required array. This recursively updates all objects to include
-    all their properties in required.
-
-    Args:
-        schema: JSON schema dictionary.
-
-    Returns:
-        Modified schema with all properties marked as required.
-    """
-    if isinstance(schema, dict):
-        if schema.get("type") == "object" and "properties" in schema:
-            properties = schema["properties"]
-            if properties:
-                schema["required"] = list(properties.keys())
-
-        for value in schema.values():
-            if isinstance(value, dict):
-                ensure_all_properties_required(value)
-            elif isinstance(value, list):
-                for item in value:
-                    if isinstance(item, dict):
-                        ensure_all_properties_required(item)
-
-    return schema
-
-
-def generate_model_description(model: type[BaseModel]) -> dict[str, Any]:
-    """Generate JSON schema description of a Pydantic model.
-
-    This function takes a Pydantic model class and returns its JSON schema,
-    which includes full type information, discriminators, and all metadata.
-    The schema is dereferenced to inline all $ref references for better LLM understanding.
-
-    Args:
-        model: A Pydantic model class.
-
-    Returns:
-        A JSON schema dictionary representation of the model.
-    """
-
-    json_schema = model.model_json_schema(ref_template="#/$defs/{model}")
-
-    json_schema = add_key_in_dict_recursively(
-        json_schema,
-        key="additionalProperties",
-        value=False,
-        criteria=lambda d: d.get("type") == "object"
-        and "additionalProperties" not in d,
-    )
-
-    json_schema = resolve_refs(json_schema)
-
-    json_schema.pop("$defs", None)
-    json_schema = fix_discriminator_mappings(json_schema)
-    json_schema = convert_oneof_to_anyof(json_schema)
-    json_schema = ensure_all_properties_required(json_schema)
-
-    return {
-        "type": "json_schema",
-        "json_schema": {
-            "name": model.__name__,
-            "strict": True,
-            "schema": json_schema,
-        },
-    }

lib/crewai/src/crewai/utilities/evaluators/task_evaluator.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, cast
+import json
+from typing import TYPE_CHECKING, Any, cast
 
 from pydantic import BaseModel, Field
 
 from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.task_events import TaskEvaluationEvent
-from crewai.llm import LLM
 from crewai.utilities.converter import Converter
-from crewai.utilities.pydantic_schema_parser import PydanticSchemaParser
+from crewai.utilities.i18n import get_i18n
+from crewai.utilities.pydantic_schema_utils import generate_model_description
 from crewai.utilities.training_converter import TrainingConverter
 
 
@@ -62,7 +63,7 @@ class TaskEvaluator:
         Args:
             original_agent: The agent to evaluate.
         """
-        self.llm = cast(LLM, original_agent.llm)
+        self.llm = original_agent.llm
         self.original_agent = original_agent
 
     def evaluate(self, task: Task, output: str) -> TaskEvaluation:
@@ -79,7 +80,8 @@ class TaskEvaluator:
             - Investigate the Converter.to_pydantic signature, returns BaseModel strictly?
         """
         crewai_event_bus.emit(
-            self, TaskEvaluationEvent(evaluation_type="task_evaluation", task=task)
+            self,
+            TaskEvaluationEvent(evaluation_type="task_evaluation", task=task),  # type: ignore[no-untyped-call]
         )
         evaluation_query = (
             f"Assess the quality of the task completed based on the description, expected output, and actual results.\n\n"
@@ -94,9 +96,14 @@ class TaskEvaluator:
 
         instructions = "Convert all responses into valid JSON output."
 
-        if not self.llm.supports_function_calling():
-            model_schema = PydanticSchemaParser(model=TaskEvaluation).get_schema()
-            instructions = f"{instructions}\n\nReturn only valid JSON with the following schema:\n```json\n{model_schema}\n```"
+        if not self.llm.supports_function_calling():  # type: ignore[union-attr]
+            schema_dict = generate_model_description(TaskEvaluation)
+            output_schema: str = (
+                get_i18n()
+                .slice("formatted_task_instructions")
+                .format(output_format=json.dumps(schema_dict, indent=2))
+            )
+            instructions = f"{instructions}\n\n{output_schema}"
 
         converter = Converter(
             llm=self.llm,
@@ -108,7 +115,7 @@ class TaskEvaluator:
         return cast(TaskEvaluation, converter.to_pydantic())
 
     def evaluate_training_data(
-        self, training_data: dict, agent_id: str
+        self, training_data: dict[str, Any], agent_id: str
     ) -> TrainingTaskEvaluation:
         """
         Evaluate the training data based on the llm output, human feedback, and improved output.
@@ -121,7 +128,8 @@ class TaskEvaluator:
             - Investigate the Converter.to_pydantic signature, returns BaseModel strictly?
         """
         crewai_event_bus.emit(
-            self, TaskEvaluationEvent(evaluation_type="training_data_evaluation")
+            self,
+            TaskEvaluationEvent(evaluation_type="training_data_evaluation"),  # type: ignore[no-untyped-call]
         )
 
         output_training_data = training_data[agent_id]
@@ -164,11 +172,14 @@ class TaskEvaluator:
         )
         instructions = "I'm gonna convert this raw text into valid JSON."
 
-        if not self.llm.supports_function_calling():
-            model_schema = PydanticSchemaParser(
-                model=TrainingTaskEvaluation
-            ).get_schema()
-            instructions = f"{instructions}\n\nThe json should have the following structure, with the following keys:\n{model_schema}"
+        if not self.llm.supports_function_calling():  # type: ignore[union-attr]
+            schema_dict = generate_model_description(TrainingTaskEvaluation)
+            output_schema: str = (
+                get_i18n()
+                .slice("formatted_task_instructions")
+                .format(output_format=json.dumps(schema_dict, indent=2))
+            )
+            instructions = f"{instructions}\n\n{output_schema}"
 
         converter = TrainingConverter(
             llm=self.llm,

lib/crewai/src/crewai/utilities/planning_handler.py

@@ -15,9 +15,12 @@ logger = logging.getLogger(__name__)
 class PlanPerTask(BaseModel):
     """Represents a plan for a specific task."""
 
-    task: str = Field(..., description="The task for which the plan is created")
+    task_number: int = Field(
+        description="The 1-indexed task number this plan corresponds to",
+        ge=1,
+    )
+    task: str = Field(description="The task for which the plan is created")
     plan: str = Field(
-        ...,
         description="The step by step plan on how the agents can execute their tasks using the available tools with mastery",
     )
 

lib/crewai/src/crewai/utilities/pydantic_schema_parser.py

@@ -1,103 +0,0 @@
-from typing import Any, Union, get_args, get_origin
-
-from pydantic import BaseModel, Field
-
-
-class PydanticSchemaParser(BaseModel):
-    model: type[BaseModel] = Field(..., description="The Pydantic model to parse.")
-
-    def get_schema(self) -> str:
-        """Public method to get the schema of a Pydantic model.
-
-        Returns:
-            String representation of the model schema.
-        """
-        return "{\n" + self._get_model_schema(self.model) + "\n}"
-
-    def _get_model_schema(self, model: type[BaseModel], depth: int = 0) -> str:
-        """Recursively get the schema of a Pydantic model, handling nested models and lists.
-
-        Args:
-            model: The Pydantic model to process.
-            depth: The current depth of recursion for indentation purposes.
-
-        Returns:
-            A string representation of the model schema.
-        """
-        indent: str = " " * 4 * depth
-        lines: list[str] = [
-            f"{indent}    {field_name}: {self._get_field_type_for_annotation(field.annotation, depth + 1)}"
-            for field_name, field in model.model_fields.items()
-        ]
-        return ",\n".join(lines)
-
-    def _format_list_type(self, list_item_type: Any, depth: int) -> str:
-        """Format a List type, handling nested models if necessary.
-
-        Args:
-            list_item_type: The type of items in the list.
-            depth: The current depth of recursion for indentation purposes.
-
-        Returns:
-            A string representation of the List type.
-        """
-        if isinstance(list_item_type, type) and issubclass(list_item_type, BaseModel):
-            nested_schema = self._get_model_schema(list_item_type, depth + 1)
-            nested_indent = " " * 4 * depth
-            return f"List[\n{nested_indent}{{\n{nested_schema}\n{nested_indent}}}\n{nested_indent}]"
-        return f"List[{list_item_type.__name__}]"
-
-    def _format_union_type(self, field_type: Any, depth: int) -> str:
-        """Format a Union type, handling Optional and nested types.
-
-        Args:
-            field_type: The Union type to format.
-            depth: The current depth of recursion for indentation purposes.
-
-        Returns:
-            A string representation of the Union type.
-        """
-        args = get_args(field_type)
-        if type(None) in args:
-            # It's an Optional type
-            non_none_args = [arg for arg in args if arg is not type(None)]
-            if len(non_none_args) == 1:
-                inner_type = self._get_field_type_for_annotation(
-                    non_none_args[0], depth
-                )
-                return f"Optional[{inner_type}]"
-            # Union with None and multiple other types
-            inner_types = ", ".join(
-                self._get_field_type_for_annotation(arg, depth) for arg in non_none_args
-            )
-            return f"Optional[Union[{inner_types}]]"
-        # General Union type
-        inner_types = ", ".join(
-            self._get_field_type_for_annotation(arg, depth) for arg in args
-        )
-        return f"Union[{inner_types}]"
-
-    def _get_field_type_for_annotation(self, annotation: Any, depth: int) -> str:
-        """Recursively get the string representation of a field's type annotation.
-
-        Args:
-            annotation: The type annotation to process.
-            depth: The current depth of recursion for indentation purposes.
-
-        Returns:
-            A string representation of the type annotation.
-        """
-        origin: Any = get_origin(annotation)
-        if origin is list:
-            list_item_type = get_args(annotation)[0]
-            return self._format_list_type(list_item_type, depth)
-        if origin is dict:
-            key_type, value_type = get_args(annotation)
-            return f"Dict[{key_type.__name__}, {value_type.__name__}]"
-        if origin is Union:
-            return self._format_union_type(annotation, depth)
-        if isinstance(annotation, type) and issubclass(annotation, BaseModel):
-            nested_schema = self._get_model_schema(annotation, depth)
-            nested_indent = " " * 4 * depth
-            return f"{annotation.__name__}\n{nested_indent}{{\n{nested_schema}\n{nested_indent}}}"
-        return annotation.__name__

lib/crewai/src/crewai/utilities/pydantic_schema_utils.py

@@ -0,0 +1,245 @@
+"""Utilities for generating JSON schemas from Pydantic models.
+
+This module provides functions for converting Pydantic models to JSON schemas
+suitable for use with LLMs and tool definitions.
+"""
+
+from collections.abc import Callable
+from copy import deepcopy
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def resolve_refs(schema: dict[str, Any]) -> dict[str, Any]:
+    """Recursively resolve all local $refs in the given JSON Schema using $defs as the source.
+
+    This is needed because Pydantic generates $ref-based schemas that
+    some consumers (e.g. LLMs, tool frameworks) don't handle well.
+
+    Args:
+        schema: JSON Schema dict that may contain "$refs" and "$defs".
+
+    Returns:
+        A new schema dictionary with all local $refs replaced by their definitions.
+    """
+    defs = schema.get("$defs", {})
+    schema_copy = deepcopy(schema)
+
+    def _resolve(node: Any) -> Any:
+        if isinstance(node, dict):
+            ref = node.get("$ref")
+            if isinstance(ref, str) and ref.startswith("#/$defs/"):
+                def_name = ref.replace("#/$defs/", "")
+                if def_name in defs:
+                    return _resolve(deepcopy(defs[def_name]))
+                raise KeyError(f"Definition '{def_name}' not found in $defs.")
+            return {k: _resolve(v) for k, v in node.items()}
+
+        if isinstance(node, list):
+            return [_resolve(i) for i in node]
+
+        return node
+
+    return _resolve(schema_copy)  # type: ignore[no-any-return]
+
+
+def add_key_in_dict_recursively(
+    d: dict[str, Any], key: str, value: Any, criteria: Callable[[dict[str, Any]], bool]
+) -> dict[str, Any]:
+    """Recursively adds a key/value pair to all nested dicts matching `criteria`.
+
+    Args:
+        d: The dictionary to modify.
+        key: The key to add.
+        value: The value to add.
+        criteria: A function that returns True for dicts that should receive the key.
+
+    Returns:
+        The modified dictionary.
+    """
+    if isinstance(d, dict):
+        if criteria(d) and key not in d:
+            d[key] = value
+        for v in d.values():
+            add_key_in_dict_recursively(v, key, value, criteria)
+    elif isinstance(d, list):
+        for i in d:
+            add_key_in_dict_recursively(i, key, value, criteria)
+    return d
+
+
+def fix_discriminator_mappings(schema: dict[str, Any]) -> dict[str, Any]:
+    """Replace '#/$defs/...' references in discriminator.mapping with just the model name.
+
+    Args:
+        schema: JSON schema dictionary.
+
+    Returns:
+        Modified schema with fixed discriminator mappings.
+    """
+    output = schema.get("properties", {}).get("output")
+    if not output:
+        return schema
+
+    disc = output.get("discriminator")
+    if not disc or "mapping" not in disc:
+        return schema
+
+    disc["mapping"] = {k: v.split("/")[-1] for k, v in disc["mapping"].items()}
+    return schema
+
+
+def add_const_to_oneof_variants(schema: dict[str, Any]) -> dict[str, Any]:
+    """Add const fields to oneOf variants for discriminated unions.
+
+    The json_schema_to_pydantic library requires each oneOf variant to have
+    a const field for the discriminator property. This function adds those
+    const fields based on the discriminator mapping.
+
+    Args:
+        schema: JSON Schema dict that may contain discriminated unions
+
+    Returns:
+        Modified schema with const fields added to oneOf variants
+    """
+
+    def _process_oneof(node: dict[str, Any]) -> dict[str, Any]:
+        """Process a single node that might contain a oneOf with discriminator."""
+        if not isinstance(node, dict):
+            return node
+
+        if "oneOf" in node and "discriminator" in node:
+            discriminator = node["discriminator"]
+            property_name = discriminator.get("propertyName")
+            mapping = discriminator.get("mapping", {})
+
+            if property_name and mapping:
+                one_of_variants = node.get("oneOf", [])
+
+                for variant in one_of_variants:
+                    if isinstance(variant, dict) and "properties" in variant:
+                        variant_title = variant.get("title", "")
+
+                        matched_disc_value = None
+                        for disc_value, schema_name in mapping.items():
+                            if variant_title == schema_name or variant_title.endswith(
+                                schema_name
+                            ):
+                                matched_disc_value = disc_value
+                                break
+
+                        if matched_disc_value is not None:
+                            props = variant["properties"]
+                            if property_name in props:
+                                props[property_name]["const"] = matched_disc_value
+
+        for key, value in node.items():
+            if isinstance(value, dict):
+                node[key] = _process_oneof(value)
+            elif isinstance(value, list):
+                node[key] = [
+                    _process_oneof(item) if isinstance(item, dict) else item
+                    for item in value
+                ]
+
+        return node
+
+    return _process_oneof(deepcopy(schema))
+
+
+def convert_oneof_to_anyof(schema: dict[str, Any]) -> dict[str, Any]:
+    """Convert oneOf to anyOf for OpenAI compatibility.
+
+    OpenAI's Structured Outputs support anyOf better than oneOf.
+    This recursively converts all oneOf occurrences to anyOf.
+
+    Args:
+        schema: JSON schema dictionary.
+
+    Returns:
+        Modified schema with anyOf instead of oneOf.
+    """
+    if isinstance(schema, dict):
+        if "oneOf" in schema:
+            schema["anyOf"] = schema.pop("oneOf")
+
+        for value in schema.values():
+            if isinstance(value, dict):
+                convert_oneof_to_anyof(value)
+            elif isinstance(value, list):
+                for item in value:
+                    if isinstance(item, dict):
+                        convert_oneof_to_anyof(item)
+
+    return schema
+
+
+def ensure_all_properties_required(schema: dict[str, Any]) -> dict[str, Any]:
+    """Ensure all properties are in the required array for OpenAI strict mode.
+
+    OpenAI's strict structured outputs require all properties to be listed
+    in the required array. This recursively updates all objects to include
+    all their properties in required.
+
+    Args:
+        schema: JSON schema dictionary.
+
+    Returns:
+        Modified schema with all properties marked as required.
+    """
+    if isinstance(schema, dict):
+        if schema.get("type") == "object" and "properties" in schema:
+            properties = schema["properties"]
+            if properties:
+                schema["required"] = list(properties.keys())
+
+        for value in schema.values():
+            if isinstance(value, dict):
+                ensure_all_properties_required(value)
+            elif isinstance(value, list):
+                for item in value:
+                    if isinstance(item, dict):
+                        ensure_all_properties_required(item)
+
+    return schema
+
+
+def generate_model_description(model: type[BaseModel]) -> dict[str, Any]:
+    """Generate JSON schema description of a Pydantic model.
+
+    This function takes a Pydantic model class and returns its JSON schema,
+    which includes full type information, discriminators, and all metadata.
+    The schema is dereferenced to inline all $ref references for better LLM understanding.
+
+    Args:
+        model: A Pydantic model class.
+
+    Returns:
+        A JSON schema dictionary representation of the model.
+    """
+    json_schema = model.model_json_schema(ref_template="#/$defs/{model}")
+
+    json_schema = add_key_in_dict_recursively(
+        json_schema,
+        key="additionalProperties",
+        value=False,
+        criteria=lambda d: d.get("type") == "object"
+        and "additionalProperties" not in d,
+    )
+
+    json_schema = resolve_refs(json_schema)
+
+    json_schema.pop("$defs", None)
+    json_schema = fix_discriminator_mappings(json_schema)
+    json_schema = convert_oneof_to_anyof(json_schema)
+    json_schema = ensure_all_properties_required(json_schema)
+
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": model.__name__,
+            "strict": True,
+            "schema": json_schema,
+        },
+    }

lib/crewai/tests/cli/test_plus_api.py

@@ -1,7 +1,7 @@
+import os
 import unittest
 from unittest.mock import ANY, MagicMock, patch
 
-from crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
 from crewai.cli.plus_api import PlusAPI
 
 
@@ -35,7 +35,7 @@ class TestPlusAPI(unittest.TestCase):
     ):
         mock_make_request.assert_called_once_with(
             method,
-            f"{DEFAULT_CREWAI_ENTERPRISE_URL}{endpoint}",
+            f"{os.getenv('CREWAI_PLUS_URL')}{endpoint}",
             headers={
                 "Authorization": ANY,
                 "Content-Type": ANY,
@@ -53,7 +53,7 @@ class TestPlusAPI(unittest.TestCase):
     ):
         mock_settings = MagicMock()
         mock_settings.org_uuid = self.org_uuid
-        mock_settings.enterprise_base_url = DEFAULT_CREWAI_ENTERPRISE_URL
+        mock_settings.enterprise_base_url = os.getenv('CREWAI_PLUS_URL')
         mock_settings_class.return_value = mock_settings
         # re-initialize Client
         self.api = PlusAPI(self.api_key)
@@ -84,7 +84,7 @@ class TestPlusAPI(unittest.TestCase):
     def test_get_agent_with_org_uuid(self, mock_make_request, mock_settings_class):
         mock_settings = MagicMock()
         mock_settings.org_uuid = self.org_uuid
-        mock_settings.enterprise_base_url = DEFAULT_CREWAI_ENTERPRISE_URL
+        mock_settings.enterprise_base_url = os.getenv('CREWAI_PLUS_URL')
         mock_settings_class.return_value = mock_settings
         # re-initialize Client
         self.api = PlusAPI(self.api_key)
@@ -115,7 +115,7 @@ class TestPlusAPI(unittest.TestCase):
     def test_get_tool_with_org_uuid(self, mock_make_request, mock_settings_class):
         mock_settings = MagicMock()
         mock_settings.org_uuid = self.org_uuid
-        mock_settings.enterprise_base_url = DEFAULT_CREWAI_ENTERPRISE_URL
+        mock_settings.enterprise_base_url = os.getenv('CREWAI_PLUS_URL')
         mock_settings_class.return_value = mock_settings
         # re-initialize Client
         self.api = PlusAPI(self.api_key)
@@ -163,7 +163,7 @@ class TestPlusAPI(unittest.TestCase):
     def test_publish_tool_with_org_uuid(self, mock_make_request, mock_settings_class):
         mock_settings = MagicMock()
         mock_settings.org_uuid = self.org_uuid
-        mock_settings.enterprise_base_url = DEFAULT_CREWAI_ENTERPRISE_URL
+        mock_settings.enterprise_base_url = os.getenv('CREWAI_PLUS_URL')
         mock_settings_class.return_value = mock_settings
         # re-initialize Client
         self.api = PlusAPI(self.api_key)
@@ -320,6 +320,7 @@ class TestPlusAPI(unittest.TestCase):
         )
 
     @patch("crewai.cli.plus_api.Settings")
+    @patch.dict(os.environ, {"CREWAI_PLUS_URL": ""})
     def test_custom_base_url(self, mock_settings_class):
         mock_settings = MagicMock()
         mock_settings.enterprise_base_url = "https://custom-url.com/api"
@@ -329,3 +330,11 @@ class TestPlusAPI(unittest.TestCase):
             custom_api.base_url,
             "https://custom-url.com/api",
         )
+
+    @patch.dict(os.environ, {"CREWAI_PLUS_URL": "https://custom-url-from-env.com"})
+    def test_custom_base_url_from_env(self):
+        custom_api = PlusAPI("test_key")
+        self.assertEqual(
+            custom_api.base_url,
+            "https://custom-url-from-env.com",
+        )

lib/crewai/tests/test_human_feedback_decorator.py

@@ -0,0 +1,401 @@
+"""Unit tests for the @human_feedback decorator.
+
+This module tests the @human_feedback decorator's validation logic,
+async support, and attribute preservation functionality.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from crewai.flow import Flow, human_feedback, listen, start
+from crewai.flow.human_feedback import (
+    HumanFeedbackConfig,
+    HumanFeedbackResult,
+)
+
+
+class TestHumanFeedbackValidation:
+    """Tests for decorator parameter validation."""
+
+    def test_emit_requires_llm(self):
+        """Test that specifying emit without llm raises ValueError."""
+        with pytest.raises(ValueError) as exc_info:
+
+            @human_feedback(
+                message="Review this:",
+                emit=["approve", "reject"],
+                # llm not provided
+            )
+            def test_method(self):
+                return "output"
+
+        assert "llm is required" in str(exc_info.value)
+
+    def test_default_outcome_requires_emit(self):
+        """Test that specifying default_outcome without emit raises ValueError."""
+        with pytest.raises(ValueError) as exc_info:
+
+            @human_feedback(
+                message="Review this:",
+                default_outcome="approve",
+                # emit not provided
+            )
+            def test_method(self):
+                return "output"
+
+        assert "requires emit" in str(exc_info.value)
+
+    def test_default_outcome_must_be_in_emit(self):
+        """Test that default_outcome must be one of the emit values."""
+        with pytest.raises(ValueError) as exc_info:
+
+            @human_feedback(
+                message="Review this:",
+                emit=["approve", "reject"],
+                llm="gpt-4o-mini",
+                default_outcome="invalid_outcome",
+            )
+            def test_method(self):
+                return "output"
+
+        assert "must be one of" in str(exc_info.value)
+
+    def test_valid_configuration_with_routing(self):
+        """Test that valid configuration with routing doesn't raise."""
+
+        @human_feedback(
+            message="Review this:",
+            emit=["approve", "reject"],
+            llm="gpt-4o-mini",
+            default_outcome="reject",
+        )
+        def test_method(self):
+            return "output"
+
+        # Should not raise
+        assert hasattr(test_method, "__human_feedback_config__")
+        assert test_method.__is_router__ is True
+        assert test_method.__router_paths__ == ["approve", "reject"]
+
+    def test_valid_configuration_without_routing(self):
+        """Test that valid configuration without routing doesn't raise."""
+
+        @human_feedback(message="Review this:")
+        def test_method(self):
+            return "output"
+
+        # Should not raise
+        assert hasattr(test_method, "__human_feedback_config__")
+        assert not hasattr(test_method, "__is_router__") or not test_method.__is_router__
+
+
+class TestHumanFeedbackConfig:
+    """Tests for HumanFeedbackConfig dataclass."""
+
+    def test_config_creation(self):
+        """Test HumanFeedbackConfig can be created with all parameters."""
+        config = HumanFeedbackConfig(
+            message="Test message",
+            emit=["a", "b"],
+            llm="gpt-4",
+            default_outcome="a",
+            metadata={"key": "value"},
+        )
+
+        assert config.message == "Test message"
+        assert config.emit == ["a", "b"]
+        assert config.llm == "gpt-4"
+        assert config.default_outcome == "a"
+        assert config.metadata == {"key": "value"}
+
+
+class TestHumanFeedbackResult:
+    """Tests for HumanFeedbackResult dataclass."""
+
+    def test_result_creation(self):
+        """Test HumanFeedbackResult can be created with all fields."""
+        result = HumanFeedbackResult(
+            output={"title": "Test"},
+            feedback="Looks good",
+            outcome="approved",
+            method_name="test_method",
+        )
+
+        assert result.output == {"title": "Test"}
+        assert result.feedback == "Looks good"
+        assert result.outcome == "approved"
+        assert result.method_name == "test_method"
+        assert isinstance(result.timestamp, datetime)
+        assert result.metadata == {}
+
+    def test_result_with_metadata(self):
+        """Test HumanFeedbackResult with custom metadata."""
+        result = HumanFeedbackResult(
+            output="test",
+            feedback="feedback",
+            metadata={"channel": "slack", "user": "test_user"},
+        )
+
+        assert result.metadata == {"channel": "slack", "user": "test_user"}
+
+
+class TestDecoratorAttributePreservation:
+    """Tests for preserving Flow decorator attributes."""
+
+    def test_preserves_start_method_attributes(self):
+        """Test that @human_feedback preserves @start decorator attributes."""
+
+        class TestFlow(Flow):
+            @start()
+            @human_feedback(message="Review:")
+            def my_start_method(self):
+                return "output"
+
+        # Check that start method attributes are preserved
+        flow = TestFlow()
+        method = flow._methods.get("my_start_method")
+        assert method is not None
+        assert hasattr(method, "__is_start_method__") or "my_start_method" in flow._start_methods
+
+    def test_preserves_listen_method_attributes(self):
+        """Test that @human_feedback preserves @listen decorator attributes."""
+
+        class TestFlow(Flow):
+            @start()
+            def begin(self):
+                return "start"
+
+            @listen("begin")
+            @human_feedback(message="Review:")
+            def review(self):
+                return "review output"
+
+        flow = TestFlow()
+        # The method should be registered as a listener
+        assert "review" in flow._listeners or any(
+            "review" in str(v) for v in flow._listeners.values()
+        )
+
+    def test_sets_router_attributes_when_emit_specified(self):
+        """Test that router attributes are set when emit is specified."""
+
+        # Test the decorator directly without @start wrapping
+        @human_feedback(
+            message="Review:",
+            emit=["approved", "rejected"],
+            llm="gpt-4o-mini",
+        )
+        def review_method(self):
+            return "output"
+
+        assert review_method.__is_router__ is True
+        assert review_method.__router_paths__ == ["approved", "rejected"]
+
+
+class TestAsyncSupport:
+    """Tests for async method support."""
+
+    def test_async_method_detection(self):
+        """Test that async methods are properly detected and wrapped."""
+
+        @human_feedback(message="Review:")
+        async def async_method(self):
+            return "async output"
+
+        assert asyncio.iscoroutinefunction(async_method)
+
+    def test_sync_method_remains_sync(self):
+        """Test that sync methods remain synchronous."""
+
+        @human_feedback(message="Review:")
+        def sync_method(self):
+            return "sync output"
+
+        assert not asyncio.iscoroutinefunction(sync_method)
+
+
+class TestHumanFeedbackExecution:
+    """Tests for actual human feedback execution."""
+
+    @patch("builtins.input", return_value="This looks great!")
+    @patch("builtins.print")
+    def test_basic_feedback_collection(self, mock_print, mock_input):
+        """Test basic feedback collection without routing."""
+
+        class TestFlow(Flow):
+            @start()
+            @human_feedback(message="Please review:")
+            def generate(self):
+                return "Generated content"
+
+        flow = TestFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="Great job!"):
+            result = flow.kickoff()
+
+        assert flow.last_human_feedback is not None
+        assert flow.last_human_feedback.output == "Generated content"
+        assert flow.last_human_feedback.feedback == "Great job!"
+
+    @patch("builtins.input", return_value="")
+    @patch("builtins.print")
+    def test_empty_feedback_with_default_outcome(self, mock_print, mock_input):
+        """Test empty feedback uses default_outcome."""
+
+        class TestFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "needs_work"],
+                llm="gpt-4o-mini",
+                default_outcome="needs_work",
+            )
+            def review(self):
+                return "Content"
+
+        flow = TestFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value=""):
+            result = flow.kickoff()
+
+        assert result == "needs_work"
+        assert flow.last_human_feedback is not None
+        assert flow.last_human_feedback.outcome == "needs_work"
+
+    @patch("builtins.input", return_value="Approved!")
+    @patch("builtins.print")
+    def test_feedback_collapsing(self, mock_print, mock_input):
+        """Test that feedback is collapsed to an outcome."""
+
+        class TestFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def review(self):
+                return "Content"
+
+        flow = TestFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="Looks great, approved!"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        assert result == "approved"
+        assert flow.last_human_feedback is not None
+        assert flow.last_human_feedback.outcome == "approved"
+
+
+class TestHumanFeedbackHistory:
+    """Tests for human feedback history tracking."""
+
+    @patch("builtins.input", return_value="feedback")
+    @patch("builtins.print")
+    def test_history_accumulates(self, mock_print, mock_input):
+        """Test that multiple feedbacks are stored in history."""
+
+        class TestFlow(Flow):
+            @start()
+            @human_feedback(message="Review step 1:")
+            def step1(self):
+                return "Step 1 output"
+
+            @listen(step1)
+            @human_feedback(message="Review step 2:")
+            def step2(self, prev):
+                return "Step 2 output"
+
+        flow = TestFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="feedback"):
+            flow.kickoff()
+
+        # Both feedbacks should be in history
+        assert len(flow.human_feedback_history) == 2
+        assert flow.human_feedback_history[0].method_name == "step1"
+        assert flow.human_feedback_history[1].method_name == "step2"
+
+    @patch("builtins.input", return_value="")
+    @patch("builtins.print")
+    def test_human_feedback_property_returns_last(self, mock_print, mock_input):
+        """Test that human_feedback property returns the last result."""
+
+        class TestFlow(Flow):
+            @start()
+            @human_feedback(message="Review:")
+            def generate(self):
+                return "output"
+
+        flow = TestFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="last feedback"):
+            flow.kickoff()
+
+        assert flow.last_human_feedback is not None
+        assert flow.last_human_feedback.feedback == "last feedback"
+        assert flow.last_human_feedback is flow.last_human_feedback
+
+
+class TestCollapseToOutcome:
+    """Tests for the _collapse_to_outcome method."""
+
+    def test_exact_match(self):
+        """Test exact match returns the correct outcome."""
+        flow = Flow()
+
+        with patch("crewai.llm.LLM") as MockLLM:
+            mock_llm = MagicMock()
+            mock_llm.call.return_value = "approved"
+            MockLLM.return_value = mock_llm
+
+            result = flow._collapse_to_outcome(
+                feedback="I approve this",
+                outcomes=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+
+        assert result == "approved"
+
+    def test_partial_match(self):
+        """Test partial match finds the outcome in the response."""
+        flow = Flow()
+
+        with patch("crewai.llm.LLM") as MockLLM:
+            mock_llm = MagicMock()
+            mock_llm.call.return_value = "The outcome is approved based on the feedback"
+            MockLLM.return_value = mock_llm
+
+            result = flow._collapse_to_outcome(
+                feedback="Looks good",
+                outcomes=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+
+        assert result == "approved"
+
+    def test_fallback_to_first(self):
+        """Test that unmatched response falls back to first outcome."""
+        flow = Flow()
+
+        with patch("crewai.llm.LLM") as MockLLM:
+            mock_llm = MagicMock()
+            mock_llm.call.return_value = "something completely different"
+            MockLLM.return_value = mock_llm
+
+            result = flow._collapse_to_outcome(
+                feedback="Unclear feedback",
+                outcomes=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+
+        assert result == "approved"  # First in list

lib/crewai/tests/test_human_feedback_integration.py

@@ -0,0 +1,428 @@
+"""Integration tests for the @human_feedback decorator with Flow.
+
+This module tests the integration of @human_feedback with @listen,
+routing behavior, multi-step flows, and state management.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+from pydantic import BaseModel
+
+from crewai.flow import Flow, HumanFeedbackResult, human_feedback, listen, start
+from crewai.flow.flow import FlowState
+
+
+class TestRoutingIntegration:
+    """Tests for routing integration with @listen decorators."""
+
+    @patch("builtins.input", return_value="I approve")
+    @patch("builtins.print")
+    def test_routes_to_matching_listener(self, mock_print, mock_input):
+        """Test that collapsed outcome routes to the matching @listen method."""
+        execution_order = []
+
+        class ReviewFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def generate(self):
+                execution_order.append("generate")
+                return "content"
+
+            @listen("approved")
+            def on_approved(self):
+                execution_order.append("on_approved")
+                return "published"
+
+            @listen("rejected")
+            def on_rejected(self):
+                execution_order.append("on_rejected")
+                return "discarded"
+
+        flow = ReviewFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="Approved!"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        assert "generate" in execution_order
+        assert "on_approved" in execution_order
+        assert "on_rejected" not in execution_order
+
+    @patch("builtins.input", return_value="")
+    @patch("builtins.print")
+    def test_default_outcome_routes_correctly(self, mock_print, mock_input):
+        """Test that default_outcome routes when no feedback provided."""
+        executed_listener = []
+
+        class ReviewFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "needs_work"],
+                llm="gpt-4o-mini",
+                default_outcome="needs_work",
+            )
+            def generate(self):
+                return "content"
+
+            @listen("approved")
+            def on_approved(self):
+                executed_listener.append("approved")
+
+            @listen("needs_work")
+            def on_needs_work(self):
+                executed_listener.append("needs_work")
+
+        flow = ReviewFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value=""):
+            flow.kickoff()
+
+        assert "needs_work" in executed_listener
+        assert "approved" not in executed_listener
+
+
+class TestMultiStepFlows:
+    """Tests for multi-step flows with multiple @human_feedback decorators."""
+
+    @patch("builtins.input", side_effect=["Good draft", "Final approved"])
+    @patch("builtins.print")
+    def test_multiple_feedback_steps(self, mock_print, mock_input):
+        """Test a flow with multiple human feedback steps."""
+
+        class MultiStepFlow(Flow):
+            @start()
+            @human_feedback(message="Review draft:")
+            def draft(self):
+                return "Draft content"
+
+            @listen(draft)
+            @human_feedback(message="Final review:")
+            def final_review(self, prev_result: HumanFeedbackResult):
+                return f"Final content based on: {prev_result.feedback}"
+
+        flow = MultiStepFlow()
+
+        with patch.object(
+            flow, "_request_human_feedback", side_effect=["Good draft", "Approved"]
+        ):
+            flow.kickoff()
+
+        # Both feedbacks should be recorded
+        assert len(flow.human_feedback_history) == 2
+        assert flow.human_feedback_history[0].method_name == "draft"
+        assert flow.human_feedback_history[0].feedback == "Good draft"
+        assert flow.human_feedback_history[1].method_name == "final_review"
+        assert flow.human_feedback_history[1].feedback == "Approved"
+
+    @patch("builtins.input", return_value="feedback")
+    @patch("builtins.print")
+    def test_mixed_feedback_and_regular_methods(self, mock_print, mock_input):
+        """Test flow with both @human_feedback and regular methods."""
+        execution_order = []
+
+        class MixedFlow(Flow):
+            @start()
+            def generate(self):
+                execution_order.append("generate")
+                return "generated"
+
+            @listen(generate)
+            @human_feedback(message="Review:")
+            def review(self):
+                execution_order.append("review")
+                return "reviewed"
+
+            @listen(review)
+            def finalize(self, result):
+                execution_order.append("finalize")
+                return "finalized"
+
+        flow = MixedFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="feedback"):
+            flow.kickoff()
+
+        assert execution_order == ["generate", "review", "finalize"]
+
+
+class TestStateManagement:
+    """Tests for state management with human feedback."""
+
+    @patch("builtins.input", return_value="approved")
+    @patch("builtins.print")
+    def test_feedback_available_in_listener(self, mock_print, mock_input):
+        """Test that feedback is accessible in downstream listeners."""
+        captured_feedback = []
+
+        class StateFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def review(self):
+                return "Content to review"
+
+            @listen("approved")
+            def on_approved(self):
+                # Access the feedback via property
+                captured_feedback.append(self.last_human_feedback)
+                return "done"
+
+        flow = StateFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="Great content!"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            flow.kickoff()
+
+        assert len(captured_feedback) == 1
+        result = captured_feedback[0]
+        assert isinstance(result, HumanFeedbackResult)
+        assert result.output == "Content to review"
+        assert result.feedback == "Great content!"
+        assert result.outcome == "approved"
+
+    @patch("builtins.input", return_value="")
+    @patch("builtins.print")
+    def test_history_preserved_across_steps(self, mock_print, mock_input):
+        """Test that feedback history is preserved across flow execution."""
+
+        class HistoryFlow(Flow):
+            @start()
+            @human_feedback(message="Step 1:")
+            def step1(self):
+                return "Step 1"
+
+            @listen(step1)
+            @human_feedback(message="Step 2:")
+            def step2(self, result):
+                return "Step 2"
+
+            @listen(step2)
+            def final(self, result):
+                # Access history
+                return len(self.human_feedback_history)
+
+        flow = HistoryFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="feedback"):
+            result = flow.kickoff()
+
+        # Final method should see 2 feedback entries
+        assert result == 2
+
+
+class TestAsyncFlowIntegration:
+    """Tests for async flow integration."""
+
+    @pytest.mark.asyncio
+    async def test_async_flow_with_human_feedback(self):
+        """Test that @human_feedback works with async flows."""
+        executed = []
+
+        class AsyncFlow(Flow):
+            @start()
+            @human_feedback(message="Review:")
+            async def async_review(self):
+                executed.append("async_review")
+                await asyncio.sleep(0.01)  # Simulate async work
+                return "async content"
+
+        flow = AsyncFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="feedback"):
+            await flow.kickoff_async()
+
+        assert "async_review" in executed
+        assert flow.last_human_feedback is not None
+        assert flow.last_human_feedback.output == "async content"
+
+
+class TestWithStructuredState:
+    """Tests for flows with structured (Pydantic) state."""
+
+    @patch("builtins.input", return_value="approved")
+    @patch("builtins.print")
+    def test_with_pydantic_state(self, mock_print, mock_input):
+        """Test human feedback with structured Pydantic state."""
+
+        class ReviewState(FlowState):
+            content: str = ""
+            review_count: int = 0
+
+        class StructuredFlow(Flow[ReviewState]):
+            initial_state = ReviewState
+
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def review(self):
+                self.state.content = "Generated content"
+                self.state.review_count += 1
+                return self.state.content
+
+            @listen("approved")
+            def on_approved(self):
+                return f"Approved: {self.state.content}"
+
+        flow = StructuredFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="LGTM"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        assert flow.state.review_count == 1
+        assert flow.last_human_feedback is not None
+        assert flow.last_human_feedback.feedback == "LGTM"
+
+
+class TestMetadataPassthrough:
+    """Tests for metadata passthrough functionality."""
+
+    @patch("builtins.input", return_value="")
+    @patch("builtins.print")
+    def test_metadata_included_in_result(self, mock_print, mock_input):
+        """Test that metadata is passed through to HumanFeedbackResult."""
+
+        class MetadataFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                metadata={"channel": "slack", "priority": "high"},
+            )
+            def review(self):
+                return "content"
+
+        flow = MetadataFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="feedback"):
+            flow.kickoff()
+
+        result = flow.last_human_feedback
+        assert result is not None
+        assert result.metadata == {"channel": "slack", "priority": "high"}
+
+
+class TestEventEmission:
+    """Tests for event emission during human feedback."""
+
+    @patch("builtins.input", return_value="test feedback")
+    @patch("builtins.print")
+    def test_events_emitted_on_feedback_request(self, mock_print, mock_input):
+        """Test that events are emitted when feedback is requested."""
+        from crewai.events.event_listener import event_listener
+
+        class EventFlow(Flow):
+            @start()
+            @human_feedback(message="Review:")
+            def review(self):
+                return "content"
+
+        flow = EventFlow()
+
+        # We can't easily capture events in tests, but we can verify
+        # the flow executes without errors
+        with (
+            patch.object(
+                event_listener.formatter, "pause_live_updates", return_value=None
+            ),
+            patch.object(
+                event_listener.formatter, "resume_live_updates", return_value=None
+            ),
+        ):
+            flow.kickoff()
+
+        assert flow.last_human_feedback is not None
+
+
+class TestEdgeCases:
+    """Tests for edge cases and error handling."""
+
+    @patch("builtins.input", return_value="")
+    @patch("builtins.print")
+    def test_empty_feedback_first_outcome_fallback(self, mock_print, mock_input):
+        """Test that empty feedback without default uses first outcome."""
+
+        class FallbackFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["first", "second", "third"],
+                llm="gpt-4o-mini",
+                # No default_outcome specified
+            )
+            def review(self):
+                return "content"
+
+        flow = FallbackFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value=""):
+            result = flow.kickoff()
+
+        assert result == "first"  # Falls back to first outcome
+
+    @patch("builtins.input", return_value="whitespace only   ")
+    @patch("builtins.print")
+    def test_whitespace_only_feedback_treated_as_empty(self, mock_print, mock_input):
+        """Test that whitespace-only feedback is treated as empty."""
+
+        class WhitespaceFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approve", "reject"],
+                llm="gpt-4o-mini",
+                default_outcome="reject",
+            )
+            def review(self):
+                return "content"
+
+        flow = WhitespaceFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="   "):
+            result = flow.kickoff()
+
+        assert result == "reject"  # Uses default because feedback is empty after strip
+
+    @patch("builtins.input", return_value="feedback")
+    @patch("builtins.print")
+    def test_feedback_result_without_routing(self, mock_print, mock_input):
+        """Test that HumanFeedbackResult is returned when not routing."""
+
+        class NoRoutingFlow(Flow):
+            @start()
+            @human_feedback(message="Review:")
+            def review(self):
+                return "content"
+
+        flow = NoRoutingFlow()
+
+        with patch.object(flow, "_request_human_feedback", return_value="feedback"):
+            result = flow.kickoff()
+
+        # Result should be HumanFeedbackResult when not routing
+        assert isinstance(result, HumanFeedbackResult)
+        assert result.output == "content"
+        assert result.feedback == "feedback"
+        assert result.outcome is None  # No routing, no outcome

lib/crewai/tests/test_task.py

@@ -1727,3 +1727,24 @@ def test_task_output_includes_messages():
     assert hasattr(task2_output, "messages")
     assert isinstance(task2_output.messages, list)
     assert len(task2_output.messages) > 0
+
+
+def test_async_execution_fails():
+    researcher = Agent(
+      role="Researcher",
+      goal="Make the best research and analysis on content about AI and AI agents",
+      backstory="You're an expert researcher, specialized in technology, software engineering, AI and startups. You work as a freelancer and is now working on doing research and analysis for a new customer.",
+      allow_delegation=False,
+    )
+
+    task = Task(
+      description="Give me a list of 5 interesting ideas to explore for na article, what makes them unique and interesting.",
+      expected_output="Bullet point list of 5 interesting ideas.",
+      async_execution=True,
+      agent=researcher,
+    )
+
+    with patch.object(Task, "_execute_core", side_effect=RuntimeError("boom!")):
+      with pytest.raises(RuntimeError, match="boom!"):
+        execution = task.execute_async(agent=researcher)
+        execution.result()

lib/crewai/tests/tools/test_base_tool.py

@@ -17,10 +17,11 @@ def test_creating_a_tool_using_annotation():
 
     # Assert all the right attributes were defined
     assert my_tool.name == "Name of my tool"
-    assert (
-        my_tool.description
-        == "Tool Name: Name of my tool\nTool Arguments: {'question': {'description': None, 'type': 'str'}}\nTool Description: Clear description for what this tool is useful for, your agent will need this information to use it."
-    )
+    assert "Tool Name: Name of my tool" in my_tool.description
+    assert "Tool Arguments:" in my_tool.description
+    assert '"question"' in my_tool.description
+    assert '"type": "string"' in my_tool.description
+    assert "Tool Description: Clear description for what this tool is useful for" in my_tool.description
     assert my_tool.args_schema.model_json_schema()["properties"] == {
         "question": {"title": "Question", "type": "string"}
     }
@@ -31,10 +32,9 @@ def test_creating_a_tool_using_annotation():
     converted_tool = my_tool.to_structured_tool()
     assert converted_tool.name == "Name of my tool"
 
-    assert (
-        converted_tool.description
-        == "Tool Name: Name of my tool\nTool Arguments: {'question': {'description': None, 'type': 'str'}}\nTool Description: Clear description for what this tool is useful for, your agent will need this information to use it."
-    )
+    assert "Tool Name: Name of my tool" in converted_tool.description
+    assert "Tool Arguments:" in converted_tool.description
+    assert '"question"' in converted_tool.description
     assert converted_tool.args_schema.model_json_schema()["properties"] == {
         "question": {"title": "Question", "type": "string"}
     }
@@ -56,10 +56,11 @@ def test_creating_a_tool_using_baseclass():
     # Assert all the right attributes were defined
     assert my_tool.name == "Name of my tool"
 
-    assert (
-        my_tool.description
-        == "Tool Name: Name of my tool\nTool Arguments: {'question': {'description': None, 'type': 'str'}}\nTool Description: Clear description for what this tool is useful for, your agent will need this information to use it."
-    )
+    assert "Tool Name: Name of my tool" in my_tool.description
+    assert "Tool Arguments:" in my_tool.description
+    assert '"question"' in my_tool.description
+    assert '"type": "string"' in my_tool.description
+    assert "Tool Description: Clear description for what this tool is useful for" in my_tool.description
     assert my_tool.args_schema.model_json_schema()["properties"] == {
         "question": {"title": "Question", "type": "string"}
     }
@@ -68,10 +69,9 @@ def test_creating_a_tool_using_baseclass():
     converted_tool = my_tool.to_structured_tool()
     assert converted_tool.name == "Name of my tool"
 
-    assert (
-        converted_tool.description
-        == "Tool Name: Name of my tool\nTool Arguments: {'question': {'description': None, 'type': 'str'}}\nTool Description: Clear description for what this tool is useful for, your agent will need this information to use it."
-    )
+    assert "Tool Name: Name of my tool" in converted_tool.description
+    assert "Tool Arguments:" in converted_tool.description
+    assert '"question"' in converted_tool.description
     assert converted_tool.args_schema.model_json_schema()["properties"] == {
         "question": {"title": "Question", "type": "string"}
     }

lib/crewai/tests/tools/test_tool_usage.py

@@ -107,25 +107,20 @@ def test_tool_usage_render():
 
     rendered = tool_usage._render()
 
-    # Updated checks to match the actual output
+    # Check that the rendered output contains the expected tool information
     assert "Tool Name: Random Number Generator" in rendered
     assert "Tool Arguments:" in rendered
-    assert (
-        "'min_value': {'description': 'The minimum value of the range (inclusive)', 'type': 'int'}"
-        in rendered
-    )
-    assert (
-        "'max_value': {'description': 'The maximum value of the range (inclusive)', 'type': 'int'}"
-        in rendered
-    )
     assert (
         "Tool Description: Generates a random number within a specified range"
         in rendered
     )
-    assert (
-        "Tool Name: Random Number Generator\nTool Arguments: {'min_value': {'description': 'The minimum value of the range (inclusive)', 'type': 'int'}, 'max_value': {'description': 'The maximum value of the range (inclusive)', 'type': 'int'}}\nTool Description: Generates a random number within a specified range"
-        in rendered
-    )
+
+    # Check that the JSON schema format is used (proper JSON schema types)
+    assert '"min_value"' in rendered
+    assert '"max_value"' in rendered
+    assert '"type": "integer"' in rendered
+    assert '"description": "The minimum value of the range (inclusive)"' in rendered
+    assert '"description": "The maximum value of the range (inclusive)"' in rendered
 
 
 def test_validate_tool_input_booleans_and_none():

lib/crewai/tests/utilities/evaluators/test_task_evaluator.py

@@ -1,4 +1,3 @@
-from unittest import mock
 from unittest.mock import MagicMock, patch
 
 from crewai.utilities.converter import ConverterError
@@ -44,26 +43,26 @@ def test_evaluate_training_data(converter_mock):
     )
 
     assert result == function_return_value
-    converter_mock.assert_has_calls(
-        [
-            mock.call(
-                llm=original_agent.llm,
-                text="Assess the quality of the training data based on the llm output, human feedback , and llm "
-                "output improved result.\n\nIteration: data1\nInitial Output:\nInitial output 1\n\nHuman Feedback:\nHuman feedback "
-                "1\n\nImproved Output:\nImproved output 1\n\n------------------------------------------------\n\nIteration: data2\nInitial Output:\nInitial output 2\n\nHuman "
-                "Feedback:\nHuman feedback 2\n\nImproved Output:\nImproved output 2\n\n------------------------------------------------\n\nPlease provide:\n- Provide "
-                "a list of clear, actionable instructions derived from the Human Feedbacks to enhance the Agent's "
-                "performance. Analyze the differences between Initial Outputs and Improved Outputs to generate specific "
-                "action items for future tasks. Ensure all key and specificpoints from the human feedback are "
-                "incorporated into these instructions.\n- A score from 0 to 10 evaluating on completion, quality, and "
-                "overall performance from the improved output to the initial output based on the human feedback\n",
-                model=TrainingTaskEvaluation,
-                instructions="I'm gonna convert this raw text into valid JSON.\n\nThe json should have the "
-                "following structure, with the following keys:\n{\n    suggestions: List[str],\n    quality: float,\n    final_summary: str\n}",
-            ),
-            mock.call().to_pydantic(),
-        ]
-    )
+
+    # Verify the converter was called with correct arguments
+    converter_mock.assert_called_once()
+    call_kwargs = converter_mock.call_args.kwargs
+
+    assert call_kwargs["llm"] == original_agent.llm
+    assert call_kwargs["model"] == TrainingTaskEvaluation
+    assert "Iteration: data1" in call_kwargs["text"]
+    assert "Iteration: data2" in call_kwargs["text"]
+
+    instructions = call_kwargs["instructions"]
+    assert "I'm gonna convert this raw text into valid JSON." in instructions
+    assert "OpenAPI schema" in instructions
+    assert '"type": "json_schema"' in instructions
+    assert '"name": "TrainingTaskEvaluation"' in instructions
+    assert '"suggestions"' in instructions
+    assert '"quality"' in instructions
+    assert '"final_summary"' in instructions
+
+    converter_mock.return_value.to_pydantic.assert_called_once()
 
 
 @patch("crewai.utilities.converter.Converter.to_pydantic")

lib/crewai/tests/utilities/test_converter.py

@@ -16,7 +16,6 @@ from crewai.utilities.converter import (
     handle_partial_json,
     validate_model,
 )
-from crewai.utilities.pydantic_schema_parser import PydanticSchemaParser
 from pydantic import BaseModel
 import pytest
 

lib/crewai/tests/utilities/test_planning_handler.py

@@ -1,7 +1,11 @@
-from unittest.mock import patch
+"""Tests for the planning handler module."""
+
+from unittest.mock import MagicMock, patch
 
 import pytest
+
 from crewai.agent import Agent
+from crewai.crew import Crew
 from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
 from crewai.task import Task
 from crewai.tasks.task_output import TaskOutput
@@ -13,7 +17,7 @@ from crewai.utilities.planning_handler import (
 )
 
 
-class InternalCrewPlanner:
+class TestInternalCrewPlanner:
     @pytest.fixture
     def crew_planner(self):
         tasks = [
@@ -49,9 +53,9 @@ class InternalCrewPlanner:
 
     def test_handle_crew_planning(self, crew_planner):
         list_of_plans_per_task = [
-            PlanPerTask(task="Task1", plan="Plan 1"),
-            PlanPerTask(task="Task2", plan="Plan 2"),
-            PlanPerTask(task="Task3", plan="Plan 3"),
+            PlanPerTask(task_number=1, task="Task1", plan="Plan 1"),
+            PlanPerTask(task_number=2, task="Task2", plan="Plan 2"),
+            PlanPerTask(task_number=3, task="Task3", plan="Plan 3"),
         ]
         with patch.object(Task, "execute_sync") as execute:
             execute.return_value = TaskOutput(
@@ -97,12 +101,12 @@ class InternalCrewPlanner:
         # Knowledge field should not be present when empty
         assert '"agent_knowledge"' not in tasks_summary
 
-    @patch("crewai.knowledge.storage.knowledge_storage.chromadb")
-    def test_create_tasks_summary_with_knowledge_and_tools(self, mock_chroma):
+    @patch("crewai.knowledge.knowledge.Knowledge.add_sources")
+    @patch("crewai.knowledge.storage.knowledge_storage.KnowledgeStorage")
+    def test_create_tasks_summary_with_knowledge_and_tools(
+        self, mock_storage, mock_add_sources
+    ):
         """Test task summary generation with both knowledge and tools present."""
-        # Mock ChromaDB collection
-        mock_collection = mock_chroma.return_value.get_or_create_collection.return_value
-        mock_collection.add.return_value = None
 
         # Create mock tools with proper string descriptions and structured tool support
         class MockTool(BaseTool):
@@ -166,7 +170,9 @@ class InternalCrewPlanner:
                 description="Description",
                 agent="agent",
                 pydantic=PlannerTaskPydanticOutput(
-                    list_of_plans_per_task=[PlanPerTask(task="Task1", plan="Plan 1")]
+                    list_of_plans_per_task=[
+                        PlanPerTask(task_number=1, task="Task1", plan="Plan 1")
+                    ]
                 ),
             )
             result = crew_planner_different_llm._handle_crew_planning()
@@ -177,3 +183,181 @@ class InternalCrewPlanner:
                 crew_planner_different_llm.tasks
             )
             execute.assert_called_once()
+
+    def test_plan_per_task_requires_task_number(self):
+        """Test that PlanPerTask model requires task_number field."""
+        with pytest.raises(ValueError):
+            PlanPerTask(task="Task1", plan="Plan 1")
+
+    def test_plan_per_task_with_task_number(self):
+        """Test PlanPerTask model with task_number field."""
+        plan = PlanPerTask(task_number=5, task="Task5", plan="Plan for task 5")
+        assert plan.task_number == 5
+        assert plan.task == "Task5"
+        assert plan.plan == "Plan for task 5"
+
+
+class TestCrewPlanningIntegration:
+    """Tests for Crew._handle_crew_planning integration with task_number matching."""
+
+    def test_crew_planning_with_out_of_order_plans(self):
+        """Test that plans are correctly matched to tasks even when returned out of order.
+
+        This test verifies the fix for issue #3953 where plans returned by the LLM
+        in a different order than the tasks would be incorrectly assigned.
+        """
+        agent1 = Agent(role="Agent 1", goal="Goal 1", backstory="Backstory 1")
+        agent2 = Agent(role="Agent 2", goal="Goal 2", backstory="Backstory 2")
+        agent3 = Agent(role="Agent 3", goal="Goal 3", backstory="Backstory 3")
+
+        task1 = Task(
+            description="First task description",
+            expected_output="Output 1",
+            agent=agent1,
+        )
+        task2 = Task(
+            description="Second task description",
+            expected_output="Output 2",
+            agent=agent2,
+        )
+        task3 = Task(
+            description="Third task description",
+            expected_output="Output 3",
+            agent=agent3,
+        )
+
+        crew = Crew(
+            agents=[agent1, agent2, agent3],
+            tasks=[task1, task2, task3],
+            planning=True,
+        )
+
+        out_of_order_plans = [
+            PlanPerTask(task_number=3, task="Task 3", plan=" [PLAN FOR TASK 3]"),
+            PlanPerTask(task_number=1, task="Task 1", plan=" [PLAN FOR TASK 1]"),
+            PlanPerTask(task_number=2, task="Task 2", plan=" [PLAN FOR TASK 2]"),
+        ]
+
+        mock_planner_result = PlannerTaskPydanticOutput(
+            list_of_plans_per_task=out_of_order_plans
+        )
+
+        with patch.object(
+            CrewPlanner, "_handle_crew_planning", return_value=mock_planner_result
+        ):
+            crew._handle_crew_planning()
+
+        assert "[PLAN FOR TASK 1]" in task1.description
+        assert "[PLAN FOR TASK 2]" in task2.description
+        assert "[PLAN FOR TASK 3]" in task3.description
+
+        assert "[PLAN FOR TASK 3]" not in task1.description
+        assert "[PLAN FOR TASK 1]" not in task2.description
+        assert "[PLAN FOR TASK 2]" not in task3.description
+
+    def test_crew_planning_with_missing_plan(self):
+        """Test that missing plans are handled gracefully with a warning."""
+        agent1 = Agent(role="Agent 1", goal="Goal 1", backstory="Backstory 1")
+        agent2 = Agent(role="Agent 2", goal="Goal 2", backstory="Backstory 2")
+
+        task1 = Task(
+            description="First task description",
+            expected_output="Output 1",
+            agent=agent1,
+        )
+        task2 = Task(
+            description="Second task description",
+            expected_output="Output 2",
+            agent=agent2,
+        )
+
+        crew = Crew(
+            agents=[agent1, agent2],
+            tasks=[task1, task2],
+            planning=True,
+        )
+
+        original_task1_desc = task1.description
+        original_task2_desc = task2.description
+
+        incomplete_plans = [
+            PlanPerTask(task_number=1, task="Task 1", plan=" [PLAN FOR TASK 1]"),
+        ]
+
+        mock_planner_result = PlannerTaskPydanticOutput(
+            list_of_plans_per_task=incomplete_plans
+        )
+
+        with patch.object(
+            CrewPlanner, "_handle_crew_planning", return_value=mock_planner_result
+        ):
+            crew._handle_crew_planning()
+
+        assert "[PLAN FOR TASK 1]" in task1.description
+
+        assert task2.description == original_task2_desc
+
+    def test_crew_planning_preserves_original_description(self):
+        """Test that planning appends to the original task description."""
+        agent = Agent(role="Agent 1", goal="Goal 1", backstory="Backstory 1")
+
+        task = Task(
+            description="Original task description",
+            expected_output="Output 1",
+            agent=agent,
+        )
+
+        crew = Crew(
+            agents=[agent],
+            tasks=[task],
+            planning=True,
+        )
+
+        plans = [
+            PlanPerTask(task_number=1, task="Task 1", plan=" - Additional plan steps"),
+        ]
+
+        mock_planner_result = PlannerTaskPydanticOutput(list_of_plans_per_task=plans)
+
+        with patch.object(
+            CrewPlanner, "_handle_crew_planning", return_value=mock_planner_result
+        ):
+            crew._handle_crew_planning()
+
+        assert "Original task description" in task.description
+        assert "Additional plan steps" in task.description
+
+    def test_crew_planning_with_duplicate_task_numbers(self):
+        """Test that duplicate task numbers use the first plan and log a warning."""
+        agent = Agent(role="Agent 1", goal="Goal 1", backstory="Backstory 1")
+
+        task = Task(
+            description="Task description",
+            expected_output="Output 1",
+            agent=agent,
+        )
+
+        crew = Crew(
+            agents=[agent],
+            tasks=[task],
+            planning=True,
+        )
+
+        # Two plans with the same task_number - should use the first one
+        duplicate_plans = [
+            PlanPerTask(task_number=1, task="Task 1", plan=" [FIRST PLAN]"),
+            PlanPerTask(task_number=1, task="Task 1", plan=" [SECOND PLAN]"),
+        ]
+
+        mock_planner_result = PlannerTaskPydanticOutput(
+            list_of_plans_per_task=duplicate_plans
+        )
+
+        with patch.object(
+            CrewPlanner, "_handle_crew_planning", return_value=mock_planner_result
+        ):
+            crew._handle_crew_planning()
+
+        # Should use the first plan, not the second
+        assert "[FIRST PLAN]" in task.description
+        assert "[SECOND PLAN]" not in task.description

lib/crewai/tests/utilities/test_pydantic_schema_parser.py

@@ -1,94 +0,0 @@
-from typing import Any, Dict, List, Optional, Set, Tuple, Union
-
-import pytest
-from pydantic import BaseModel, Field
-
-from crewai.utilities.pydantic_schema_parser import PydanticSchemaParser
-
-
-def test_simple_model():
-    class SimpleModel(BaseModel):
-        field1: int
-        field2: str
-
-    parser = PydanticSchemaParser(model=SimpleModel)
-    schema = parser.get_schema()
-
-    expected_schema = """{
-    field1: int,
-    field2: str
-}"""
-    assert schema.strip() == expected_schema.strip()
-
-
-def test_nested_model():
-    class NestedModel(BaseModel):
-        nested_field: int
-
-    class ParentModel(BaseModel):
-        parent_field: str
-        nested: NestedModel
-
-    parser = PydanticSchemaParser(model=ParentModel)
-    schema = parser.get_schema()
-
-    expected_schema = """{
-    parent_field: str,
-    nested: NestedModel
-    {
-        nested_field: int
-    }
-}"""
-    assert schema.strip() == expected_schema.strip()
-
-
-def test_model_with_list():
-    class ListModel(BaseModel):
-        list_field: List[int]
-
-    parser = PydanticSchemaParser(model=ListModel)
-    schema = parser.get_schema()
-
-    expected_schema = """{
-    list_field: List[int]
-}"""
-    assert schema.strip() == expected_schema.strip()
-
-
-def test_model_with_optional_field():
-    class OptionalModel(BaseModel):
-        optional_field: Optional[str]
-
-    parser = PydanticSchemaParser(model=OptionalModel)
-    schema = parser.get_schema()
-
-    expected_schema = """{
-    optional_field: Optional[str]
-}"""
-    assert schema.strip() == expected_schema.strip()
-
-
-def test_model_with_union():
-    class UnionModel(BaseModel):
-        union_field: Union[int, str]
-
-    parser = PydanticSchemaParser(model=UnionModel)
-    schema = parser.get_schema()
-
-    expected_schema = """{
-    union_field: Union[int, str]
-}"""
-    assert schema.strip() == expected_schema.strip()
-
-
-def test_model_with_dict():
-    class DictModel(BaseModel):
-        dict_field: Dict[str, int]
-
-    parser = PydanticSchemaParser(model=DictModel)
-    schema = parser.get_schema()
-
-    expected_schema = """{
-    dict_field: Dict[str, int]
-}"""
-    assert schema.strip() == expected_schema.strip()

lib/devtools/src/crewai_devtools/__init__.py

@@ -1,3 +1,3 @@
 """CrewAI development tools."""
 
-__version__ = "1.7.0"
+__version__ = "1.7.2"

lib/devtools/src/crewai_devtools/cli.py

@@ -323,13 +323,17 @@ def cli() -> None:
     "--dry-run", is_flag=True, help="Show what would be done without making changes"
 )
 @click.option("--no-push", is_flag=True, help="Don't push changes to remote")
-def bump(version: str, dry_run: bool, no_push: bool) -> None:
+@click.option(
+    "--no-commit", is_flag=True, help="Don't commit changes (just update files)"
+)
+def bump(version: str, dry_run: bool, no_push: bool, no_commit: bool) -> None:
     """Bump version across all packages in lib/.
 
     Args:
         version: New version to set (e.g., 1.0.0, 1.0.0a1).
         dry_run: Show what would be done without making changes.
         no_push: Don't push changes to remote.
+        no_commit: Don't commit changes (just update files).
     """
     try:
         # Check prerequisites
@@ -397,51 +401,60 @@ def bump(version: str, dry_run: bool, no_push: bool) -> None:
         else:
             console.print("[dim][DRY RUN][/dim] Would run: uv sync")
 
-        branch_name = f"feat/bump-version-{version}"
-        if not dry_run:
-            console.print(f"\nCreating branch {branch_name}...")
-            run_command(["git", "checkout", "-b", branch_name])
-            console.print("[green]✓[/green] Branch created")
-
-            console.print("\nCommitting changes...")
-            run_command(["git", "add", "."])
-            run_command(["git", "commit", "-m", f"feat: bump versions to {version}"])
-            console.print("[green]✓[/green] Changes committed")
-
-            if not no_push:
-                console.print("\nPushing branch...")
-                run_command(["git", "push", "-u", "origin", branch_name])
-                console.print("[green]✓[/green] Branch pushed")
+        if no_commit:
+            console.print("\nSkipping git operations (--no-commit flag set)")
         else:
-            console.print(f"[dim][DRY RUN][/dim] Would create branch: {branch_name}")
-            console.print(
-                f"[dim][DRY RUN][/dim] Would commit: feat: bump versions to {version}"
-            )
-            if not no_push:
-                console.print(f"[dim][DRY RUN][/dim] Would push branch: {branch_name}")
+            branch_name = f"feat/bump-version-{version}"
+            if not dry_run:
+                console.print(f"\nCreating branch {branch_name}...")
+                run_command(["git", "checkout", "-b", branch_name])
+                console.print("[green]✓[/green] Branch created")
 
-        if not dry_run and not no_push:
-            console.print("\nCreating pull request...")
-            run_command(
-                [
-                    "gh",
-                    "pr",
-                    "create",
-                    "--base",
-                    "main",
-                    "--title",
-                    f"feat: bump versions to {version}",
-                    "--body",
-                    "",
-                ]
-            )
-            console.print("[green]✓[/green] Pull request created")
-        elif dry_run:
-            console.print(
-                f"[dim][DRY RUN][/dim] Would create PR: feat: bump versions to {version}"
-            )
-        else:
-            console.print("\nSkipping PR creation (--no-push flag set)")
+                console.print("\nCommitting changes...")
+                run_command(["git", "add", "."])
+                run_command(
+                    ["git", "commit", "-m", f"feat: bump versions to {version}"]
+                )
+                console.print("[green]✓[/green] Changes committed")
+
+                if not no_push:
+                    console.print("\nPushing branch...")
+                    run_command(["git", "push", "-u", "origin", branch_name])
+                    console.print("[green]✓[/green] Branch pushed")
+            else:
+                console.print(
+                    f"[dim][DRY RUN][/dim] Would create branch: {branch_name}"
+                )
+                console.print(
+                    f"[dim][DRY RUN][/dim] Would commit: feat: bump versions to {version}"
+                )
+                if not no_push:
+                    console.print(
+                        f"[dim][DRY RUN][/dim] Would push branch: {branch_name}"
+                    )
+
+            if not dry_run and not no_push:
+                console.print("\nCreating pull request...")
+                run_command(
+                    [
+                        "gh",
+                        "pr",
+                        "create",
+                        "--base",
+                        "main",
+                        "--title",
+                        f"feat: bump versions to {version}",
+                        "--body",
+                        "",
+                    ]
+                )
+                console.print("[green]✓[/green] Pull request created")
+            elif dry_run:
+                console.print(
+                    f"[dim][DRY RUN][/dim] Would create PR: feat: bump versions to {version}"
+                )
+            else:
+                console.print("\nSkipping PR creation (--no-push flag set)")
 
         console.print(f"\n[green]✓[/green] Version bump to {version} complete!")