Skip to main content
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.