Understand where tools live — agent-level vs task-level
Overview
Tools can be attached at two levels: Agent and Task. Where you place a tool determines its scope and availability.
Agent-Level Tools
Tools added to an agent are available for every task that agent executes.
from upsonic import Agent, Taskfrom upsonic.tools import tool@tooldef 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 taskstask1 = 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)
Task-Level Tools
Tools added to a task are only available for that specific task. Other tasks executed by the same agent cannot use them.
from upsonic import Agent, Taskfrom upsonic.tools import tool@tooldef calculate_tax(amount: float, rate: float) -> float: """Calculate tax for given amount.""" return amount * rateagent = Agent("anthropic/claude-sonnet-4-5")# calculate_tax is only available for this tasktask1 = 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_taxtask2 = 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, Taskfrom upsonic.tools import tool@tooldef search(query: str) -> str: """Search for information.""" return f"Results for: {query}"@tooldef summarize(text: str) -> str: """Summarize the given text.""" return f"Summary of: {text}"# search is available for ALL tasksagent = 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 summarizetask2 = 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.