Adding Thinking - Upsonic AI

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="anthropic/claude-sonnet-4-5",
    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:

Strategic Planning: The agent creates a complete, sequential plan of tool calls
Orchestrated Execution: Tools are executed step-by-step according to the plan
Final Synthesis: Results from all tools are combined into a comprehensive answer

Example Flow:
Agent receives: "Tell me about Paris's weather and population"
Agent creates plan: [get_weather("Paris"), get_population("Paris")]
Orchestrator executes: get_weather → get_population
Agent synthesizes: "Paris has sunny weather at 25°C and 2.1 million residents"

Thinking vs. Basic Mode

Feature	Basic Mode	Thinking Mode
Planning	Ad-hoc tool calls	Structured blueprint creation
Execution	Direct tool execution	Orchestrated step-by-step execution
Best For	Single tool tasks	Multi-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="anthropic/claude-sonnet-4-5",
    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="anthropic/claude-sonnet-4-5",
    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="anthropic/claude-sonnet-4-5",
    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="anthropic/claude-sonnet-4-5",
    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="anthropic/claude-sonnet-4-5",
    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:

Reasoning: Detailed strategy for approaching the task
Execution Plan: Step-by-step tool call sequence
Criticism: Self-assessment identifying potential issues
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="anthropic/claude-sonnet-4-5",
    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

Use for Multi-Tool Tasks: Enable thinking when you have 2+ tools that need coordination
Disable for Simple Queries: Use basic mode for single-tool or no-tool tasks
Provide Clear Instructions: Help the agent plan by being specific about what you need
Include Multiple Tools: Thinking shines when there are tools to orchestrate
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.

​Why Use Thinking?

​Enabling Thinking

​How Thinking Works

​Thinking vs. Basic Mode

​Thinking Configuration

​Agent-Level Thinking

​Task-Level Thinking

​Mixed Configuration

​When to Use Thinking

​Example: Financial Analysis with Multiple Tools

​Example: Multi-City Research

​Thinking Output Structure

​Performance Considerations

​Best Practices