Per-Turn Tools

Scope tools to one task or one chat call without touching the agent definition

Hand a tool to a single task or a single chat call — the agent runs it for that turn and forgets it after.

python
from praisonaiagents import Agent

def lookup(symbol: str) -> str:
    """Look up a stock symbol."""
    return f"{symbol} = $100"

agent = Agent(name="Trader", instructions="Help with quotes.")
agent.chat("What is AAPL?", tools=[lookup])
Diagram

🤖 Agent

📋 Task / chat
tools=[…]

🔧 Dispatch finds
the per-turn tool

✅ Result

Quick Start

  1. One task in a team

    Give a tool to just one task with Task(tools=…):

    python
    from praisonaiagents import Agent, Task, AgentTeam
    
    def get_weather(city: str) -> str:
        """Get the weather for a city."""
        return f"Sunny in {city}"
    
    researcher = Agent(name="Researcher", instructions="Find weather info.")
    
    task = Task(
        description="Weather in Paris",
        expected_output="A one-line forecast",
        agent=researcher,
        tools=[get_weather],   # only this task gets the tool
    )
    
    AgentTeam(agents=[researcher], tasks=[task]).start()
  2. One chat call

    Pass tools= to agent.chat():

    python
    from praisonaiagents import Agent
    
    def lookup(symbol: str) -> str:
        """Look up a stock symbol."""
        return f"{symbol} = $100"
    
    agent = Agent(name="Trader", instructions="Help with quotes.")
    print(agent.chat("What is AAPL?", tools=[lookup]))
  3. Async

    agent.achat() works the same way:

    python
    import asyncio
    from praisonaiagents import Agent
    
    def lookup(symbol: str) -> str:
        """Look up a stock symbol."""
        return f"{symbol} = $100"
    
    async def main():
        agent = Agent(name="Trader", instructions="Help with quotes.")
        print(await agent.achat("What is AAPL?", tools=[lookup]))
    
    asyncio.run(main())

How It Works

Diagram
DispatchModelAgentUserDispatchModelAgentUserchat(“What is AAPL?”, tools=[lookup])Prompt + lookup schemaCall lookup(symbol=”AAPL”)Find “lookup”Per-turn tools first, then Agent(tools=…)“AAPL = $100”Final answer
SituationWhat happens
Tool only in Task(tools=…) or chat(tools=…)The per-turn tool runs
Task(tools=…) on an agent that has its own toolsThe task’s tools are added to the agent’s tools for that task
chat(tools=…) / achat(tools=…) on an agent that has its own toolsOnly the tools in the list are allowed that turn; other agent tools are refused with Tool '…' is not available in this turn
Same name in Agent(tools=…) and per-turn tools=The per-turn tool wins
Same name on an Agent(tools=MCP(...)) and a per-turn Python functionThe per-turn function wins
Per-tool guardrails (@tool(input_guardrails=…))Taken from the per-turn tool, not a same-named tool elsewhere

Common Patterns

Give one step of a pipeline an extra tool

python
from praisonaiagents import Agent, Task, AgentTeam

def fetch_prices(item: str) -> str:
    """Fetch current prices."""
    return f"{item}: $10"

analyst = Agent(name="Analyst", instructions="Analyse markets.")

gather = Task(description="Get prices for coffee", agent=analyst, tools=[fetch_prices])
report = Task(description="Write a short market note", agent=analyst)  # no extra tool

AgentTeam(agents=[analyst], tasks=[gather, report]).start()

Override one MCP tool with a local function

python
from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

def read_file(path: str) -> str:
    """Read a file from the local cache instead."""
    return "cached contents"

agent = Agent(
    name="Reader",
    instructions="Read files on request.",
    tools=MCP("npx -y @modelcontextprotocol/server-filesystem ."),
)

agent.chat("Show me notes.txt", tools=[read_file])  # local read_file wins this turn

Guard a one-off tool — attach guardrails to the tool itself and pass it per turn. See Per-Tool Guardrails.


Best Practices

Pick the right scope

Use Task(tools=…) in team pipelines and chat(tools=…) for direct one-off calls. Keep tools every turn needs in Agent(tools=…).

No need to repeat tools on the agent

A per-turn tool does not have to appear in Agent(tools=…) — it is always callable during its own turn.

chat(tools=…) is a limit, not an addition

When you pass tools= to chat() or achat(), list every tool the turn should be able to use — the agent’s other tools are refused for that turn.

Safe with concurrent turns

The per-turn scope is tracked per task and per coroutine, so parallel calls on the same agent never see each other’s tools.


Related