> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic Agent Example

> Learn how to build Agents with Upsonic

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:

```python theme={null}
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:

```python theme={null}
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`:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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](/concepts/agents/running-agents) documentation.

* **How do I manage sessions?** -> See the [memory](/concepts/memory/overview) documentation.

* **How do I manage input and capture output?** -> See the [running agents](/concepts/agents/running-agents) documentation.

* **How do I add tools?** -> See the [tools](/concepts/tools/overview) documentation.

* **How do I give the agent context?** -> See the [agent attributes](/concepts/agents/attributes) documentation.

* **How do I add knowledge?** -> See the [knowledge base](/concepts/knowledge-base) documentation.

* **How do I handle images, audio, video, and files?** -> See the [OCR](/concepts/ocr/overview) documentation.

* **How do I add guardrails?** -> See the [safety engine](/concepts/safety-engine/overview) documentation.

* **How do I cache model responses during development?** -> See the [task attributes](/concepts/tasks/attributes) documentation for cache configuration.

## Developer Resources

* View the [Agent reference](/reference/agent/agent)

* View the [Agent overview](/concepts/agents/overview)