Agent as Tool

Use agents as callable tools for hierarchical agent composition

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

1. 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]
   )

2. With Configuration

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

3. Direct Invocation

   Call the generated tool yourself with execute_tool — the tool exposes an explicit task parameter:

   from praisonaiagents import Agent
   
   coder = Agent(name="Coder", instructions="Write clean Python code")
   writer = Agent(
       name="Writer",
       instructions="Delegate coding to Coder",
       tools=[coder.as_tool(tool_name="invoke_coder")],
   )
   
   # New in PR #4232: the tool exposes an explicit `task` parameter
   writer.execute_tool("invoke_coder", {"task": "write a haiku about async I/O"})

   The generated tool now has (task: str) in its signature — the LLM sees it in the schema and fills it, and direct callers must pass it.

How It Works

as_tool() vs Handoffs

If you previously “worked around” the broken as_tool() by switching to handoffs=, note the workaround wasn’t equivalent — invoke_{name} runs with ContextPolicy.NONE (a genuine clean slate, now that context policies take effect) while transfer_to_{name} shares context per its policy (SUMMARY by default). Now that as_tool() works in tools=[...], switch back if you want the clean-slate behaviour.

API Reference

Agent.as_tool()

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

Generated tool signature

Because as_tool() always pins ContextPolicy.NONE, the generated callable exposes a task: str keyword-only parameter. This is what the LLM tool schema advertises and what direct execute_tool calls must supply.

def invoke_<agent_name>(*, task: str) -> str

Examples

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")

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}")

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

Troubleshooting

Related