Deploy via Django

Integrate Upsonic agents into Django with views, optional DB models and admin

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

1. Initialize the project with uv

   mkdir my-django-agent && cd my-django-agent
   uv init
   uv add django upsonic anthropic
   
2. Create a Django project and app

   uv run django-admin startproject myproject .
   uv run python manage.py startapp agent_api
   
3. Register the app

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

4. 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")),
   ]
   
5. 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),
   ]
   
6. 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

1. Create a `.dockerignore` file

   .dockerignore

   .venv
   __pycache__
   db.sqlite3
   
2. 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"]
   
3. 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
   
4. 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})

Register the async route in agent_api/urls.py:

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.