Agent - Upsonic AI

The Agent class is the core agent implementation in Upsonic, providing a powerful and flexible interface for creating AI agents with advanced capabilities including memory management, safety policies, reliability layers, and sophisticated tool integration.

Creating an Agent
Agent Attributes
Adding a Memory
Adding Thinking
Adding Reasoning

Creating an Agent

The Agent can be created with minimal configuration or with extensive customization to suit your specific needs. The agent provides a robust foundation for AI-powered applications with built-in support for various advanced features.

Basic Agent Creation

The simplest way to create an agent is with default settings:

from upsonic import Agent

# Create agent with default settings
agent = Agent()

Warning: When creating an agent without specifying a model, it defaults to "openai/gpt-4o". Make sure you have the appropriate API key set in your environment.

Agent with Custom Configuration

For more control over your agent’s behavior, you can specify various parameters:

from upsonic import Agent

# Create agent with custom settings for financial analysis
agent = Agent(
    name="FinancialAnalyst",
    model="openai/gpt-4o-mini",
    debug=True,
    retry=3,
    mode="raise"
)

Agent with Company Information

You can provide company context to help the agent understand your organization:

agent = Agent(
    name="BankingAgent",
    company_url="https://fintechbank.com",
    company_objective="To provide secure, innovative financial services",
    company_description="A leading digital bank specializing in AI-powered financial solutions and personalized banking experiences"
)

Agent Attributes

The Agent exposes numerous attributes that control its behavior and capabilities. Understanding these attributes is crucial for effective agent configuration.

Core Identity Attributes

Attribute	Type	Default	Description
`name`	`str \| None`	`None`	Human-readable name for the agent
`agent_id_`	`str \| None`	`None`	Unique identifier for the agent instance

Example:

agent = Agent(
    name="CreditRiskAnalyst",
    agent_id_="risk_analyst_001"
)
print(f"Agent: {agent.name}, ID: {agent.agent_id}")

Model and Performance Attributes

Attribute	Type	Default	Description
`model`	`Union[str, Model]`	`"openai/gpt-4o"`	Model specification (string or Model instance)
`retry`	`int`	`1`	Number of retry attempts for failed calls
`mode`	`RetryMode`	`"raise"`	Retry behavior: “raise” or “return_false”
`debug`	`bool`	`False`	Enable debug mode for detailed logging

Example:

agent = Agent(
    model="openai/gpt-4o-mini",
    retry=5,
    mode="raise",
    debug=True
)

Company Context Attributes

Attribute	Type	Default	Description
`company_url`	`str \| None`	`None`	Company website URL
`company_objective`	`str \| None`	`None`	Company’s main objective
`company_description`	`str \| None`	`None`	Detailed company description

Example:

agent = Agent(
    company_url="https://securebank.com",
    company_objective="Revolutionizing digital banking with AI",
    company_description="Leading provider of AI-powered financial services for retail and commercial clients"
)

Role and Professional Attributes

Attribute	Type	Default	Description
`role`	`str \| None`	`None`	Professional role of the agent
`goal`	`str \| None`	`None`	Primary goal or objective
`instructions`	`str \| None`	`None`	Specific instructions for behavior
`education`	`str \| None`	`None`	Educational background
`work_experience`	`str \| None`	`None`	Professional experience

Example:

agent = Agent(
    role="Senior Financial Risk Analyst",
    goal="To provide accurate risk assessments and regulatory compliance analysis",
    instructions="Always follow banking regulations and provide detailed risk documentation",
    education="Finance and Risk Management Degree",
    work_experience="8 years in banking and financial risk analysis"
)

System and Context Attributes

Attribute	Type	Default	Description
`system_prompt`	`str \| None`	`None`	Custom system prompt for the agent
`reflection`	`bool`	`False`	Reflection capabilities
`compress_context`	`bool`	`False`	Enable context compression

Example:

agent = Agent(
    system_prompt="You are a financial AI assistant specialized in banking operations and regulatory compliance. Always provide accurate, well-documented financial analysis and ensure compliance with banking regulations.",
    compress_context=True
)

Tool and Execution Attributes

Attribute	Type	Default	Description
`show_tool_calls`	`bool`	`True`	Display tool call information
`tool_call_limit`	`int`	`5`	Maximum number of tool calls per execution
`tool_call_count`	`int`	`0`	Current tool call count (read-only)
`enable_thinking_tool`	`bool`	`False`	Enable thinking/reasoning capabilities
`enable_reasoning_tool`	`bool`	`False`	Enable advanced reasoning (requires thinking)

