Basic Agent Example

To build effective agents, start simple — just a model, tools, and instructions. Once that works, layer in more functionality as needed. It’s also best to begin with well-defined tasks like report generation, data extraction, classification, summarization, knowledge search, and document processing. These early wins help you identify what works, validate user needs, and set the stage for advanced systems. Here’s the simplest possible report generation agent:

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

@tool
def search_web(query: str) -> str:
    """Search the web for information about a topic."""
    # Simulated web search - replace with actual implementation
    return f"Search results for '{query}': Found relevant information about the topic."

agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    instructions="Write a report on the topic. Output only the report.",
    tools=[search_web]  # Tools can be added during initialization
)

task = Task(description="Trending startups and products.")
agent.print_do(task)

Setting a System Prompt

You can customize your agent’s behavior by providing a system_prompt or instructions parameter. The system_prompt gives you full control over the system message sent to the model, while instructions provides high-level guidance that gets incorporated into the agent’s default prompt.

Using instructions (Recommended for most cases)

The instructions parameter is the simplest way to guide your agent’s behavior:

from upsonic import Agent

agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    instructions="You are a helpful assistant that specializes in Python programming. Be concise and provide code examples when relevant."
)

Using system_prompt (Full control)

For complete control over the system message, use system_prompt:

from upsonic import Agent

agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    system_prompt="""You are an expert financial analyst. 
Your responses should:
- Be data-driven and analytical
- Include relevant metrics when available
- Maintain a professional tone
- Cite sources when making claims"""
)

Combining with Agent Identity

You can also define your agent’s identity using role, goal, and other attributes:

from upsonic import Agent

agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    name="DataBot",
    role="Data Analyst",
    goal="Help users understand and visualize their data",
    instructions="Always ask clarifying questions before analyzing data. Provide visualizations when possible.",
    education="PhD in Statistics",
    work_experience="10 years of experience in data science and analytics"
)

Run your Agent

When running your agent, use the Agent.print_do() method to print the response in the terminal. This is only for development purposes and not recommended for production use. In production, use the Agent.do() or Agent.do_async() methods. For example:

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

@tool
def search_web(query: str) -> str:
    """Search the web for information about a topic."""
    # Simulated web search - replace with actual implementation
    return f"Search results for '{query}': Found relevant information about the topic."


async def main():

    agent = Agent(
        model="anthropic/claude-sonnet-4-5",
        instructions="Write a report on the topic. Output only the report.",
        tools=[search_web]  # Tools can be added during initialization
    )

    # You can also add tools after initialization
    # agent.add_tools([another_tool])

    # do() and do_async() methods accept both Task objects and strings
    task = Task(description="Trending startups and products.")
    #result = agent.do(task)
    # Or: result = agent.do("Trending startups and products.")

    # Print the response
    #print(result)

    ################ STREAM RESPONSE #################
    async for text_chunk in agent.astream(task):
        print(text_chunk, end='', flush=True)
    print()  # New line after streaming

if __name__ == "__main__":
    asyncio.run(main())

Next, continue building your agent by adding functionality as needed. Common questions:

How do I run my agent? -> See the running agents documentation.
How do I manage sessions? -> See the memory documentation.
How do I manage input and capture output? -> See the running agents documentation.
How do I add tools? -> See the tools documentation.
How do I give the agent context? -> See the agent attributes documentation.
How do I add knowledge? -> See the knowledge base documentation.
How do I handle images, audio, video, and files? -> See the OCR documentation.
How do I add guardrails? -> See the safety engine documentation.
How do I cache model responses during development? -> See the task attributes documentation for cache configuration.

Developer Resources

View the Agent reference
View the Agent overview

GET STARTED

CONCEPTS

STARTING AN AGENT PROJECT

READY TO USE SNIPPETS

DEPLOYMENT

FURTHER READINGS

Setting a System Prompt

Using instructions (Recommended for most cases)

Using system_prompt (Full control)

Combining with Agent Identity

Run your Agent

Developer Resources

​Setting a System Prompt

​Using instructions (Recommended for most cases)

​Using system_prompt (Full control)

​Combining with Agent Identity

​Run your Agent

​Developer Resources

Setting a System Prompt

Using instructions (Recommended for most cases)

Using system_prompt (Full control)

Combining with Agent Identity

Run your Agent

Developer Resources