union-py-app 1.0.0

package/app/views/errors.py

@@ -0,0 +1,29 @@
+"""定义视图层统一 HTTP 错误及响应格式。"""
+
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from app.utils.request_logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class RouteError(HTTPException):
+    pass
+
+
+async def http_error(_: Request, exc: RouteError) -> JSONResponse:
+    if isinstance(exc.detail, dict):
+        payload = exc.detail
+    elif isinstance(exc.detail, str):
+        payload = {"error": exc.detail}
+    else:
+        payload = {"detail": exc.detail}
+    reason = payload.get("code") or payload.get("error", "invalid_request")
+    logger.warning(
+        "Request rejected status=%s reason=%r cause=%s",
+        exc.status_code, reason,
+        type(exc.__cause__).__name__ if exc.__cause__ else "-",
+    )
+    return JSONResponse(payload, status_code=exc.status_code, headers=exc.headers)

package/app/views/routes.py

@@ -0,0 +1,25 @@
+"""注册应用对外公开的 HTTP 路由。"""
+
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+
+from app.views.errors import RouteError, http_error
+from app.views.streaming_runs import cancel, runs
+from app.views.sync_runs import scheduled_run, sync_run
+
+__all__ = ["RouteError", "build_routes", "http_error"]
+
+
+def build_routes() -> list[Route]:
+    return [
+        Route("/healthcheck.html", healthcheck, methods=["GET"]),
+        Route("/agent/v1/runs", runs, methods=["POST"]),
+        Route("/agent/v1/runs/cancel", cancel, methods=["POST"]),
+        Route("/agent/v1/runs/sync", sync_run, methods=["POST"]),
+        Route("/agent/v1/runs/scheduled", scheduled_run, methods=["POST"]),
+    ]
+
+
+async def healthcheck(_: Request):
+    return PlainTextResponse("success")

package/app/views/run_context.py

@@ -0,0 +1,33 @@
+"""为各类运行构造一致的依赖与状态客户端。"""
+
+import anyio
+
+from app.agent.runtime.deps import RunDeps
+from app.utils.api_client import ApiClient
+from app.utils.state_client import AgentStateClient
+
+
+def build_state_client(runtime, user: dict) -> AgentStateClient:
+    return AgentStateClient(
+        http=runtime.http,
+        base_url=runtime.settings.union_base_url,
+        auth=user["control_auth"],
+    )
+
+
+def build_run_deps(runtime, user: dict, state_client: AgentStateClient) -> RunDeps:
+    return RunDeps(
+        user_id=user["user_id"],
+        permissions=tuple(user.get("permissions") or ()),
+        authentication_type=user.get("authentication_type", "CAS"),
+        org_code=user.get("org_code", ""),
+        scheduled_run_id=user.get("scheduled_run_id"),
+        state_client=state_client,
+        api_client=ApiClient(
+            http=runtime.http,
+            base_url=runtime.settings.union_base_url,
+            auth=user["control_auth"],
+        ),
+        cancelled=anyio.Event(),
+        rag_service=runtime.rag_service,
+    )

package/app/views/streaming_runs.py

