Skip to main content
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="openai/gpt-4o",
    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)

​
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

@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="openai/gpt-4o",
    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 with agent.stream(task) as result:
    async for text_chunk in result.stream_output():
        print(text_chunk, end='', flush=True)
    print()  # New line after streaming
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