Skip to main content
Thinking capabilities enable your agent to plan and orchestrate multiple tool calls in a structured, step-by-step manner. This feature is essential when tasks require coordinating several tools to reach a comprehensive conclusion.

​
Why Use Thinking?

Thinking is most valuable when your agent has multiple tools and needs to:
  • Create an execution plan before acting
  • Call tools in a specific sequence
  • Synthesize results from multiple sources
Without thinking, agents make ad-hoc tool calls. With thinking, agents strategically plan their approach first.

​
Enabling Thinking

To enable thinking capabilities, set enable_thinking_tool=True when creating your agent: 
from upsonic import Agent, Task
from upsonic.tools import tool

# Define tools the agent can use
@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: Sunny, 25°C"

@tool
def get_population(city: str) -> str:
    """Get population for a city."""
    return f"Population of {city}: 2.1 million"

# Enable thinking for multi-tool orchestration
agent = Agent(
    model="openai/gpt-4o",
    name="CityAnalyst",
    tools=[get_weather, get_population],
    enable_thinking_tool=True,
    debug=True
)

# Create task and execute
task = Task("Tell me about Paris's weather and population")
result = agent.do(task)
print(result)

​
How Thinking Works

When thinking is enabled, the agent follows a structured “blueprint” approach:
  1. Strategic Planning: The agent creates a complete, sequential plan of tool calls
  2. Orchestrated Execution: Tools are executed step-by-step according to the plan
  3. Final Synthesis: Results from all tools are combined into a comprehensive answer
Example Flow:
1. Agent receives: "Tell me about Paris's weather and population"
2. Agent creates plan: [get_weather("Paris"), get_population("Paris")]
3. Orchestrator executes: get_weather → get_population
4. Agent synthesizes: "Paris has sunny weather at 25°C and 2.1 million residents"

​
Thinking vs. Basic Mode

FeatureBasic ModeThinking Mode
PlanningAd-hoc tool callsStructured blueprint creation
ExecutionDirect tool executionOrchestrated step-by-step execution
Best ForSingle tool tasksMulti-tool coordination

​
Thinking Configuration

​
Agent-Level Thinking

from upsonic import Agent, Task
from upsonic.tools import tool

