DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Classes / PendingFeedbackContext
Class hitl

PendingFeedbackContext: Reference Guide

By DevShelfHub

The context object passed to HumanFeedbackProvider.request — carries prompt, metadata, and routing keys.

See the CrewAI API reference index, CrewAI introduction, and core concepts for surrounding context.

What is PendingFeedbackContext?

PendingFeedbackContext is the structured envelope the Flow runtime hands your HumanFeedbackProvider when an @human_feedback step suspends. Think of it as the ticket opened for that pause: it carries the human-readable prompt, any metadata your flow attached (correlation ids, SLA hints, UI deep links), and routing keys so multi-tenant providers can fan requests to the correct Slack channel or inbox without parsing free-form strings.

Treat fields as immutable from the provider's perspective — mutate flow state only through sanctioned APIs after the user responds. The object is also the right place to log for audits because it ties the out-of-band approval back to the originating method and Flow instance when you combine HITL with @persist checkpoints.

If you build bespoke review UIs, serialize the subset of attributes your front end needs rather than pickling the whole context; CrewAI may extend the schema across minor versions and defensive coding keeps providers compatible.

When to Use

Inside provider implementations.

Use Cases

  • • Routing approvals
  • • Building per-context UIs

Key Features

  • ✓ Prompt
  • ✓ Metadata
  • ✓ Routing keys

When NOT to Use

Outside provider code.

Notes

Secrets in metadata

Do not stash API keys or PII you would not write to application logs inside metadata just because it is convenient. Downstream serializers and observability hooks may echo those fields.

Long waits and process lifetime

Providers often block for hours. Ensure the host process stays alive or externalize the wait onto a webhook that resumes the Flow via persisted state instead of holding an asyncio task open indefinitely.

Version skew

Optional attributes appear as CrewAI adds richer HITL telemetry. Use dict.get patterns on metadata and avoid hard-coded positional unpacking of undocumented tuples.

Import

python 
from crewai.flow.human_feedback import PendingFeedbackContext

Code Examples

Log and route by metadata

python 
import logging
from crewai.flow.human_feedback import HumanFeedbackProvider, PendingFeedbackContext

log = logging.getLogger(__name__)

class RoutedProvider(HumanFeedbackProvider):
    async def request(self, ctx: PendingFeedbackContext) -> str:
        tenant = (ctx.metadata or {}).get('tenant_id', 'unknown')
        log.info('hitl.waiting', extra={'tenant': tenant, 'prompt_len': len(ctx.prompt or '')})
        return await self._ui.wait_for_decision(tenant, ctx.prompt)

Slack thread keyed off routing fields

python 
async def request(self, ctx: PendingFeedbackContext) -> str:
    channel = ctx.metadata.get('slack_channel') if ctx.metadata else None
    thread = await slack.open_thread(channel, ctx.prompt)
    return await slack.collect_reactions(thread, timeout_s=86400)

Timeout-safe wrapper sketch

python 
import asyncio

async def request(self, ctx: PendingFeedbackContext) -> str:
    try:
        return await asyncio.wait_for(self._human_queue.get(ctx), timeout=3600)
    except asyncio.TimeoutError:
        return 'timeout: escalate to on-call'

Common Mistakes

❌ Mutating ctx fields to push answers back into the flow

✅ Return the operator's string/intent from request(); let the runtime merge it into flow state.

❌ Blocking the event loop with synchronous HTTP inside request()

✅ Await async clients or run blocking SDK calls in asyncio.to_thread.

PendingFeedbackContext FAQ

What is PendingFeedbackContext in CrewAI?

The context object passed to HumanFeedbackProvider.request — carries prompt, metadata, and routing keys. PendingFeedbackContext is the structured envelope the Flow runtime hands your HumanFeedbackProvider when an @human_feedback step suspends. Think of it as the ticket opened for that pause: it carries the human-readable prompt, any metadata your flow attached (correlation ids, SLA hints, UI deep links), and routing keys so multi-tenant providers can fan requests to the correct Slack channel or inbox without parsing free-form strings. Treat fields as immutable from the provider…

Which package defines the CrewAI class PendingFeedbackContext?

DevShelfHub maps PendingFeedbackContext to Python module crewai.flow.human_feedback (package path crewai.flow.human_feedback in this reference). Pin your installed crewai version and match imports to the snippet on this page.

When should I use PendingFeedbackContext?

Inside provider implementations.

When should I avoid using PendingFeedbackContext?

Outside provider code.

How do I import PendingFeedbackContext in Python?

from crewai.flow.human_feedback import PendingFeedbackContext

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search 58 classes, 30 methods, and 16 decorators, each with runnable examples, parameters, common mistakes, and cross-links.