@@ -0,0 +1,350 @@
+"""处理 AG-UI 流式运行、取消及消息历史装载。"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+import anyio
+import httpx
+from ag_ui.core import Message
+from pydantic import TypeAdapter, ValidationError
+from pydantic_ai.exceptions import ModelHTTPError
+from pydantic_ai.messages import ModelMessage, ModelRequest, TextContent, UserPromptPart
+from pydantic_ai.ui.ag_ui import AGUIAdapter
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from app.utils.request_logging import get_logger
+from app.agent.runtime.activity import RunCollector
+from app.agent.runtime.execution import ExecutionPreparationStopped
+from app.agent.runtime.model_errors import model_http_error_details
+from app.utils.state_client import AgentStateError
+from app.views.auth import authenticate_user
+from app.views.errors import RouteError
+from app.views.run_context import build_run_deps, build_state_client
+
+_MESSAGES = TypeAdapter(list[Message])
+_HARNESS_MEMORY_METADATA = "pydantic-ai-harness.memory.v1"
+logger = get_logger(__name__)
+
+
+async def runs(request: Request):
+    runtime = request.app.state.runtime
+    user = await authenticate_user(request, runtime)
+    run_input = _parse_run_input(await request.body())
+    question, user_message = _latest_user_message(run_input.messages)
+    if not question:
+        raise RouteError(422, "a latest user message is required")
+    run_input = run_input.model_copy(update={"messages": [user_message]})
+    state_client = build_state_client(runtime, user)
+    logger.info("History loading started run_id=%r", run_input.run_id)
+    message_history = await _load_message_history(
+        state_client,
+        run_input.thread_id,
+        user_message,
+    )
+    deps = build_run_deps(runtime, user, state_client)
+    collector = RunCollector(
+        root_run_id=run_input.run_id,
+        conversation_id=run_input.thread_id,
+    )
+    collector.root.add_messages(
+        [
+            message.model_dump(by_alias=True, mode="json")
+            for message in run_input.messages
+        ]
+    )
+    record = await _reserve_run(runtime, run_input, deps, collector)
+    root_agent = await _prepare_run(
+        request,
+        runtime,
+        run_input,
+        question,
+        message_history,
+        state_client,
+        deps,
+        collector,
+        record,
+    )
+    record = await _start_run(
+        request,
+        runtime,
+        run_input,
+        root_agent,
+        message_history,
+        deps,
+        collector,
+        record,
+    )
+    return runtime.executions.response(record)
+
+
+async def _reserve_run(runtime, run_input, deps, collector):
+    try:
+        return await runtime.executions.reserve(
+            run_id=run_input.run_id,
+            user_id=deps.user_id,
+            conversation_id=run_input.thread_id,
+            deps=deps,
+            collector=collector,
+        )
+    except ValueError as exc:
+        raise RouteError(409, str(exc)) from exc
+
+
+async def _prepare_run(
+    request,
+    runtime,
+    run_input,
+    question,
+    message_history,
+    state_client,
+    deps,
+    collector,
+    record,
+):
+    preparation_done = anyio.Event()
+
+    async def watch_disconnect() -> None:
+        while not preparation_done.is_set():
+            if await request.is_disconnected():
+                await runtime.executions.cancel(
+                    run_id=run_input.run_id,
+                    user_id=deps.user_id,
+                    conversation_id=run_input.thread_id,
+                )
+                return
+            with anyio.move_on_after(0.1):
+                await preparation_done.wait()
+
+    logger.info("Route resolution started mode=stream run_id=%r", run_input.run_id)
+    preparation_phase = "route_resolution"
+    preparation_error: BaseException | None = None
+    try:
+        async with anyio.create_task_group() as task_group:
+            task_group.start_soon(watch_disconnect)
+            try:
+                decision = await runtime.executions.prepare(
+                    record,
+                    lambda: runtime.graph.router.run(
+                        question,
+                        deps=deps,
+                        message_history=message_history,
+                        conversation_id=run_input.thread_id,
+                        usage_limits=runtime.graph.usage_limits,
+                    ),
+                )
+                root_agent = runtime.graph.resolve_root(decision.output)
+                collector.root_agent_name = root_agent.name or "Agent"
+                logger.info(
+                    "Agent execution starting mode=stream run_id=%r agent=%s",
+                    run_input.run_id,
+                    collector.root_agent_name,
+                )
+            except BaseException as exc:
+                preparation_error = exc
+            finally:
+                preparation_done.set()
+        if preparation_error is not None:
+            raise preparation_error
+    except ExecutionPreparationStopped as exc:
+        status_code = 504 if exc.error_code == "execution_timeout" else 499
+        raise RouteError(status_code, exc.error_code) from exc
+    except anyio.get_cancelled_exc_class():
+        with anyio.CancelScope(shield=True):
+            await runtime.executions.abandon(
+                record,
+                "cancelled",
+                "request_cancelled",
+            )
+        raise
+    except ModelHTTPError as exc:
+        status, code, message, model_name = model_http_error_details(exc)
+        await runtime.executions.abandon(record, "failed", code)
+        logger.error(
+            "Model request failed phase=%s status=%s model=%s code=%s",
+            preparation_phase,
+            status,
+            model_name,
+            code,
+        )
+        raise RouteError(
+            status,
+            {"error": message, "code": code, "model": model_name},
+        )
+    except Exception as exc:
+        error_code = f"{preparation_phase}_failed"
+        await runtime.executions.abandon(record, "failed", error_code)
+        logger.error(
+            "Run preparation failed phase=%s error_type=%s",
+            preparation_phase,
+            type(exc).__name__,
+        )
+        raise RouteError(502, "route resolution failed")
+    return root_agent
+
+
+async def _start_run(
+    request,
+    runtime,
+    run_input,
+    root_agent,
+    message_history,
+    deps,
+    collector,
+    record,
+):
+    try:
+        adapter = AGUIAdapter(
+            agent=root_agent,
+            run_input=run_input,
+            accept=request.headers.get("accept"),
+            allow_uploaded_files=False,
+            preserve_file_data=False,
+        )
+
+        async def capture_root_messages(result) -> None:
+            collector.set_root_messages(
+                [
+                    message.model_dump(by_alias=True, mode="json")
+                    for message in AGUIAdapter.dump_messages(
+                        without_internal_memory(result.new_messages())
+                    )
+                ]
+            )
+
+        stream = adapter.run_stream(
+            output_type=str,
+            deps=deps,
+            message_history=message_history,
+            conversation_id=run_input.thread_id,
+            run_id=run_input.run_id,
+            usage_limits=runtime.graph.usage_limits,
+            on_complete=capture_root_messages,
+        )
+        return await runtime.executions.start(
+            run_id=run_input.run_id,
+            user_id=deps.user_id,
+            conversation_id=run_input.thread_id,
+            adapter=adapter,
+            stream=stream,
+            deps=deps,
+            collector=collector,
+            record=record,
+        )
+    except anyio.get_cancelled_exc_class():
+        with anyio.CancelScope(shield=True):
+            await runtime.executions.abandon(
+                record,
+                "cancelled",
+                "request_cancelled",
+            )
+        raise
+    except ValueError as exc:
+        await runtime.executions.abandon(record, "failed", "run_start_failed")
+        raise RouteError(409, str(exc)) from exc
+    except Exception as exc:
+        await runtime.executions.abandon(record, "failed", "run_start_failed")
+        raise RouteError(500, "run setup failed") from exc
+
+
+def without_internal_memory(messages: list[ModelMessage]) -> list[ModelMessage]:
+    """Remove Harness memory parts while their internal metadata is still intact."""
+    filtered: list[ModelMessage] = []
+    for message in messages:
+        if not isinstance(message, ModelRequest):
+            filtered.append(message)
+            continue
+        parts = []
+        changed = False
+        for part in message.parts:
+            if not isinstance(part, UserPromptPart) or isinstance(part.content, str):
+                parts.append(part)
+                continue
+            content = [
+                item
+                for item in part.content
+                if not (
+                    isinstance(item, TextContent)
+                    and isinstance(item.metadata, str)
+                    and (
+                        item.metadata == _HARNESS_MEMORY_METADATA
+                        or item.metadata.startswith(f"{_HARNESS_MEMORY_METADATA}:")
+                    )
+                )
+            ]
+            if len(content) == len(part.content):
+                parts.append(part)
+            else:
+                changed = True
+                if content:
+                    parts.append(replace(part, content=content))
+        filtered.append(replace(message, parts=parts) if changed else message)
+    return filtered
+
+
+async def cancel(request: Request):
+    runtime = request.app.state.runtime
+    user = await authenticate_user(request, runtime)
+    try:
+        payload = await request.json()
+        run_id = str(payload["runId"])
+        conversation_id = str(payload["conversationId"])
+        cancelled = await runtime.executions.cancel(
+            run_id=run_id,
+            user_id=user["user_id"],
+            conversation_id=conversation_id,
+        )
+    except (KeyError, TypeError, ValueError):
+        return JSONResponse({"error": "invalid cancel request"}, status_code=422)
+    except PermissionError:
+        return JSONResponse({"error": "forbidden"}, status_code=403)
+    return JSONResponse({"success": True, "cancelled": cancelled})
+
+
+def _parse_run_input(body: bytes):
+    try:
+        run_input = AGUIAdapter.build_run_input(body)
+    except ValidationError as exc:
+        raise RouteError(
+            422,
+            exc.errors(include_context=False),
+        ) from exc
+
+    if run_input.tools:
+        raise RouteError(400, "frontend tools are not supported")
+    if run_input.context:
+        raise RouteError(400, "frontend context is not supported")
+    if run_input.state:
+        raise RouteError(400, "frontend state is not supported")
+    if run_input.resume:
+        raise RouteError(400, "frontend resume is not supported")
+    return run_input
+
+
+async def _load_message_history(state_client, thread_id: str, user_message):
+    try:
+        stored = await state_client.load_messages(thread_id)
+        stored_messages = _MESSAGES.validate_python(stored)
+        if stored_messages and stored_messages[-1] == user_message:
+            stored_messages.pop()
+        return AGUIAdapter.load_messages(stored_messages)
+    except (AgentStateError, httpx.HTTPError, ValidationError, TypeError, ValueError) as exc:
+        raise RouteError(503, "conversation history unavailable") from exc
+
+
+def _latest_user_message(messages):
+    for message in reversed(messages):
+        body = message.model_dump(by_alias=True)
+        if body.get("role") == "user":
+            content = body.get("content")
+            if isinstance(content, str):
+                return content.strip(), message
+            if isinstance(content, list):
+                text = "\n".join(
+                    str(item.get("text", ""))
+                    for item in content
+                    if isinstance(item, dict) and item.get("type") == "text"
+                ).strip()
+                return text, message
+    return "", None

package/app/views/sync_runs.py

@@ -0,0 +1,180 @@
+"""处理 CAS 同步运行与定时任务同步适配入口。"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+from zoneinfo import ZoneInfo
+
+import anyio
+from pydantic import BaseModel
+from pydantic_ai.exceptions import ModelHTTPError, UnexpectedModelBehavior
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from app.utils.request_logging import get_logger
+from app.agent.runtime.model_errors import (
+    model_http_error_details,
+    unexpected_model_behavior_details,
+)
+from app.utils.control_auth import ControlAuth
+from app.views.auth import (
+    authenticate_scheduled_run,
+    authenticate_user,
+    reject_scheduled_on_cas_endpoint,
+    scheduled_token,
+    strict_scheduled_body,
+)
+from app.views.errors import RouteError
+from app.views.run_context import build_run_deps, build_state_client
+
+logger = get_logger(__name__)
+
+
+async def sync_run(request: Request):
+    runtime = request.app.state.runtime
+    reject_scheduled_on_cas_endpoint(request)
+    user = await authenticate_user(request, runtime)
+    try:
+        payload = await request.json()
+        question = str(payload["question"]).strip()
+        input_data = payload["input"]
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+        return JSONResponse({"error": "invalid sync request"}, status_code=422)
+    if not question or not isinstance(input_data, dict):
+        return JSONResponse({"error": "invalid sync request"}, status_code=422)
+    return await _sync_response(
+        runtime,
+        user,
+        question,
+        input_data,
+        effective_context=_effective_time_context(request),
+    )
+
+
+async def scheduled_run(request: Request):
+    runtime = request.app.state.runtime
+    token = scheduled_token(request)
+    await strict_scheduled_body(request)
+    identity = await authenticate_scheduled_run(runtime, token)
+    input_data = {
+        "scheduledTaskId": identity.task_id,
+        "scheduledRunId": identity.run_id,
+        "scheduledAt": identity.scheduled_at.isoformat().replace("+00:00", "Z"),
+        "timezone": identity.timezone,
+    }
+    return await _sync_response(
+        runtime,
+        {
+            "authentication_type": "SCHEDULED",
+            "user_id": identity.user_id,
+            "org_code": identity.org_code,
+            "scheduled_run_id": identity.run_id,
+            "control_auth": ControlAuth.trusted_context(identity.trusted_context),
+        },
+        identity.prompt,
+        input_data,
+        effective_context=(input_data["scheduledAt"], identity.timezone),
+    )
+
+
+async def _sync_response(
+    runtime,
+    user: dict[str, Any],
+    question: str,
+    input_data: dict[str, Any],
+    *,
+    effective_context: tuple[str, str] | None = None,
+) -> JSONResponse:
+    try:
+        with anyio.fail_after(runtime.settings.max_run_seconds):
+            content = await _run_sync(
+                runtime,
+                user,
+                question,
+                input_data,
+                effective_context=effective_context,
+            )
+    except TimeoutError:
+        logger.warning(
+            "Sync execution timed out code=execution_timeout limit_seconds=%s",
+            runtime.settings.max_run_seconds,
+        )
+        return JSONResponse(
+            {"code": "execution_timeout", "error": "Agent 执行超时"},
+            status_code=504,
+        )
+    except ModelHTTPError as exc:
+        status, code, message, model_name = model_http_error_details(exc)
+        logger.error(
+            "Sync model request failed status=%s model=%s code=%s",
+            status,
+            model_name,
+            code,
+        )
+        return JSONResponse(
+            {"error": message, "code": code, "model": model_name},
+            status_code=status,
+        )
+    except UnexpectedModelBehavior as exc:
+        status, code, message = unexpected_model_behavior_details(exc)
+        logger.error(
+            "Sync Agent execution failed status=%s code=%s error_type=%s",
+            status,
+            code,
+            type(exc).__name__,
+        )
+        return JSONResponse(
+            {"error": message, "code": code},
+            status_code=status,
+        )
+    return JSONResponse({"content": content})
+
+
+async def _run_sync(
+    runtime,
+    user: dict[str, Any],
+    question: str,
+    input_data: Any,
+    *,
+    effective_context: tuple[str, str] | None = None,
+):
+    state_client = build_state_client(runtime, user)
+    deps = build_run_deps(runtime, user, state_client)
+    if effective_context is not None:
+        deps.effective_at, deps.effective_timezone = effective_context
+    prompt = f"{question}\n\n输入数据：{json.dumps(input_data, ensure_ascii=False)}"
+    logger.info("Route resolution started mode=sync")
+    decision = await runtime.graph.router.run(
+        prompt,
+        deps=deps,
+        usage_limits=runtime.graph.usage_limits,
+    )
+    agent = runtime.graph.resolve_root(decision.output)
+    logger.info("Agent execution started mode=sync agent=%s", agent.name)
+    result = await agent.run(
+        prompt,
+        deps=deps,
+        usage_limits=runtime.graph.usage_limits,
+    )
+    logger.info("Agent execution completed mode=sync agent=%s", agent.name)
+    output = result.output
+    return output.model_dump(by_alias=True) if isinstance(output, BaseModel) else output
+
+
+def _effective_time_context(request: Request) -> tuple[str, str] | None:
+    effective_at = request.headers.get("x-agent-effective-at")
+    timezone = request.headers.get("x-agent-effective-timezone")
+    if effective_at is None and timezone is None:
+        return None
+    if not effective_at or not timezone:
+        raise RouteError(422, "invalid effective time context")
+    try:
+        parsed = datetime.fromisoformat(effective_at.replace("Z", "+00:00"))
+        if parsed.tzinfo is None:
+            raise ValueError
+        ZoneInfo(timezone)
+    except (KeyError, ValueError):
+        raise RouteError(422, "invalid effective time context")
+    return effective_at, timezone

