Upsonic

"""An Upsonic support agent on AgentOS. The refund tool is an external-execution tool: Upsonic pauses the run when
the model calls it, AgentOS asks a person, and on the resume the agent issues the refund as decided (approved,
edited or rejected) and hands Upsonic the result. Upsonic keeps a paused run in its database; here that database is
a SQLite file that travels in the run's state, so the resume works in whichever container answers it."""
import base64
import hashlib
import json
import os
import tempfile

import agentos
from openai import AsyncOpenAI
from upsonic import Agent, Task
from upsonic.db.database import SqliteDatabase
from upsonic.models.openai import OpenAIChatModel
from upsonic.providers.openai import OpenAIProvider
from upsonic.run.requirements import RunRequirement
from upsonic.tools import tool

ORDERS = {  # stands in for your order system
    "A-1001": {"status": "delivered", "total": "49.90", "items": ["Desk lamp"], "delivered": "2026-10-02"},
    "A-1002": {"status": "in transit", "total": "129.00", "items": ["Office chair"], "delivered": None},
}


def lookup_order(order_id: str) -> str:
    """Look an order up by its id (like A-1001): its status, items, total and delivery date."""
    order = ORDERS.get(order_id.strip().upper())
    return json.dumps(order) if order else f"There is no order {order_id}."


@tool(external_execution=True)
def issue_refund(order_id: str, amount: str, reason: str) -> str:
    """Refund `amount` (a decimal string like 49.90) on an order. A person approves every refund first."""
    raise NotImplementedError  # never called by Upsonic: the agent runs refunds itself, once a person decided


def refund(run_id: str, order_id: str, amount: str) -> str:
    """Stands in for your payment provider; key the real call by run id so a retried run never pays twice."""
    refund_id = "rf_" + hashlib.sha256(f"{run_id}:{order_id}:{amount}".encode()).hexdigest()[:12]
    return f"Refunded {amount} on {order_id}: {refund_id}"


def build_agent(inv: agentos.Invocation, db_file: str) -> Agent:
    """Built per invocation: the model client carries this run's token."""
    model = OpenAIChatModel(
        inv.llm.model("main"),  # config.models.main, sent to the gateway as it is
        provider=OpenAIProvider(openai_client=AsyncOpenAI(**inv.llm.openai_kwargs(asynchronous=True), max_retries=0)),
    )
    db = SqliteDatabase(db_file=db_file, session_id=inv.run_id, user_id=inv.user or "anonymous")
    return Agent(model, name="support", db=db, system_prompt=inv.config["prompts"]["system"])


async def support(inv: agentos.Invocation):
    db_file = os.path.join(tempfile.gettempdir(), f"upsonic-{inv.run_id}.db")
    paused = await inv.state.run.aget("upsonic")  # set while a person decides
    if paused:  # the resume: put Upsonic's database back where it was
        with open(db_file, "wb") as f:
            f.write(base64.b64decode(paused["db"]))
    agent = build_agent(inv, db_file)
    try:
        if not paused:  # the start
            output = await agent.do_async(Task(inv.input["message"], tools=[lookup_order, issue_refund]),
                                          return_output=True)
        else:  # run the refunds as decided, then let Upsonic continue with their results
            requirements = [RunRequirement.from_dict(r) for r in paused["requirements"]]
            for requirement in requirements:
                if requirement.needs_external_execution:
                    requirement.set_external_execution_result(decided(inv, requirement))
            output = await agent.continue_run_async(run_id=paused["run_id"], requirements=requirements,
                                                    return_output=True)
    except Exception as error:
        if block := agentos.guardrail_block(error):
            raise block  # the run fails with blocked_by_guardrail and the guardrail's message
        raise

    if output.is_paused:  # the model wants to refund: keep the paused run, ask a person
        with open(db_file, "rb") as f:
            await inv.state.run.aput("upsonic", {"run_id": output.run_id, "db": base64.b64encode(f.read()).decode(),
                                                 "requirements": [r.to_dict() for r in output.requirements]})
        calls = [r.tool_execution for r in output.active_requirements if r.needs_external_execution]
        await inv.aask("Approve these refunds?",
                       [{"id": call.tool_call_id, "title": f"Refund {call.tool_args['amount']} on "
                                                           f"{call.tool_args['order_id']}",
                         "data": call.tool_args} for call in calls],
                       actions=["approve", "edit", "reject"])
    await inv.state.run.adelete("upsonic")
    return {"answer": str(output.output)}


def decided(inv: agentos.Invocation, requirement: RunRequirement) -> str:
    """What the refund tool returns to the model: the refund as approved or edited, or why it didn't happen."""
    item = inv.resume.item(requirement.tool_execution.tool_call_id)
    if item is None:  # the ask expired
        return "Nobody approved this refund in time; it was not issued."
    if item.action == "reject":
        return f"A person rejected this refund. {item.comment or ''}".strip()
    return refund(inv.run_id, item.data["order_id"], item.data["amount"])  # as approved, or as edited


agentos.serve({"support": support}, port=8080)

name: upsonic-support
title: Support agent (Upsonic)
description: Answers order questions with a lookup tool; refunds go through a person first.
runtime: stateless
port: 8080
capabilities:
  support:
    description: Handles a customer's message. A refund the model wants to issue waits for a person's approval.
    input:
      type: object
      properties: {message: {type: string, minLength: 1}}
      required: [message]
    output:
      type: object
      properties: {answer: {type: string}}
      required: [answer]
    timeout: 120s
config:
  models:
    main: anthropic/claude-sonnet-4-5    # a model from your Models page: <provider slug>/<model ID>
  prompts:
    system: >-
      You are a support agent for an online shop. Look orders up with lookup_order before you
      answer anything about an order. Use issue_refund only for delivered orders that arrived
      damaged. Answer in at most three sentences.

FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# the AgentOS SDK wheel, from the bundle's vendor/ folder
COPY vendor/ vendor/
RUN pip install --no-cache-dir vendor/*.whl
COPY app.py .
USER nobody
EXPOSE 8080
CMD ["python", "-u", "app.py"]

upsonic[sqlite-storage]==0.77.3