# Source: https://docs.pipecat.ai/server/pipeline/pipeline-task.md

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PipelineTask

> Manage pipeline execution and lifecycle with PipelineTask

## Overview

`PipelineTask` is the central class for managing pipeline execution. It handles the lifecycle of the pipeline, processes frames in both directions, manages task cancellation, and provides event handlers for monitoring pipeline activity.

## Basic Usage

```python  theme={null}
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask

# Create a pipeline
pipeline = Pipeline([...])

# Create a task with the pipeline
task = PipelineTask(pipeline)

# Queue frames for processing
await task.queue_frame(TTSSpeakFrame("Hello, how can I help you today?"))

# Run the pipeline
runner = PipelineRunner()
await runner.run(task)
```

## Constructor Parameters

<ParamField path="pipeline" type="BasePipeline" required>
  The pipeline to execute.
</ParamField>

<ParamField path="params" type="PipelineParams" default="PipelineParams()">
  Configuration parameters for the pipeline. See
  [PipelineParams](/server/pipeline/pipeline-params) for details.
</ParamField>

<ParamField path="observers" type="List[BaseObserver]" default="[]">
  List of observers for monitoring pipeline execution. See
  [Observers](/server/utilities/observers/observer-pattern) for details.
</ParamField>

<ParamField path="clock" type="BaseClock" default="SystemClock()">
  Clock implementation for timing operations.
</ParamField>

<ParamField path="task_manager" type="Optional[BaseTaskManager]" default="None">
  Custom task manager for handling asyncio tasks. If None, a default TaskManager
  is used.
</ParamField>

<ParamField path="check_dangling_tasks" type="bool" default="True">
  Whether to check for processors' tasks finishing properly.
</ParamField>

<ParamField path="idle_timeout_secs" type="Optional[float]" default="300">
  Timeout in seconds before considering the pipeline idle. Set to None to
  disable idle detection. See [Pipeline Idle
  Detection](/server/pipeline/pipeline-idle-detection) for details.
</ParamField>

<ParamField path="idle_timeout_frames" type="Tuple[Type[Frame], ...]" default="(BotSpeakingFrame, LLMFullResponseEndFrame)">
  Frame types that should prevent the pipeline from being considered idle. See
  [Pipeline Idle Detection](/server/pipeline/pipeline-idle-detection) for
  details.
</ParamField>

<ParamField path="cancel_on_idle_timeout" type="bool" default="True">
  Whether to automatically cancel the pipeline task when idle timeout is
  reached. See [Pipeline Idle
  Detection](/server/pipeline/pipeline-idle-detection) for details.
</ParamField>

<ParamField path="enable_tracing" type="bool" default="False">
  Whether to enable OpenTelemetry tracing. See [The OpenTelemetry
  guide](/server/utilities/opentelemetry) for details.
</ParamField>

<ParamField path="enable_turn_tracking" type="bool" default="False">
  Whether to enable turn tracking. See [The OpenTelemetry
  guide](/server/utilities/opentelemetry) for details.
</ParamField>

<ParamField path="conversation_id" type="Optional[str]" default="None">
  Custom ID for the conversation. If not provided, a UUID will be generated. See
  [The OpenTelemetry guide](/server/utilities/opentelemetry) for details.
</ParamField>

<ParamField path="additional_span_attributes" type="Optional[dict]" default="None">
  Any additional attributes to add to top-level OpenTelemetry conversation span.
  See [The OpenTelemetry guide](/server/utilities/opentelemetry) for details.
</ParamField>

## Methods

### Task Lifecycle Management

<ResponseField name="run()" type="async">
  Starts and manages the pipeline execution until completion or cancellation.

  ```python  theme={null}
  await task.run()
  ```
</ResponseField>

<ResponseField name="stop_when_done()" type="async">
  Sends an EndFrame to the pipeline to gracefully stop the task after all queued
  frames have been processed.

  ```python  theme={null}
  await task.stop_when_done()
  ```
</ResponseField>

<ResponseField name="cancel()" type="async">
  Stops the running pipeline immediately by sending a CancelFrame.

  ```python  theme={null}
    await task.cancel()
  ```
</ResponseField>

<ResponseField name="has_finished()" type="bool">
  Returns whether the task has finished (all processors have stopped).

  ```python  theme={null}
  if task.has_finished(): print("Task is complete")
  ```
</ResponseField>

### Frame Management

<ResponseField name="queue_frame()" type="async">
  Queues a single frame to be pushed down the pipeline.

  ```python  theme={null}
  await task.queue_frame(TTSSpeakFrame("Hello!"))
  ```
</ResponseField>

<ResponseField name="queue_frames()" type="async">
  Queues multiple frames to be pushed down the pipeline.

  ```python  theme={null}
  frames = [TTSSpeakFrame("Hello!"), TTSSpeakFrame("How are you?")]

  await task.queue_frames(frames)

  ```
</ResponseField>

## Event Handlers

PipelineTask provides an event handler that can be registered using the `event_handler` decorator:

### on\_idle\_timeout

Triggered when no activity frames (as specified by `idle_timeout_frames`) have been received within the idle timeout period.

```python  theme={null}
@task.event_handler("on_idle_timeout")
async def on_idle_timeout(task):
    print("Pipeline has been idle too long")
    await task.queue_frame(TTSSpeakFrame("Are you still there?"))
```