POST /agui/history
Host: smartmedia.vod-qcloud.com
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
  "threadId": "my-thread-001",
  "forwardedProps": {
    "scenario_name": "video-mixcut"
  }
}

POST /agui/cancel
Host: smartmedia.vod-qcloud.com
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
  "threadId": "my-thread-001",
  "forwardedProps": {
    "scenario_name": "video-mixcut"
  }
}


id: <ID>
data: {"type":"<EventType>","timestamp":<timestamp>,...}

id: RUN_STARTED_1784102011155
data: {"type":"RUN_STARTED","timestamp":1784102011155,"threadId":"thread-001","runId":"run-001"}

id: REASONING_START_1784102012264
data: {"type":"REASONING_START","timestamp":1784102012264,"messageId":"msg-001"}

id: REASONING_MESSAGE_START_1784102012264
data: {"type":"REASONING_MESSAGE_START","timestamp":1784102012264,"messageId":"msg-001","role":"reasoning"}

id: REASONING_MESSAGE_CONTENT_1784102012264
data: {"type":"REASONING_MESSAGE_CONTENT","timestamp":1784102012264,"messageId":"msg-001","delta":"The user wants to search for ocean wave videos..."}

id: REASONING_MESSAGE_END_1784102013400
data: {"type":"REASONING_MESSAGE_END","timestamp":1784102013400,"messageId":"msg-001"}

id: REASONING_END_1784102013401
data: {"type":"REASONING_END","timestamp":1784102013401,"messageId":"msg-001"}

id: TEXT_MESSAGE_START_1784102019000
data: {"type":"TEXT_MESSAGE_START","timestamp":1784102019000,"messageId":"msg-002"}

id: TEXT_MESSAGE_CONTENT_1784102019050
data: {"type":"TEXT_MESSAGE_CONTENT","timestamp":1784102019050,"messageId":"msg-002","delta":"I'll help you search."}

id: TEXT_MESSAGE_END_1784102024858
data: {"type":"TEXT_MESSAGE_END","timestamp":1784102024858,"messageId":"msg-002"}

id: TOOL_CALL_START_1784102126631
data: {"type":"TOOL_CALL_START","timestamp":1784102126631,"toolCallId":"call-001","toolCallName":"search_media_by_semantics","parentMessageId":"msg-002"}

id: TOOL_CALL_ARGS_1784102126631
data: {"type":"TOOL_CALL_ARGS","timestamp":1784102126631,"toolCallId":"call-001","delta":"{\\"query\\":\\"ocean waves\\"}"}

id: TOOL_CALL_END_1784102126631
data: {"type":"TOOL_CALL_END","timestamp":1784102126631,"toolCallId":"call-001"}

id: TOOL_CALL_RESULT_1784102126886
data: {"type":"TOOL_CALL_RESULT","timestamp":1784102126886,"messageId":"msg-003","toolCallId":"call-001","content":"{\\"Recall\\":[]}","role":"tool"}

id: RUN_FINISHED_1784102025004
data: {"type":"RUN_FINISHED","timestamp":1784102025004,"threadId":"thread-001","runId":"run-001"}

{
  "threadId": "my-thread-001",
  "runId": "run-002",
  "messages": [{"role": "user", "content": ""}],
  "forwardedProps": {"approval_mode": "level:low", "scenario_name": "video-mixcut"},
  "resume": [
    {"interruptId": "interruptId-001", "status": "resolved"},
    {"interruptId": "interruptId-002", "status": "resolved"}
  ]
}


{
  "threadId": "my-thread-001",
  "runId": "run-002",
  "messages": [{"role": "user", "content": ""}],
  "forwardedProps": {"approval_mode": "level:low", "scenario_name": "video-mixcut"},
  "resume": [
    {"interruptId": "interruptId-001", "status": "cancelled", "payload": {"feedback": "No cropping needed"}},
    {"interruptId": "interruptId-002", "status": "cancelled", "payload": {"feedback": "No watermark needed"}}
  ]
}