Example:

agent = Agent(
    show_tool_calls=True,
    tool_call_limit=10,
    enable_thinking_tool=True,
    enable_reasoning_tool=True
)

Warning: enable_reasoning_tool requires enable_thinking_tool to be True. Setting reasoning without thinking will raise a ValueError.

Memory and Storage Attributes

Attribute	Type	Default	Description
`memory`	`Memory \| None`	`None`	Memory management system
`feed_tool_call_results`	`bool`	`False`	Include tool results in memory

Example:

from upsonic import Memory
from upsonic.storage.providers.sqlite import SqliteStorage

storage = SqliteStorage("sessions", "profiles", "agent_memory.db")
memory = Memory(
    storage=storage,
    session_id="my_session",
    full_session_memory=True,
    summary_memory=True
)

agent = Agent(
    memory=memory,
    feed_tool_call_results=True
)

Safety and Reliability Attributes

Attribute	Type	Default	Description
`user_policy`	`Policy \| None`	`None`	Safety policy for user input validation
`agent_policy`	`Policy \| None`	`None`	Safety policy for agent output validation
`reliability_layer`	`Any \| None`	`None`	Reliability and validation layer

Example:

from upsonic.safety_engine.policies.crypto_policies import CryptoBlockPolicy
from upsonic.safety_engine.policies.phone_policies import AnonymizePhoneNumbersPolicy

agent = Agent(
    user_policy=CryptoBlockPolicy,
    agent_policy=AnonymizePhoneNumbersPolicy
)

Canvas and External Integration Attributes

Attribute	Type	Default	Description
`canvas`	`Canvas \| None`	`None`	Canvas for persistent text storage

Example:

from upsonic.canvas.canvas import Canvas

canvas = Canvas("my_canvas")
agent = Agent(canvas=canvas)

Adding a Memory

Memory capabilities allow your agent to maintain context across conversations, learn from interactions, and provide personalized responses. The memory system supports multiple storage backends and various memory types.

Memory System Overview

The memory system in Upsonic provides three main types of memory:

Full Session Memory: Stores complete conversation history
Summary Memory: Maintains condensed summaries of conversations
User Analysis Memory: Builds user profiles and preferences

Setting Up Memory with SQLite

from upsonic import Agent
from upsonic.storage.memory.memory import Memory
from upsonic.storage.providers.sqlite import SqliteStorage
from upsonic.models.openai import OpenAIChatModel

# Create storage backend
storage = SqliteStorage(
    sessions_table_name="sessions",
    profiles_table_name="profiles", 
    db_file="agent_memory.db"
)

# Create memory system
memory = Memory(
    storage=storage,
    session_id="user_session_001",
    user_id="user_123",
    full_session_memory=True,
    summary_memory=True,
    user_analysis_memory=True,
    model=OpenAIChatModel("gpt-4o-mini"),
    debug=True
)

# Create agent with memory for customer relationship management
agent = Agent(
    name="CustomerServiceAgent",
    memory=memory,
    feed_tool_call_results=True
)

Memory Configuration Options

Parameter	Type	Default	Description
`storage`	`Storage`	Required	Storage backend (SQLite, PostgreSQL, MongoDB, etc.)
`session_id`	`str \| None`	`None`	Unique session identifier
`user_id`	`str \| None`	`None`	User identifier for profile building
`full_session_memory`	`bool`	`False`	Enable complete conversation storage
`summary_memory`	`bool`	`False`	Enable conversation summarization
`user_analysis_memory`	`bool`	`False`	Enable user profile analysis
`num_last_messages`	`int \| None`	`None`	Limit conversation history to last N messages
`user_memory_mode`	`Literal['update', 'replace']`	`'update'`	How to update user profiles

Example with Custom Memory Settings:

memory = Memory(
    storage=storage,
    session_id="conversation_001",
    user_id="user_456",
    full_session_memory=True,
    summary_memory=True,
    user_analysis_memory=True,
    num_last_messages=10,  # Keep only last 10 conversation turns
    user_memory_mode='update',  # Update existing profile data
    model=OpenAIChatModel("gpt-4o-mini")
)

Using Memory in Task Execution

When memory is enabled, the agent automatically:

Retrieves relevant context from previous conversations
Updates user profiles based on interactions
Maintains conversation summaries for long-term context
Feeds tool call results into memory (if enabled)

