Skip to main content

​
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.
​
name
str
required
Unique name for this agent.
​
bus
AgentBus
required
The AgentBus for inter-agent communication.
​
active
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.
​
bridged
Optional[tuple[str, ...]]
default:"None"
Bridge configuration. See BaseAgent for details.
​
defer_tool_frames
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: Optional[dict]) -> 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.
ParameterTypeDescription
argsOptional[dict]Activation arguments (see LLMAgentActivationArgs)

​
handoff_to

async def handoff_to(
    self,
    agent_name: str,
    *,
    args: Optional[AgentActivationArgs] = None,
    result_callback: Optional[FunctionCallResultCallback] = 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.
ParameterTypeDefaultDescription
agent_namestrName of the agent to hand off to
argsOptional[AgentActivationArgs]NoneArguments forwarded to on_activated
result_callbackOptional[FunctionCallResultCallback]NoneThe result_callback from FunctionCallParams

​
end

async def end(
    self,
    *,
    reason: Optional[str] = None,
    result_callback: Optional[FunctionCallResultCallback] = 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.
ParameterTypeDefaultDescription
reasonOptional[str]NoneHuman-readable reason for ending
result_callbackOptional[FunctionCallResultCallback]NoneThe 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.
ParameterTypeDescription
frameslist[tuple[Frame, FrameDirection]]The deferred frames collected during tool execution
Returns: The frames to queue. Return the list as-is for default behavior.