{
  "threadId": "my-thread-001",
  "runId": "run-002",
  "messages": [{"role": "user", "content": ""}],
  "forwardedProps": {"approval_mode": "level:low", "scenario_name": "video-mixcut"},
  "resume": [
    {"interruptId": "interruptId-001", "status": "resolved"},
    {"interruptId": "interruptId-002", "status": "cancelled", "payload": {"feedback": "Do not add a watermark"}}
  ]
}

{
  "threadId": "thread-001",
  "runId": "run-001",
  "messages": [{"role": "user", "content": "Search for ocean wave videos"}],
  "forwardedProps": {"scenario_name": "video-mixcut"}
}

{
  "threadId": "thread-001",
  "runId": "run-001",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Help me mash up these assets"
        },
        {
          "type": "mixcut_assets",
          "metadata": {
            "attachments": [
              {"url": " http://example.com/video-a.mp4"},
              {"fileId": "vod-file-001"}
            ]
          }
        }
      ]
    }
  ]
}

{
  "name": "<tool_name>",
  "description": "<Tool purpose description, based on which the LLM decides when to call>",
  "parameters": <JSON schema definition of the tool parameters>
}

{
  "name": "clarify",
  "description": "Ask the user a question when you need clarification...",
  "parameters": {
    "type": "object",
    "properties": {
      "question": {
        "type": "string",
        "description": "The question itself. Do NOT embed options here."
      },
      "choices": {
        "type": "array",
        "items": { "type": "string" },
        "maxItems": 4,
        "description": "Selectable options (up to 4). Omit for free-text."
      }
    },
    "required": ["question"]
  }
}

Request → LLM decides to call an external tool
  ↓ SSE event stream
  TOOL_CALL_START   { toolCallId, toolCallName }
  TOOL_CALL_ARGS    { delta (JSON fragment) }
  TOOL_CALL_END     { toolCallId }
  ↓ Tool execution is suspended, and the Agent ends the current turn.
  RUN_FINISHED

[The client executes the external tool and fills in the result]
  ↓
  Send a new request (/agui/chat)
  {
    "threadId": "...",
    "runId": "...",
    "messages": [ { "role": "tool", "content": "<tool_execution_result>", "toolCallId": "<id>" } ],
    "tools": [ ... ]
  }
  → The Agent continues execution.

id: TOOL_CALL_START_xxx
data: {"type":"TOOL_CALL_START","timestamp":...,"toolCallId":"call-ext-001","toolCallName":"external_search","parentMessageId":"msg-001"}

id: TOOL_CALL_ARGS_xxx
data: {"type":"TOOL_CALL_ARGS","timestamp":...,"toolCallId":"call-ext-001","delta":"{\\"query\\":\\"VOD architecture document\\"}"}

id: TOOL_CALL_END_xxx
data: {"type":"TOOL_CALL_END","timestamp":...,"toolCallId":"call-ext-001"}

id: RUN_FINISHED_xxx
data: {"type":"RUN_FINISHED","timestamp":...,"threadId":"thread-001","runId":"run-001"}

{
  "threadId": "my-thread-001",
  "runId": "run-002",
  "messages": [
    {
      "role": "tool",
      "content": "<tool_execution_result (a string that the LLM interprets)>",
      "toolCallId": "call-ext-001"
    }
  ],
  "tools": [
    {
      "name": "clarify",
      "description": "...",
      "parameters": {"type":"object","properties":{}}
    }
  ]
}

from ag_ui.client import HttpAgent
from ag_ui.core import RunAgentInput, Message, ResumeEntry

BASE_URL = "https://smartmedia.vod-qcloud.com/agui"
API_KEY = "<your-token>"

def run_agent(thread_id, run_id, message, resume=None, forwarded_props=None):
    agent = HttpAgent(
        base_url=BASE_URL,
        api_key=API_KEY,
    )

    input_params = RunAgentInput(
        thread_id=thread_id,
        run_id=run_id,
        messages=[Message(role="user", content=message)],
    )
    if forwarded_props:
        input_params.forwarded_props = forwarded_props
    if resume:
        input_params.resume = resume

    interrupts = []
    for event in agent.run(input_params):
        etype = event.type
        if etype == "TEXT_MESSAGE_CONTENT":
            print(event.delta, end="", flush=True)
        elif etype == "TOOL_CALL_START":
            print(f"\\n[Tool] {event.tool_call_name}")
        elif etype == "RUN_FINISHED":
            outcome = getattr(event, "outcome", None)
            if outcome and outcome.type == "interrupt":
                interrupts = outcome.interrupts
                for i, intr in enumerate(interrupts):
                    print(f"\\n[Interrupt {i + 1}] {intr.message} (id: {intr.id})")
        elif etype == "RUN_ERROR":
            print(f"\\n[Error] {event.message}")
    return interrupts

