Agent as Tool

Agent as Tool turns any agent into a callable tool so a parent agent can invoke specialists and keep control of the result.

from praisonaiagents import Agent

researcher = Agent(name="Researcher", instructions="Research topics thoroughly")
writer = Agent(
    name="Writer",
    instructions="Write polished copy using specialist tools",
    tools=[researcher.as_tool()],
)
writer.start("Write a short post about quantum computing with cited facts")

The user asks for a polished article; the writer agent invokes the researcher as a tool and composes the answer.

Quick Start

Simple Usage

from praisonaiagents import Agent

# Create specialist agents
researcher = Agent(
    name="Researcher",
    instructions="Research topics thoroughly and return findings"
)

coder = Agent(
    name="Coder", 
    instructions="Write clean Python code"
)

# Parent agent uses specialists as tools
writer = Agent(
    name="Writer",
    instructions="Write technical articles using your tools",
    tools=[
        researcher.as_tool("Research a topic and return findings"),
        coder.as_tool("Write Python code for a given task"),
    ]
)

# Writer invokes researcher and coder as needed
result = writer.start("Write an article about async Python patterns")

from praisonaiagents import Agent

analyst = Agent(name="DataAnalyst", instructions="Analyze data")

# Custom tool name and description
tool = analyst.as_tool(
    description="Analyze dataset and return insights",
    tool_name="analyze_data"
)

coordinator = Agent(
    name="Coordinator",
    tools=[tool]
)

With Configuration

Pass custom tool_name and description to as_tool() when the default labels are not clear enough for the parent LLM.

How It Works

Step	What happens
1. Request	User asks the parent agent for a result
2. Invoke	Parent LLM decides to call the specialist as a tool
3. Execute	Specialist agent runs with a clean context
4. Return	Result is returned to the parent agent
5. Respond	Parent composes the final response

as_tool() vs Handoffs

Key Difference: With as_tool(), the parent agent retains control and receives results. With handoffs, control transfers entirely to the target agent.

Feature	`as_tool()`	Handoffs
Control	Parent retains control	Control transfers to target
Context	No history passed (clean slate)	Context passed based on policy
Use Case	Hierarchical composition	Task delegation
Return	Result returned to parent	Target continues conversation

API Reference

`Agent.as_tool()`

def as_tool(
    self,
    description: Optional[str] = None,
    tool_name: Optional[str] = None,
) -> Handoff

str

Tool description for the LLM. Describes what this agent does. Default: "Invoke {agent_name} to complete a subtask and return the result"

str

Custom tool name. Default: invoke_{agent_name} (snake_case)

Handoff

A Handoff configured with ContextPolicy.NONE (no history passed to child).

Examples

Research + Writing Pipeline

from praisonaiagents import Agent

# Specialist agents
researcher = Agent(
    name="Researcher",
    instructions="Search the web and compile research findings"
)

fact_checker = Agent(
    name="FactChecker", 
    instructions="Verify facts and cite sources"
)

# Writer uses both as tools
writer = Agent(
    name="Writer",
    instructions="""Write articles using your tools:
    - Use invoke_researcher for initial research
    - Use invoke_factchecker to verify claims""",
    tools=[
        researcher.as_tool("Research a topic"),
        fact_checker.as_tool("Verify facts and claims"),
    ]
)

result = writer.start("Write about quantum computing breakthroughs in 2024")

Code Review Pipeline

from praisonaiagents import Agent

# Specialist agents
linter = Agent(
    name="Linter",
    instructions="Check code for style issues and bugs"
)

security_scanner = Agent(
    name="SecurityScanner",
    instructions="Scan code for security vulnerabilities"
)

# Reviewer orchestrates both
reviewer = Agent(
    name="CodeReviewer",
    instructions="Review code using your analysis tools",
    tools=[
        linter.as_tool("Lint code for issues"),
        security_scanner.as_tool("Scan for security vulnerabilities"),
    ]
)

code = """
def login(username, password):
    query = f"SELECT * FROM users WHERE name='{username}'"
    return db.execute(query)
"""

result = reviewer.start(f"Review this code:\n{code}")

Multi-Step Analysis

from praisonaiagents import Agent

# Create a chain of specialists
data_fetcher = Agent(name="DataFetcher", instructions="Fetch data from APIs")
analyzer = Agent(name="Analyzer", instructions="Analyze data patterns")
visualizer = Agent(name="Visualizer", instructions="Create visualizations")

# Orchestrator uses all three
orchestrator = Agent(
    name="Orchestrator",
    instructions="Coordinate data analysis workflow",
    tools=[
        data_fetcher.as_tool("Fetch data from a source"),
        analyzer.as_tool("Analyze data and find patterns"),
        visualizer.as_tool("Create charts and visualizations"),
    ]
)

result = orchestrator.start("Analyze sales trends for Q4 2024")

Best Practices

Clear Descriptions

Provide clear tool descriptions so the LLM knows when to invoke each specialist.

Single Responsibility

Each specialist agent should have one clear purpose.

Avoid Deep Nesting

Keep hierarchies shallow (2-3 levels max) for clarity.

Test Individually

Test each specialist agent independently before composing.

Handoffs

Transfer control between agents

Multi-Agent Workflows

Coordinate multiple agents

Toolsets

Create custom tools

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

as_tool() vs Handoffs

API Reference

`Agent.as_tool()`

Examples

Best Practices

Handoffs

Multi-Agent Workflows

Toolsets

​Quick Start

​How It Works

​as_tool() vs Handoffs

​API Reference

​Agent.as_tool()

​Examples

​Best Practices

​Related

Handoffs

Multi-Agent Workflows

Toolsets

Quick Start

How It Works

as_tool() vs Handoffs

API Reference

`Agent.as_tool()`

Examples

Best Practices

Related