Enterprise agent platform for building, deploying, and operating AI teammates.
"""Helpers shared by the structured-output record tests: an SDK agent with a
key, task rows written straight to the database, and a recorder of the SELECT
statements one block of code sends."""
from __future__ import annotations
import re
from collections.abc import Iterator
from contextlib import contextmanager
from dataclasses import replace
from datetime import datetime, timezone
from typing import Any
from sqlalchemy import event
from xagent.web.api.v1 import tasks as v1_tasks
from xagent.web.models.agent import Agent
from xagent.web.models.database import get_engine
from xagent.web.models.task import Task, TaskStatus
from xagent.web.services.task_auto_resume import TerminalView
from ..conftest import _admin_headers, _direct_db_session, client
COLUMN = "structured_output_record"
def bearer(full_key: str) -> dict[str, str]:
return {"Authorization": f"Bearer {full_key}"}
def create_agent_with_key() -> tuple[int, str]:
"""An agent under the admin user and its API key: (agent_id, full_key)."""
headers = _admin_headers()
agent_resp = client.post(
"/api/agents",
headers=headers,
json={
"name": "structured output record agent",
"description": "test",
"instructions": "you are a test agent",
"execution_mode": "balanced",
},
)
assert agent_resp.status_code == 200, agent_resp.text
agent_id = agent_resp.json()["id"]
key_resp = client.post(f"/api/agents/{agent_id}/api-key", headers=headers)
assert key_resp.status_code == 200, key_resp.text
return agent_id, key_resp.json()["full_key"]
def insert_task(
agent_id: int,
*,
status: TaskStatus = TaskStatus.COMPLETED,
run_id: str | None = "run-1",
record: Any = None,
agent_config: Any = None,
output: str | None = "final answer",
error: str | None = None,
title: str = "structured output task",
moment: datetime | None = None,
completion_outcome: str | None = None,
) -> int:
"""One SDK task row, with its structured output record and agent_config."""
db = _direct_db_session()
try:
agent = db.query(Agent).filter(Agent.id == agent_id).one()
task = Task(
user_id=int(agent.user_id),
title=title,
description=title,
status=status,
agent_id=agent_id,
input="question",
output=output,
source="sdk",
is_visible=False,
run_id=run_id,
agent_config=agent_config,
error_message=error,
completion_outcome=completion_outcome,
)
if moment is not None:
task.created_at = moment
task.updated_at = moment
task.structured_output_record = record
db.add(task)
db.commit()
return int(task.id)
finally:
db.close()
@contextmanager
def recorded_statements() -> Iterator[list[str]]:
"""Every SQL statement the test engine executes inside the block."""
statements: list[str] = []
def record(_conn, _cursor, statement, *_args) -> None:
statements.append(statement)
engine = get_engine()
event.listen(engine, "before_cursor_execute", record)
try:
yield statements
finally:
event.remove(engine, "before_cursor_execute", record)
def task_selects(statements: list[str]) -> list[str]:
"""The statements that read rows from ``tasks`` into Python."""
return [
s
for s in statements
if s.lstrip().upper().startswith("SELECT")
and not s.lstrip().upper().startswith("SELECT COUNT(")
and re.search(r"\bFROM tasks\b", s) is not None
and "tasks.title" in s
]
FORMAT_CONFIG = {"response_format": {"type": "json_schema", "name": "answer"}}
def stored_format_config(**switch: bool) -> dict[str, Any]:
"""The agent_config of a task whose stored format is complete, with the
accept_partial switch stored as given (not stored when not given)."""
return {
"response_format": {
"type": "json_schema",
"name": "answer",
"schema": {"type": "object", "properties": {}},
"description": None,
**switch,
}
}
MOMENT = datetime(2026, 11, 1, 8, 30, tzinfo=timezone.utc)
RECORD = {
"run_id": "run-1",
"status": "ready",
"output": {"zeta": 1, "alpha": [3, 2, 1]},
"reason": None,
}
# Tasks whose GET response is fixed in structured_output_get_baseline.py:
# (status, run_id, record, agent_config, output, error).
BASELINE_TASKS: list[dict[str, Any]] = [
{"status": TaskStatus.COMPLETED, "output": "final answer"},
{
"status": TaskStatus.COMPLETED,
"output": "with a record",
"record": RECORD,
"agent_config": FORMAT_CONFIG,
},
{"status": TaskStatus.FAILED, "output": None, "error": "agent crashed"},
{"status": TaskStatus.RUNNING, "output": None},
{"status": TaskStatus.PENDING, "output": None, "run_id": None},
{"status": TaskStatus.WAITING_FOR_USER, "output": None},
{"status": TaskStatus.COMPLETED, "output": "\u00e9 \u4e2d\u6587 \U0001f600"},
]
NEW_KEYS = ("structured_output", "structured_output_status", "structured_output_reason")
# The keys of a GET task response and of a task.completed frame for a task
# without accept_partial, in order.
TODAY_TASK_INFO_KEYS = (
"task_id",
"agent_id",
"workforce_id",
"status",
"run_id",
"state_version",
"control_state",
"input",
"output",
"error",
"error_code",
"created_at",
"completed_at",
"pending_interaction",
*NEW_KEYS,
)
TODAY_COMPLETED_FRAME_KEYS = ("status", "output", "error", "error_code", *NEW_KEYS)
SWITCH_OFF_CONFIGS = {
"no-format": None,
"no-switch": stored_format_config(),
"switch-false": stored_format_config(accept_partial=False),
}
SWITCH_ON_CONFIG = stored_format_config(accept_partial=True)
TERMINAL_VIEW = TerminalView(
state="stopped", error="stopped", stopped_at=MOMENT, reason="x"
)
# (id, rating stored on the row, snapshot changes that make the effective state)
EFFECTIVE_STATES = [
("completed-completed", "completed", {}),
("completed-partial", "partial", {}),
("completed-blocked", "blocked", {}),
("completed-unrated", None, {}),
("pending", "partial", {"start_queued": True}),
("failed-view", "partial", {"view": TERMINAL_VIEW}),
]
def with_snapshot(monkeypatch, **changes) -> None:
"""Make the v1 task snapshot reader return the row's snapshot with
``changes`` applied."""
real = v1_tasks._load_task_info_snapshot
monkeypatch.setattr(
v1_tasks,
"_load_task_info_snapshot",
lambda task_id, principal: replace(real(task_id, principal), **changes),
)