Overview
Tools can be attached at two levels: Agent and Task. Where you place a tool determines its scope and availability.
Tools added to an agent are available for every task that agent executes.
from upsonic import Agent, Task
from upsonic.tools import tool
@tool
def search(query: str) -> str:
"""Search for information."""
return f"Results for: {query}"
agent = Agent("anthropic/claude-sonnet-4-5")
agent.add_tools(search) # Agent-level tool
# search is available in both tasks
task1 = Task(description="Search for Python tutorials")
result = agent.print_do(task1)
print("Result:", result)
task2 = Task(description="Search for JavaScript frameworks")
result = agent.print_do(task2)
print("Result:", result)
from upsonic import Agent, Task
from upsonic.tools import tool
@tool
def calculate_tax(amount: float, rate: float) -> float:
"""Calculate tax for given amount."""
return amount * rate
agent = Agent("anthropic/claude-sonnet-4-5")
# calculate_tax is only available for this task
task1 = Task(
description="Calculate 18% tax on 1000",
tools=[calculate_tax]
)
result = agent.print_do(task1)
print("Result:", result)
# This task does NOT have access to calculate_tax
task2 = Task(description="What is the capital of France?")
result = agent.print_do(task2)
print("Result:", result)
Combining Both Levels
When an agent has tools and a task also has tools, the task gets access to both:
from upsonic import Agent, Task
from upsonic.tools import tool
@tool
def search(query: str) -> str:
"""Search for information."""
return f"Results for: {query}"
@tool
def summarize(text: str) -> str:
"""Summarize the given text."""
return f"Summary of: {text}"
# search is available for ALL tasks
agent = Agent("anthropic/claude-sonnet-4-5", tools=[search])
# This task has both: search (from agent) + summarize (task-only)
task1 = Task(
description="Search for AI news and summarize the results",
tools=[summarize]
)
result = agent.print_do(task1)
print("Result:", result)
# This task only has search (from agent), NOT summarize
task2 = Task(description="Search for Python tutorials")
result = agent.print_do(task2)
print("Result:", result)
Summary
| Level | Scope | Use When |
|---|
| Agent | Available for all tasks the agent runs | The tool is generally useful across many tasks |
| Task | Available only for that specific task | The tool is needed for one specific operation |
Use agent-level tools for general-purpose tools like search, database access, or utilities. Use task-level tools for specialized tools that are only relevant to a specific task — this keeps the LLM focused by not exposing unnecessary tools.