# 1. First Conversation
interrupts = run_agent(
    thread_id="thread-001",
    run_id="run-001",
    message="Search for ocean wave videos and trim the first 10 seconds",
    forwarded_props={
        "approval_mode": "level:low",
        "scenario_name": "media_management",
    },
)

# 2. Independent Decision per Tool — Approve the First, Reject the Second
if interrupts:
    print(f"\\n{len(interrupts)} tools require confirmation")
    resume = []
    for i, intr in enumerate(interrupts):
        if i == 0:
            resume.append(ResumeEntry(
                interrupt_id=intr.id,
                status="resolved",
            ))
        else:
            resume.append(ResumeEntry(
                interrupt_id=intr.id,
                status="cancelled",
                payload={"feedback": "This operation is not needed"},
            ))

    # 3. Resume (with the same approval_mode)
    run_agent(
        "thread-001", "run-002", "",
        resume=resume,
        forwarded_props={"approval_mode": "level:low"},
    )

import { HttpAgent } from "@ag-ui/client";
import type { RunAgentInput, Interrupt } from "@ag-ui/core";

const BASE_URL = "https://smartmedia.vod-qcloud.com/agui";
const API_KEY = "<your-token>";

async function runAgent(params: {
  threadId: string;
  runId: string;
  message: string;
  forwardedProps?: Record<string, unknown>;
  resume?: Array<{
    interruptId: string;
    status: "resolved" | "cancelled";
    payload?: Record<string, unknown>;
  }>;
}): Promise<Interrupt[]> {
  const agent = new HttpAgent({
    serverUrl: BASE_URL,
    apiKey: API_KEY,
  });

  const input: RunAgentInput = {
    threadId: params.threadId,
    runId: params.runId,
    messages: [{ role: "user", content: params.message }],
    forwardedProps: params.forwardedProps,
    resume: params.resume,
  };

  const interrupts: Interrupt[] = [];

  // Subscribe to the event stream
  const unsubscribe = agent.subscribe((event: any) => {
    switch (event.type) {
      case "TEXT_MESSAGE_CONTENT":
        process.stdout.write(event.delta || "");
        break;
      case "TOOL_CALL_START":
        console.log(`\\n[Tool] ${event.toolCallName}`);
        break;
      case "RUN_FINISHED":
        if (event.outcome?.type === "interrupt") {
          interrupts.push(...event.outcome.interrupts);
          interrupts.forEach((intr, i) =>
            console.log(`\\n[Interrupt ${i + 1}] ${intr.message} (id: ${intr.id})`)
          );
        }
        break;
      case "RUN_ERROR":
        console.error(`\\n[Error] ${event.message}`);
        break;
    }
  });

  // Run the Agent
  await agent.run(input);
  unsubscribe();
  return interrupts;
}

// Usage example: independent approval per tool
async function main() {
  // 1. First Conversation
  const interrupts = await runAgent({
    threadId: "thread-001",
    runId: "run-001",
    message: "Search for ocean wave videos and trim the first 10 seconds",
    forwardedProps: {
      approval_mode: "level:low",
      scenario_name: "media_management",
    },
  });

  // 2. Independent Decision per Tool — Approve the First, Reject the Second
  if (interrupts.length > 0) {
    console.log(`\\n${interrupts.length} tools require confirmation`);
    await runAgent({
      threadId: "thread-001",
      runId: "run-002",
      message: "",
      forwardedProps: { approval_mode: "level:low" },
      resume: interrupts.map((intr, idx) => ({
        interruptId: intr.id,
        status: idx === 0 ? "resolved" as const : "cancelled" as const,
        payload: idx === 0 ? undefined : { feedback: "This operation is not needed" },
      })),
    });
  }
}

main();