package/deploy/autoconf/templates/env.j2

@@ -0,0 +1,23 @@
+APP_ENV={{APP_ENV}}
+CONSOLE_STDOUT={{CONSOLE_STDOUT}}
+LOG_LEVEL={{LOG_LEVEL}}
+LOG_DIR={{LOG_DIR}}
+# 联合运维服务
+UNION_BASE_URL={{UNION_BASE_URL}}
+PERMISSIONS={{PERMISSIONS}}
+
+# 大模型地址
+LLM_URL={{LLM_URL}}
+LLM_KEY={{LLM_KEY}}
+LLM_MODEL={{LLM_MODEL}}
+LLM_CONTEXT_WINDOW={{LLM_CONTEXT_WINDOW}}
+AGENT_MAX_RUN_SECONDS={{AGENT_MAX_RUN_SECONDS | default('900')}}
+SUBAGENT_TIMEOUT_SECONDS={{SUBAGENT_TIMEOUT_SECONDS | default('900')}}
+
+# 向量模型地址（OpenAI-compatible embeddings API）
+RAG_ENABLED=true
+RAG_KNOWLEDGE_DIR=knowledge
+RAG_COLLECTION=ops_knowledge
+RAG_EMBEDDING_MODEL={{RAG_EMBEDDING_MODEL}}
+RAG_TOP_K=5
+RAG_CHUNK_SIZE=1200

package/deploy/autoconf.yml

@@ -0,0 +1,15 @@
+union-py-app:
+  test:
+    test:
+      - template: deploy/autoconf/templates/env.j2
+        dest: app/.env.test.bj12
+  prod:
+    bj11:
+      - template: deploy/autoconf/templates/env.j2
+        dest: app/.env.prod.bj11
+    sh20:
+      - template: deploy/autoconf/templates/env.j2
+        dest: app/.env.prod.sh20
+    sz31:
+      - template: deploy/autoconf/templates/env.j2
+        dest: app/.env.prod.sz31

package/deploy/scripts/healthcheck.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -u
+
+TIMEOUT_SECONDS="${HEALTHCHECK_TIMEOUT_SECONDS:-5}"
+
+probe_http() {
+  local url="$1"
+  curl --fail --silent --show-error --max-time "$TIMEOUT_SECONDS" "$url" >/dev/null
+}
+
+probe_http "${APP_HEALTHCHECK_URL:-http://127.0.0.1:${APP_PORT:-8080}/healthcheck.html}" || exit 1