LLMAgent

Overview

LLMAgent extends BaseAgent with an LLM pipeline and automatic tool registration. Subclasses implement build_llm() to provide an LLM service and define tools with the @tool decorator.

from pipecat_subagents.agents import LLMAgent

class MyAgent(LLMAgent):
    def build_llm(self) -> LLMService:
        return OpenAILLMService(
            api_key="...",
            system_instruction="You are a helpful assistant.",
        )

    @tool
    async def my_function(self, params, arg: str):
        ...

Configuration

Inherits all parameters from BaseAgent.

str

required

Unique name for this agent.

AgentBus

required

The AgentBus for inter-agent communication.

bool

default:"False"

Whether the agent starts active. Defaults to False (unlike BaseAgent which defaults to True), since LLM agents typically wait to be activated via handoff.

tuple[str, ...] | None

default:"None"

Bridge configuration. See BaseAgent for details.

bool

default:"True"

Whether to defer frames queued during tool execution until all tools complete. When True, any frames queued via queue_frame() while a @tool method is running are held in an internal queue and delivered automatically once the last tool finishes.

Properties

Inherits all properties from BaseAgent.

tool_call_active

agent.tool_call_active -> bool

True when one or more @tool methods are executing.

Abstract Methods

build_llm

@abstractmethod
def build_llm(self) -> LLMService

Return the LLM service for this agent. Subclasses must implement this to provide a configured LLMService (e.g. OpenAILLMService, AnthropicLLMService). Tool registration is handled automatically; do not register @tool methods here. Returns: An LLMService instance.

Methods

build_tools

def build_tools(self) -> list

Return the tools for this agent’s LLM. By default, returns all methods decorated with @tool. Override to provide additional or different tools. Returns: List of tool functions.

create_llm

def create_llm(self) -> LLMService

Create the LLM with tools registered. Calls build_llm() and registers all @tool decorated methods. Each tool is automatically wrapped with inflight tracking for frame deferral. Override to customize the LLM setup. Returns: The configured LLMService.

on_activated

async def on_activated(self, args: dict | None) -> None

Configure the LLM with tools and activation messages. When args contains messages, they are appended to the LLM context. When args contains run_llm (defaults to True when messages are set), the LLM is triggered after appending.

Parameter	Type	Description
`args`	`dict	None`	Activation arguments (see `LLMAgentActivationArgs`)

handoff_to

async def handoff_to(
    self,
    agent_name: str,
    *,
    args: AgentActivationArgs | None = None,
    result_callback: FunctionCallResultCallback | None = None,
) -> None

Hand off to another agent. When called from a @tool handler, pass params.result_callback to ensure any pending LLM output is fully delivered before handing off.

Parameter	Type	Default	Description
`agent_name`	`str`		Name of the agent to hand off to
`args`	`AgentActivationArgs	None`	`None`	Arguments forwarded to `on_activated`
`result_callback`	`FunctionCallResultCallback	None`	`None`	The `result_callback` from `FunctionCallParams`

end

async def end(
    self,
    *,
    reason: str | None = None,
    result_callback: FunctionCallResultCallback | None = None,
) -> None

Request a graceful end of the session. When called from a @tool handler, pass params.result_callback to ensure any pending LLM output is fully delivered before ending.

Parameter	Type	Default	Description
`reason`	`str	None`	`None`	Human-readable reason for ending
`result_callback`	`FunctionCallResultCallback	None`	`None`	The `result_callback` from `FunctionCallParams`

process_deferred_tool_frames

async def process_deferred_tool_frames(
    self,
    frames: list[tuple[Frame, FrameDirection]],
) -> list[tuple[Frame, FrameDirection]]

Process deferred frames before they are flushed. Called after all in-flight tools complete, before the deferred frames are queued into the pipeline. Override to inspect, modify, reorder, or filter the frames.

Parameter	Type	Description
`frames`	`list[tuple[Frame, FrameDirection]]`	The deferred frames collected during tool execution

Returns: The frames to queue. Return the list as-is for default behavior.

Pipecat Server

Pipecat Subagents

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Overview

Configuration

Properties

tool_call_active

Abstract Methods

build_llm

Methods

build_tools

create_llm

on_activated

handoff_to

end

process_deferred_tool_frames

​Overview

​Configuration

​Properties

​tool_call_active

​Abstract Methods

​build_llm

​Methods

​build_tools

​create_llm

​on_activated

​handoff_to

​end

​process_deferred_tool_frames

Overview

Configuration

Properties

tool_call_active

Abstract Methods

build_llm

Methods

build_tools

create_llm

on_activated

handoff_to

end

process_deferred_tool_frames