from upsonic import Task

# Create a task - memory will be automatically used for customer context
task = Task(description="What were the customer's previous concerns about their mortgage application?")

# Execute with memory context
result = agent.print_do(task)

Memory Management Methods

The agent provides methods to manage memory:

# Get cache statistics
cache_stats = agent.get_cache_stats()
print(f"Cache hits: {cache_stats['cache_hits']}")
print(f"Cache misses: {cache_stats['cache_misses']}")
print(f"Hit rate: {cache_stats['hit_rate']}")

# Clear agent's cache
agent.clear_cache()

Adding Thinking Tool

Thinking Tool capabilities enable the agent to think through problems step-by-step, analyze its own reasoning, and provide more thoughtful responses. This is particularly useful for complex problem-solving tasks.

Enabling Thinking Tool

Thinking Tool is controlled by the enable_thinking_tool parameter:

from upsonic import Agent, Task

# Create agent with thinking capabilities for financial analysis
agent = Agent(
    name="FinancialAnalyst",
    enable_thinking_tool=True,
    debug=True
)

# Create a task that benefits from thinking tool
task = Task(
    description="Analyze this step by step: A customer wants to invest $10,000 with a 5% annual return. Calculate the compound interest over 10 years and provide investment recommendations.",
    enable_thinking_tool=True
)

# Execute with thinking tool
result = agent.print_do(task)

How Thinking Tool Works

When Thinking Tool is enabled, the agent:

Analyzes the problem before attempting to solve it
Breaks down complex tasks into manageable steps
Evaluates its own reasoning and adjusts if needed
Provides detailed explanations of its thought process

Example Output with Thinking Tool:

The agent will show its thinking process:
- Financial problem analysis
- Step-by-step calculation methodology
- Risk assessment evaluation
- Investment recommendation with justification

Thinking Tool Configuration

You can control Thinking Tool at both the agent and task level:

# Agent-level Thinking Tool (applies to all tasks)
agent = Agent(enable_thinking_tool=True)

# Task-level Thinking Tool (overrides agent setting)
task = Task(
    description="Complex loan risk assessment with multiple variables",
    enable_thinking_tool=True  # Force Thinking Tool for this task
)

# Task-level Thinking Tool (disable for specific task)
task = Task(
    description="Simple account balance inquiry",
    enable_thinking_tool=False  # Disable Thinking Tool for this task
)

Thinking Tool Use Cases

Thinking Tool is particularly valuable for:

Financial calculations and modeling
Risk assessment and compliance analysis
Multi-step loan processing workflows
Regulatory compliance verification
Investment strategy planning

Example:

task = Task(
    description="""
    You need to plan a digital banking transformation project with the following requirements:
    1. Implement mobile banking application
    2. Integrate with 3 payment processing APIs
    3. Implement multi-factor authentication and fraud detection
    4. Deploy to secure cloud infrastructure with compliance monitoring
    
    Create a detailed project plan with timelines, dependencies, and regulatory compliance checkpoints.
    """,
    enable_thinking_tool=True
)

Adding Reasoning

Reasoning capabilities build upon Thinking Tool to provide even more sophisticated problem-solving abilities. Reasoning enables the agent to use advanced logical analysis and structured thinking approaches.

Enabling Reasoning

Reasoning requires both enable_thinking_tool and enable_reasoning_tool to be True:

from upsonic import Agent, Task

# Create agent with reasoning capabilities for financial analysis
agent = Agent(
    name="RiskAssessmentAgent",
    enable_thinking_tool=True,      # Required for reasoning
    enable_reasoning_tool=True,     # Enables advanced reasoning
    debug=True
)

# Create a complex reasoning task
task = Task(
    description="""
    Analyze the following banking scenario and provide a comprehensive risk assessment:
    
    A regional bank has $1B in assets across 3 business lines. Commercial lending has 40% of assets,
    retail banking has 35%, and wealth management has 25%. The bank wants to implement
    new risk management policies that affect each business line differently. Commercial lending
    will see a 20% reduction in default risk, retail banking will see a 15% reduction, and wealth
    management will see a 10% reduction. Calculate the overall risk impact and provide
    recommendations for implementation and regulatory compliance.
    """,
    enable_thinking_tool=True,
    enable_reasoning_tool=True
)

# Execute with advanced reasoning
result = agent.print_do(task)

