Deploy via Django - Upsonic AI

This guide shows how to run a Upsonic agent inside a Django project. Choose Django when you need database models, user management, or admin UI alongside your agent API.

Prerequisites

Django 4.1+ (for async view support if you use agent.do_async())
A Django project already created, or follow the steps below to create one

Setup

Initialize the project with uv

mkdir my-django-agent && cd my-django-agent
uv init
uv add django upsonic anthropic

Create a Django project and app

uv run django-admin startproject myproject .
uv run python manage.py startapp agent_api

Add "agent_api" to INSTALLED_APPS in myproject/settings.py.

Configure URLs

In myproject/urls.py, include the app URLs:

myproject/urls.py

from django.urls import path, include

urlpatterns = [
    path("api/", include("agent_api.urls")),
]

Create the agent view and URL

In agent_api/views.py:

agent_api/views.py

from django.http import JsonResponse, HttpRequest
from django.views.decorators.http import require_GET
from upsonic import Agent, Task
from upsonic.tools import WebSearch

agent = Agent(
    "anthropic/claude-sonnet-4-6",
    name="Support Agent",
    company_url="https://your-company.com",
    company_objective="To assist users with their questions",
)

@require_GET
def ask(request: HttpRequest) -> JsonResponse:
    query: str = request.GET.get("query", "")
    if not query:
        return JsonResponse({"error": "Missing query"}, status=400)
    task = Task(query, tools=[WebSearch])
    response = agent.do(task)
    return JsonResponse({"response": response})

In agent_api/urls.py (create the file):

agent_api/urls.py

from django.urls import path
from . import views

urlpatterns = [
    path("ask/", views.ask),
]

Run the server

export ANTHROPIC_API_KEY=your_api_key
uv run python manage.py runserver

Call the agent: http://localhost:8000/api/ask/?query=Hello

Step 2: Docker

Create a `.dockerignore` file

.dockerignore

.venv
__pycache__
db.sqlite3

Create a `Dockerfile`

Dockerfile

FROM python:3.12-slim

WORKDIR /app

COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

COPY . .

CMD ["uv", "run", "python", "manage.py", "runserver", "0.0.0.0:8000"]

Build and run the image

docker build -t my-django-agent .
docker run -p 8000:8000 -e ANTHROPIC_API_KEY=your_api_key my-django-agent

Access the app

Call the agent: http://localhost:8000/api/ask/?query=Hello

For production, replace manage.py runserver with Gunicorn:

CMD ["uv", "run", "gunicorn", "myproject.wsgi:application", "--bind", "0.0.0.0:8000"]

Add Gunicorn as a dependency: uv add gunicorn.

Async view with `agent.do_async()`

Django 4.1+ supports async views. Use agent.do_async() so the worker is not blocked during LLM calls.

agent_api/views.py

from django.http import JsonResponse, HttpRequest
from django.views.decorators.http import require_GET
from upsonic import Agent, Task
from upsonic.tools import WebSearch

agent = Agent(
    "anthropic/claude-sonnet-4-6",
    name="Support Agent",
    company_url="https://your-company.com",
    company_objective="To assist users with their questions",
)

@require_GET
async def ask_async(request: HttpRequest) -> JsonResponse:
    query: str = request.GET.get("query", "")
    if not query:
        return JsonResponse({"error": "Missing query"}, status=400)
    task = Task(query, tools=[WebSearch])
    response = await agent.do_async(task)
    return JsonResponse({"response": response})

urlpatterns = [
    path("ask/", views.ask),
    path("ask-async/", views.ask_async),
]

When using async views, run Django with an ASGI server (e.g. uvicorn or daphne). With runserver, Django runs in a single thread and async may not scale. For production use:

uv add uvicorn
uv run uvicorn myproject.asgi:application --host 0.0.0.0 --port 8000

Using with Django auth and DB

You can use the request user and DB in the same view before or after calling the agent.

agent_api/views.py

from django.contrib.auth.decorators import login_required
from django.http import JsonResponse, HttpRequest
from django.views.decorators.http import require_GET
from upsonic import Agent, Task

agent = Agent(
    "anthropic/claude-sonnet-4-6",
    name="Support Agent",
    company_url="https://your-company.com",
    company_objective="To assist users with their questions",
)

@require_GET
@login_required
def ask(request: HttpRequest) -> JsonResponse:
    query: str = request.GET.get("query", "")
    if not query:
        return JsonResponse({"error": "Missing query"}, status=400)
    task = Task(query)
    response = agent.do(task)
    return JsonResponse({"response": response, "user_id": request.user.id})

Store agent runs in the DB by defining a model (e.g. in agent_api/models.py), running migrations, and saving after agent.do() or agent.do_async().

Key takeaways

Use sync views with agent.do(task) when you rely on runserver or a WSGI server.
Use async views with await agent.do_async(task) and an ASGI server for better concurrency.
Combine with Django auth, ORM, and admin when you need user management and persistence.

For a minimal API-only deployment with maximum async performance, see Deploy via FastAPI.

​Prerequisites

​Setup

​Step 2: Docker

​Async view with agent.do_async()

​Using with Django auth and DB

​Key takeaways

Prerequisites

Setup

Step 2: Docker

Async view with `agent.do_async()`

Using with Django auth and DB

Key takeaways