This guide will walk you through:
  • Creating a minimal FastAPI app with a Upsonic agent
  • Containerizing it with Docker
  • Running it locally

​
Setup

1

Create a new directory for your project

Create a new directory for your project and navigate to it:
mkdir my-upsonic-project
cd my-upsonic-project
After following this guide, your project structure will look like this:
my-upsonic-project/
├── main.py
├── Dockerfile
├── requirements.txt
2

Create a `requirements.txt` file and add the required dependencies:

requirements.txt
fastapi
upsonic
uvicorn

​
Step 1: Create a FastAPI App with a Upsonic Agent

1

Create a new Python file, e.g., `main.py`, and add the following code to create a minimal FastAPI app with a Upsonic agent:

main.py
from fastapi import FastAPI
from upsonic import Agent, Task
from upsonic.tools import Search

app = FastAPI()

# Create an agent with a specific role
agent = Agent(
    name="Customer Support",
    company_url="https://your-company.com",
    company_objective="To provide excellent customer service and support",
)

@app.get("/ask")
async def ask(query: str):
    # Create a task with the user's query
    task = Task(query, tools=[Search])
    
    # Run the task with the agent
    response = agent.do(task)
    
    return {"response": response}
2

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
3

Install the required dependencies by running:

pip install -r requirements.txt
4

Set your OPENAI_API_KEY environment variable:

export OPENAI_API_KEY=your_api_key  # On Windows: set OPENAI_API_KEY=your_api_key
5

Run the FastAPI app with `uvicorn main:app --reload`.

uvicorn main:app --reload

​
Step 2: Create a Dockerfile

1

In the same directory, create a new file named `Dockerfile` with the following content:

Dockerfile
FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
2

Build the Docker image by running:

docker build -t my-upsonic-app .
3

Run the Docker container with:

docker run -p 8000:8000 -e OPENAI_API_KEY=your_api_key my-upsonic-app
4

Access your app

You can now access the FastAPI app at http://localhost:8000.

​
Step 3: Advanced Configuration with Structured Responses

1

Enhance your `main.py` file to include structured responses using Pydantic models:

main.py
from fastapi import FastAPI
from upsonic import Agent, Task
from upsonic.tools import Search
from pydantic import BaseModel
from typing import List

app = FastAPI()

# Define a structured response model
class TravelRecommendation(BaseModel):
    destination: str
    attractions: List[str]
    best_time_to_visit: str
    estimated_budget: str

# Create an agent with a specific role
agent = Agent(
    name="Travel Advisor",
    company_url="https://your-travel-company.com",
    company_objective="To provide personalized travel recommendations and advice",
)

@app.get("/travel-recommendation")
async def get_travel_recommendation(destination_type: str, budget: str, duration: str):
    # Create a task with structured response format
    task = Task(
        f"Recommend a travel destination for a {duration} trip with {destination_type} experience and {budget} budget",
        tools=[Search],
        response_format=TravelRecommendation
    )
    
    # Run the task with the agent
    response = agent.do(task)
    
    return response

@app.get("/ask")
async def ask(query: str):
    # Create a general purpose task
    task = Task(
        query, 
        tools=[Search]
    )
    
    # Run the task with the agent
    response = agent.do(task)
    
    return {"response": response}
2

Run the updated Docker container:

docker build -t my-upsonic-app .
docker run -p 8000:8000 -e OPENAI_API_KEY=your_api_key my-upsonic-app
Now your API provides both a general-purpose query endpoint and a specialized endpoint that returns structured travel recommendations.You can test the structured response endpoint with:
curl "http://localhost:8000/travel-recommendation?destination_type=beach&budget=medium&duration=7%20days"
This will return a JSON object with structured travel recommendation information.