@tool
def search_web(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

@tool
def analyze_sentiment(text: str) -> str:
    """Analyze sentiment of text."""
    return "Sentiment: Positive (85% confidence)"

# Enable thinking for all tasks
agent = Agent(
    model="openai/gpt-4o",
    name="ResearchAgent",
    tools=[search_web, analyze_sentiment],
    enable_thinking_tool=True
)

# Execute a research task
task = Task("Search for information about AI trends and analyze the sentiment")
result = agent.do(task)
print(result)

​
Task-Level Thinking

from upsonic import Agent, Task
from upsonic.tools import tool

@tool
def search_web(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query} - Found 5 relevant articles"

@tool
def analyze_sentiment(text: str) -> str:
    """Analyze sentiment of text."""
    return "Sentiment: Positive (85% confidence)"

# Create agent without thinking enabled by default
agent = Agent(
    model="openai/gpt-4o",
    name="ResearchAgent",
    tools=[search_web, analyze_sentiment]
)

# Override agent settings for specific task - enable thinking
task = Task(
    description="Search for recent AI news and analyze the sentiment",
    enable_thinking_tool=True  # Enable thinking for this specific task
)

result = agent.do(task)
print(result)

​
Mixed Configuration

from upsonic import Agent, Task
from upsonic.tools import tool

@tool
def search_web(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

@tool
def analyze_sentiment(text: str) -> str:
    """Analyze sentiment of text."""
    return "Sentiment: Positive (85% confidence)"

# Agent with thinking enabled
agent = Agent(
    model="openai/gpt-4o",
    name="AnalysisAgent",
    tools=[search_web, analyze_sentiment],
    enable_thinking_tool=True
)

# Simple task without thinking (single tool)
simple_task = Task(
    description="What time is it in Tokyo?",
    enable_thinking_tool=False  # Disable thinking for simple queries
)
result1 = agent.do(simple_task)
print("Simple result:", result1)

# Complex task with thinking (multiple tools)
complex_task = Task(
    description="Research the topic of electric vehicles and analyze public sentiment",
    enable_thinking_tool=True  # Keep thinking for complex analysis
)
result2 = agent.do(complex_task)
print("Complex result:", result2)

​
When to Use Thinking

Thinking is ideal for:
  • Multi-source Research: Gathering data from multiple tools and synthesizing
  • Step-by-Step Analysis: Tasks requiring sequential tool execution
  • Complex Workflows: When tool outputs feed into subsequent tool calls
  • Data Aggregation: Combining results from several sources

​
Example: Financial Analysis with Multiple Tools

from upsonic import Agent, Task
from upsonic.tools.common_tools.financial_tools import YFinanceTools

# Create financial tools
finance_tools = YFinanceTools(
    stock_price=True,
    analyst_recommendations=True,
    company_news=True
)

# Create agent with thinking for multi-step analysis
agent = Agent(
    model="openai/gpt-4o",
    name="FinancialAnalyst",
    tools=finance_tools.functions(),
    enable_thinking_tool=True,
    debug=True
)

# Task requiring multiple tool calls
task = Task(
    description="""
    Analyze Apple (AAPL) stock:
    1. Get the current stock price
    2. Fetch analyst recommendations
    3. Get recent company news
    4. Provide a comprehensive investment summary
    """
)

# Agent will plan and execute: get_current_stock_price, get_analyst_recommendations, get_company_news
# Then synthesize results into investment summary
result = agent.do(task)
print(result)

​
Example: Multi-City Research

from upsonic import Agent, Task
from upsonic.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: Sunny, 25°C"

@tool
def get_population(city: str) -> str:
    """Get population statistics for a city."""
    return f"Population of {city}: 2.1 million"

@tool
def get_attractions(city: str) -> str:
    """Get top attractions in a city."""
    return f"Top attractions in {city}: Museums, Parks, Historic sites"

agent = Agent(
    model="openai/gpt-4o",
    name="TravelAdvisor",
    tools=[get_weather, get_population, get_attractions],
    enable_thinking_tool=True,
    debug=True
)

task = Task(
    description="Give me a complete travel briefing for Paris including weather, population, and attractions",
    enable_thinking_tool=True
)

# Agent creates plan: [get_weather, get_population, get_attractions]
# Executes each tool, then synthesizes into travel briefing
result = agent.do(task)
print(result)

​
Thinking Output Structure

When thinking is enabled, the agent provides:
  1. Reasoning: Detailed strategy for approaching the task
  2. Execution Plan: Step-by-step tool call sequence
  3. Criticism: Self-assessment identifying potential issues
  4. Final Synthesis: Comprehensive answer combining all tool results

​
Performance Considerations

Important: Thinking capabilities consume more tokens and processing time than basic mode due to the planning and synthesis steps. Use thinking when the orchestration value outweighs the cost. 
from upsonic import Agent, Task
from upsonic.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: Sunny, 25\u00b0C"

@tool
def get_population(city: str) -> str:
    """Get population for a city."""
    return f"Population of {city}: 2.1 million"

# Monitor performance with debug mode
agent = Agent(
    model="openai/gpt-4o",
    name="Analyst",
    tools=[get_weather, get_population],
    enable_thinking_tool=True,
    debug=True  # Shows detailed execution metrics
)

# Run task to see performance metrics
task = Task("Compare the weather and populations of London and Paris")
result = agent.do(task)
print(result)

​
Best Practices

  1. Use for Multi-Tool Tasks: Enable thinking when you have 2+ tools that need coordination
  2. Disable for Simple Queries: Use basic mode for single-tool or no-tool tasks
  3. Provide Clear Instructions: Help the agent plan by being specific about what you need
  4. Include Multiple Tools: Thinking shines when there are tools to orchestrate
  5. Monitor with Debug Mode: Use debug=True to understand the planning process
Thinking provides a powerful way to handle complex scenarios that require multiple tools working together, making it essential for sophisticated multi-step analysis and research tasks.