Warning: enable_reasoning_tool cannot be True if enable_thinking_tool is False. This will raise a ValueError.

Reasoning vs. Thinking Tool

Feature	Thinking Tool (`enable_thinking_tool`)	Reasoning (`enable_reasoning_tool`)
Purpose	Basic step-by-step financial analysis	Advanced risk and compliance analysis
Complexity	Simple to moderate financial problems	Complex, multi-faceted banking scenarios
Output	Clear financial explanations	Structured analysis with regulatory recommendations
Use Cases	Interest calculations, basic risk assessment	Strategic banking planning, complex compliance analysis

Reasoning Configuration

Reasoning can be configured at multiple levels:

# Agent-level reasoning (applies to all tasks)
agent = Agent(
    enable_thinking_tool=True,
    enable_reasoning_tool=True
)

# Task-level reasoning (overrides agent settings)
task = Task(
    description="Complex credit risk analysis with multiple variables",
    enable_thinking_tool=True,
    enable_reasoning_tool=True
)

# Mixed configuration (reasoning disabled for specific task)
task = Task(
    description="Simple account balance inquiry",
    enable_thinking_tool=True,   # Keep thinking
    enable_reasoning_tool=False  # Disable reasoning
)

Advanced Reasoning Use Cases

Reasoning is ideal for:

Strategic banking and fintech analysis
Complex financial data interpretation
Multi-variable risk assessment
Regulatory compliance and risk mitigation
Portfolio optimization and investment strategies

Example:

task = Task(
    description="""
    You are a financial risk analyst. Analyze the following banking market data and provide
    strategic recommendations:
    
    Banking Market Data:
    - Current digital banking market size: $50B
    - Growth rate: 15% annually
    - Competitor analysis: 3 major digital banks
    - Customer segments: Retail (60%), Commercial (40%)
    - Technology trends: AI/ML adoption increasing 25% yearly in fintech
    
    Provide:
    1. Market opportunity assessment for digital banking
    2. Competitive positioning strategy for fintech services
    3. Technology investment recommendations for AI/ML
    4. Risk analysis and regulatory compliance mitigation
    """,
    enable_thinking_tool=True,
    enable_reasoning_tool=True
)

Reasoning Output Structure

When reasoning is enabled, the agent provides:

Financial Problem Decomposition: Breaking complex banking scenarios into components
Risk Analysis: Step-by-step risk assessment and logical reasoning
Regulatory Evidence Evaluation: Assessing compliance requirements and financial data
Financial Synthesis: Combining insights into coherent banking recommendations
Actionable Recommendations: Specific next steps for implementation and compliance

Performance Considerations

Warning: Reasoning capabilities consume more tokens and processing time than basic Thinking Tool. Monitor your usage and costs when using reasoning for production applications.

# Monitor performance with debug mode
agent = Agent(
    enable_thinking_tool=True,
    enable_reasoning_tool=True,
    debug=True  # Shows detailed execution metrics
)

Complete Example: Advanced Agent Configuration

Here’s a comprehensive example showing how to create a fully-featured agent with all capabilities:

import os
from upsonic import Agent, Task, Memory
from upsonic.storage.providers.sqlite import SqliteStorage
from upsonic.models.openai import OpenAIChatModel
from upsonic.safety_engine.policies.crypto_policies import CryptoBlockPolicy
from upsonic.safety_engine.policies.phone_policies import AnonymizePhoneNumbersPolicy
from upsonic.reliability_layer.reliability_layer import ReliabilityProcessor

# Set API key
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# Create storage and memory
storage = SqliteStorage("sessions", "profiles", "advanced_agent.db")
memory = Memory(
    storage=storage,
    session_id="advanced_session",
    user_id="user_001",
    full_session_memory=True,
    summary_memory=True,
    user_analysis_memory=True,
    model=OpenAIChatModel("gpt-4o-mini")
)

# Create reliability layer
reliability_layer = ReliabilityProcessor(confidence_threshold=0.8)

