upstage-studio

Upstage Studio / Document Agent API

Run multi-step document processing workflows via the Upstage Document Agent API (v2). Two paths:

1. Studio UI path — visually configure a workflow at console.upstage.ai/studio, then call the resulting Agent ID (agt_xxx) from your code.
2. API-only path — create Agents and Configs (workflows) programmatically via REST. See references/agents-and-configs.md.

Both paths execute the same way: upload a File → run a Job → poll for results.

Quick Start (End-to-End, Studio UI Path)

import os
import time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UPSTAGE_API_KEY"],
    base_url="https://api.upstage.ai/v2"
)

# 1. Upload file
file = client.files.create(
    file=open("document.pdf", "rb"),
    purpose="user_data"
)

# 2. Create workflow job
job = client.responses.create(
    model="agt_BxcRatEWzVYH2yRNtyWynn",  # Studio Agent ID
    input=[{
        "role": "user",
        "content": [{"type": "input_file", "file_id": file.id}]
    }],
    include=["all"]  # "all": all step results, "last": final step only
)

# 3. Poll until complete
while job.status in ("queued", "in_progress"):
    time.sleep(5)
    job = client.responses.retrieve(job.id, include=["all"])

# 4. Print results
if job.status == "completed":
    for step in job.output:
        print(f"\n=== {step.model} ===")
        for content in step.content:
            print(content.text)
else:
    print(f"Job failed: {job.status}")

# 5. Cleanup
client.files.delete(file.id)

API Key: Always use os.environ["UPSTAGE_API_KEY"]. Get your key at console.upstage.ai/api-keys (keys start with up_).

Base URL: https://api.upstage.ai (Document Agent endpoints live under /v2)

---

Core Concepts

Resource Hierarchy

Agent (execution unit)
 └─ Config (workflow definition: ordered Steps + conditional branching)
     └─ Job (execution instance)
         ├─ File (input document)
         └─ Results (per-step output)