> ## 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.

# Decorators

> @tool, @task, and @agent_ready decorators

## @tool

Mark an agent method as an LLM tool.

On [`LLMAgent`](/api-reference/pipecat-subagents/llm-agent) subclasses, decorated methods are automatically registered with the LLM and included in `build_tools()`.

On [`FlowsAgent`](/api-reference/pipecat-subagents/flows-agent) subclasses, decorated methods are automatically collected as global functions available at every flow node.

```python theme={null}
from pipecat_subagents.agents import tool
```

Can be used with or without arguments:

```python theme={null}
@tool
async def my_tool(self, params, arg: str):
    ...

@tool(cancel_on_interruption=False, timeout=60)
async def my_tool(self, params, arg: str):
    ...
```

### Parameters

<ParamField path="cancel_on_interruption" type="bool" default="True">
  Whether to cancel this tool call when an interruption occurs. Only applies to
  `LLMAgent` tools.
</ParamField>

<ParamField path="timeout" type="float | None" default="None">
  Timeout in seconds for this tool call. Defaults to `None` (uses the LLM
  service default).
</ParamField>

### Method Signature

Tool methods receive the LLM function call parameters object as their first argument (after `self`), followed by the tool's declared parameters:

```python theme={null}
@tool
async def get_weather(self, params, location: str, unit: str = "celsius"):
    """Get the current weather for a location."""
    result = await fetch_weather(location, unit)
    await params.result_callback(result)
```

<Note>
  Tool methods must call `params.result_callback()` to return a result to the
  LLM. The method signature (parameter names, types, and docstring) is
  automatically used to generate the tool schema.
</Note>

## @task

Mark an agent method as a task handler.

Decorated methods are automatically collected by [`BaseAgent`](/api-reference/pipecat-subagents/base-agent) at initialization and dispatched when matching task requests arrive. Each request runs in its own asyncio task so the bus message loop is never blocked.

```python theme={null}
from pipecat_subagents.agents import task
```

Can be used with or without arguments:

```python theme={null}
# Default handler (receives unnamed requests)
@task
async def on_task_request(self, message):
    result = await do_work(message.payload)
    await self.send_task_response(result)

# Named handler (receives only "research" requests)
@task(name="research")
async def on_research(self, message):
    result = await do_research(message.payload)
    await self.send_task_response(result)
```

### Parameters

<ParamField path="name" type="str | None" default="None">
  Task name to match. When set, this handler only receives requests with a
  matching name. When `None`, handles all unnamed requests (or requests with no
  matching named handler).
</ParamField>

### Method Signature

Task handler methods receive a [`BusTaskRequestMessage`](/api-reference/pipecat-subagents/messages#bustaskrequestmessage):

```python theme={null}
@task(name="analyze")
async def on_analyze(self, message: BusTaskRequestMessage):
    data = message.payload
    # Send progress updates
    await self.send_task_update({"progress": 50})
    # Send final response
    await self.send_task_response({"result": "done"})
```

## @agent\_ready

Mark a method as a handler for a specific agent becoming ready.

Decorated methods are automatically collected by [`BaseAgent`](/api-reference/pipecat-subagents/base-agent) at initialization. When `on_ready` fires, the agent calls `watch_agent` for each decorated handler. When the watched agent registers, the decorated method is called.

```python theme={null}
from pipecat_subagents.agents import agent_ready
```

```python theme={null}
@agent_ready(name="greeter")
async def on_greeter_ready(self, data: AgentReadyData) -> None:
    await self.activate_agent("greeter", args=...)
```

### Parameters

<ParamField path="name" type="str" required>
  The name of the agent to watch.
</ParamField>

### Method Signature

Agent-ready handler methods receive an [`AgentReadyData`](/api-reference/pipecat-subagents/types#agentreadydata) instance:

```python theme={null}
@agent_ready(name="worker")
async def on_worker_ready(self, data: AgentReadyData) -> None:
    print(f"Agent {data.agent_name} is ready on runner {data.runner}")
```