# Create fully-featured banking agent
agent = Agent(
    # Identity
    name="BankingRiskAnalyst",
    agent_id_="banking_analyst_001",
    
    # Model and performance
    model="openai/gpt-4o-mini",
    retry=3,
    mode="raise",
    debug=True,
    
    # Company context
    company_url="https://securebank.com",
    company_objective="Providing secure, AI-powered financial services",
    company_description="Leading digital bank with advanced risk management",
    
    # Professional context
    role="Senior Financial Risk Analyst",
    goal="To provide accurate risk assessments and regulatory compliance analysis",
    instructions="Always follow banking regulations and provide detailed risk documentation",
    education="Finance and Risk Management PhD",
    work_experience="10 years in banking and financial risk analysis",
    
    # System configuration
    system_prompt="You are an expert financial AI assistant with advanced risk assessment and regulatory compliance capabilities.",
    
    # Memory and storage
    memory=memory,
    feed_tool_call_results=True,
    
    # Safety and reliability
    user_policy=CryptoBlockPolicy,
    agent_policy=AnonymizePhoneNumbersPolicy,
    reliability_layer=reliability_layer,
    
    # Tool configuration
    show_tool_calls=True,
    tool_call_limit=10,
    enable_thinking_tool=True,
    enable_reasoning_tool=True
)

# Create and execute a complex banking task
task = Task(
    description="""
    Analyze the following banking scenario and provide strategic risk management recommendations:
    
    A regional bank has $100M in capital and needs to decide between:
    1. Expanding digital banking services to new markets
    2. Developing AI-powered fraud detection systems
    3. Acquiring a smaller fintech startup
    
    Consider regulatory requirements, market conditions, competition, and risk exposure.
    """,
    enable_thinking_tool=True,
    enable_reasoning_tool=True,
    enable_cache=True,
    cache_method="vector_search",
    cache_threshold=0.8
)

# Execute the task
result = agent.print_do(task)

# Check memory and cache statistics
print(f"Cache stats: {agent.get_cache_stats()}")

This comprehensive configuration demonstrates how to leverage all the major features of the Agent for sophisticated banking and fintech applications.

Best Practices

Start Simple: Begin with basic configuration and add features as needed for your banking use case
Monitor Performance: Use debug mode to understand token usage and costs in financial applications
Memory Management: Choose appropriate memory settings for customer relationship management and compliance tracking
Safety First: Always implement appropriate safety policies for financial data and regulatory compliance
Error Handling: Configure retry settings based on your reliability requirements for critical banking operations
Resource Management: Be mindful of token consumption with reasoning capabilities in risk assessment scenarios
Regulatory Compliance: Ensure all AI outputs meet banking regulations and compliance requirements
Data Security: Implement proper data encryption and access controls for sensitive financial information

The Agent provides a powerful foundation for building sophisticated banking and fintech applications with enterprise-grade features, regulatory compliance, and advanced risk management capabilities.

​Table of Contents

​Creating an Agent

​Basic Agent Creation

​Agent with Custom Configuration

​Agent with Company Information

​Agent Attributes

​Core Identity Attributes

​Model and Performance Attributes

​Company Context Attributes

​Role and Professional Attributes

​System and Context Attributes

​Tool and Execution Attributes

​Memory and Storage Attributes

​Safety and Reliability Attributes

​Canvas and External Integration Attributes

​Adding a Memory

​Memory System Overview

​Setting Up Memory with SQLite

​Memory Configuration Options

​Using Memory in Task Execution

​Memory Management Methods

​Adding Thinking Tool

​Enabling Thinking Tool

​How Thinking Tool Works

​Thinking Tool Configuration

​Thinking Tool Use Cases

​Adding Reasoning

​Enabling Reasoning

​Reasoning vs. Thinking Tool

​Reasoning Configuration

​Advanced Reasoning Use Cases

​Reasoning Output Structure

​Performance Considerations

​Complete Example: Advanced Agent Configuration

​Best Practices

Table of Contents

Creating an Agent

Basic Agent Creation

Agent with Custom Configuration

Agent with Company Information

Agent Attributes

Core Identity Attributes

Model and Performance Attributes

Company Context Attributes

Role and Professional Attributes

System and Context Attributes

Tool and Execution Attributes

Memory and Storage Attributes

Safety and Reliability Attributes

Canvas and External Integration Attributes

Adding a Memory

Memory System Overview

Setting Up Memory with SQLite

Memory Configuration Options

Using Memory in Task Execution

Memory Management Methods

Adding Thinking Tool

Enabling Thinking Tool

How Thinking Tool Works

Thinking Tool Configuration

Thinking Tool Use Cases

Adding Reasoning

Enabling Reasoning

Reasoning vs. Thinking Tool

Reasoning Configuration

Advanced Reasoning Use Cases

Reasoning Output Structure

Performance Considerations

Complete Example: Advanced Agent Configuration

Best Practices