Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

28.0 KB
Raw Blame
from __future__ import annotations

import logging
from typing import Any, Literal

from fastapi import APIRouter, HTTPException, Response, status
from pydantic import BaseModel, Field

from openexecutive.agents.base import AgentVisibility
from openexecutive.agents.overrides import (
    EXECUTIVE_AGENT_ID as EXECUTIVE_ID,
)
from openexecutive.agents.overrides import (
    AgentHistoryEntry,
    append_instructions,
    clear_override,
    get_override,
    list_history,
    rollback_to,
    set_override,
)
from openexecutive.agents.presets import (
    PRESET_IDS,
    PRESETS,
    AgentState,
    PresetId,
    preset_available,
    preset_model,
    preset_status,
    writes_for,
)
from openexecutive.audit.usage import log_model_usage
from openexecutive.orchestrator.pushback import PUSHBACK_OFF

logger = logging.getLogger(__name__)

router = APIRouter()

# Models the Agent Council UI is allowed to switch agents to. Sourced
# from ``providers.allowed_models()`` so the dropdown always matches
# what the runtime can actually serve — when OPENROUTER_ENABLED is on,
# the curated OpenRouter set folds in automatically.
from openexecutive.providers import allowed_models_for as _allowed_models_for  # noqa: E402
from openexecutive.providers import model_options_for as _model_options_for  # noqa: E402


def _allowed(agent_id: str | None = None) -> list[str]:
    return _allowed_models_for(agent_id)


class ModelOption(BaseModel):
    """One allowlisted model, grouped for the Council's Provider → Model picker."""

    id: str
    provider: str
    provider_label: str
    route: Literal["direct", "openrouter", "local"]
    label: str


class AgentMeta(BaseModel):
    name: str
    role: str
    model: str
    deep_reasoning: bool
    domains: list[str]
    has_override: bool = False
    # "core" (the Executive and the domain specialists) or "internal"
    # (triage and the helper agents); the Council's simple view lists core.
    visibility: AgentVisibility = "internal"


class AgentDetail(BaseModel):
    name: str
    role: str
    role_default: str
    model: str
    model_default: str
    deep_reasoning: bool
    deep_reasoning_default: bool
    prompt: str
    prompt_default: str
    domains: list[str]
    has_override: bool
    overridden_fields: list[str]
    updated_at: str | None = None
    voice_persona_slug: str | None = None
    # Per-specialist research-mode focus tail (effective value + code
    # default). null for agents that have no research scope (executive /
    # utility knobs); the UI shows the editor only when a default exists.
    research_focus: str | None = None
    research_focus_default: str | None = None
    # Additional instructions appended after ``prompt`` (which stays the
    # built-in prompt or its replacement, never the two joined).
    instructions: str | None = None
    # The Executive only: the model for one answer after pushback
    # (orchestrator.pushback), and PUSHBACK_MODEL's. "off" or "" means
    # answers stay on ``model``. null on the specialists.
    pushback_model: str | None = None
    pushback_model_default: str | None = None


# Additional instructions ride in every call to the agent (and in the
# Executive's cached block 0), so they stay short. A whole new prompt goes
# in ``prompt`` instead.
INSTRUCTIONS_MAX_CHARS = 4000


class AgentPatch(BaseModel):
    prompt: str | None = None
    model: str | None = None
    use_deep_reasoning: bool | None = None
    role: str | None = None
    voice_persona_slug: str | None = None
    research_focus: str | None = None
    instructions: str | None = Field(None, max_length=INSTRUCTIONS_MAX_CHARS)
    # The Executive only: a model id, "off", or null to follow PUSHBACK_MODEL.
    pushback_model: str | None = None


class AgentTestRequest(BaseModel):
    query: str
    prompt: str | None = None
    instructions: str | None = Field(None, max_length=INSTRUCTIONS_MAX_CHARS)
    model: str | None = None
    use_deep_reasoning: bool | None = None


class AgentTestResponse(BaseModel):
    response: str


def _role_default(name: str) -> str:
    if name == "executive":
        return "Executive"
    if name == "quality_judge":
        return "Committee · Quality Judge"
    if name == "utility_fast":
        return "Utility · Fast model (gates, titles, decision parsing)"
    if name == "research":
        return "Utility · Research model (executive_research fan-out)"
    if name == "fixture_generator":
        return "Utility · Company fixture generator"
    if name == "engagement_intake":
        return "Utility · Client engagement intake (grounded company drafts)"
    if name == "onboarding_interviewer":
        return "Utility · Company setup interviewer (conversational onboarding)"
    if name == "workflow_designer":
        return "Utility · Workflow designer (conversational New workflow wizard)"
    if name == "workflow_actor":
        return "Utility · Workflow actor (runs workflow action steps with tools)"
    from openexecutive.orchestrator.router import SPECIALIST_DESCRIPTIONS

    description = SPECIALIST_DESCRIPTIONS.get(name, name)
    return description.split(" — ")[0] if " — " in description else description


_executive_proxy: Any = None
_quality_judge_agent: Any = None
_utility_fast_agent: Any = None
_research_council_agent: Any = None
_fixture_generator_agent: Any = None
_engagement_intake_agent: Any = None
_onboarding_interviewer_agent: Any = None
_workflow_designer_agent: Any = None
_workflow_actor_agent: Any = None


def _agent_registry() -> dict[str, Any]:
    """Map of agent_id → agent instance for the Council UI.

    Includes the Executive proxy, all consult-routable specialists, the
    Committee's Quality Judge, the ``utility_fast`` virtual agent that
    controls the model used by non-specialist Haiku call sites (Discord
    response gate / title gen, wait_for_human parser, inbound resolver
    disambiguation), and the ``fixture_generator`` that authors company
    simulator fixtures, the ``onboarding_interviewer`` that runs the
    conversational company-setup flow, the ``workflow_designer`` behind the
    conversational New workflow wizard, the ``workflow_actor`` that runs
    workflow action steps with tools, and the ``research`` virtual agent
    whose model + deep-reasoning drive the executive_research fan-out. These
    live here (not in SPECIALIST_REGISTRY) because we want them overridable
    through the Council but NOT callable via the ``consult_specialist`` tool.
    """
    global _executive_proxy, _quality_judge_agent, _utility_fast_agent
    global _research_council_agent, _fixture_generator_agent
    global _engagement_intake_agent, _onboarding_interviewer_agent
    global _workflow_designer_agent, _workflow_actor_agent
    if _executive_proxy is None:
        from openexecutive.agents.executive_proxy import ExecutiveProxy
        _executive_proxy = ExecutiveProxy()
    if _quality_judge_agent is None:
        from openexecutive.agents.quality_judge import QualityJudgeAgent
        _quality_judge_agent = QualityJudgeAgent()
    if _utility_fast_agent is None:
        from openexecutive.agents.utility_fast import UtilityFastAgent
        _utility_fast_agent = UtilityFastAgent()
    if _research_council_agent is None:
        from openexecutive.agents.research_council import ResearchCouncilAgent
        _research_council_agent = ResearchCouncilAgent()
    if _fixture_generator_agent is None:
        from openexecutive.agents.fixture_generator import FixtureGeneratorAgent
        _fixture_generator_agent = FixtureGeneratorAgent()
    if _engagement_intake_agent is None:
        from openexecutive.agents.engagement_intake import EngagementIntakeAgent
        _engagement_intake_agent = EngagementIntakeAgent()
    if _onboarding_interviewer_agent is None:
        from openexecutive.agents.onboarding_interviewer import (
            OnboardingInterviewerAgent,
        )
        _onboarding_interviewer_agent = OnboardingInterviewerAgent()
    if _workflow_designer_agent is None:
        from openexecutive.agents.workflow_designer import WorkflowDesignerAgent
        _workflow_designer_agent = WorkflowDesignerAgent()
    if _workflow_actor_agent is None:
        from openexecutive.agents.workflow_actor import WorkflowActorAgent
        _workflow_actor_agent = WorkflowActorAgent()
    from openexecutive.orchestrator.router import SPECIALIST_REGISTRY

    return {
        "executive": _executive_proxy,
        **SPECIALIST_REGISTRY,
        "quality_judge": _quality_judge_agent,
        "utility_fast": _utility_fast_agent,
        "research": _research_council_agent,
        "fixture_generator": _fixture_generator_agent,
        "engagement_intake": _engagement_intake_agent,
        "onboarding_interviewer": _onboarding_interviewer_agent,
        "workflow_designer": _workflow_designer_agent,
        "workflow_actor": _workflow_actor_agent,
    }


class _ExecutiveDefaults:
    """Defaults for the synthetic 'executive' agent entry.

    The Executive isn't a BaseAgent — it has no analyze() and its system
    prompt is assembled by cache_manager. We expose just enough surface
    for the Council UI to read/edit it like a specialist.
    """

    # Matches _role_default("executive") so the proxy-based path (main) and
    # the synthetic-defaults path agree on what the UI should display.
    role: str = "Executive"
    use_deep_reasoning: bool = False

    @staticmethod
    def model() -> str:
        from openexecutive.config import get_settings

        return get_settings().default_model

    @staticmethod
    def pushback_model() -> str:
        from openexecutive.config import get_settings

        return (get_settings().pushback_model or "").strip()

    @staticmethod
    def prompt() -> str:
        """The built-in persona for this install's workspace mode, so the
        Council shows — and resets to — the prompt a turn actually uses."""
        from openexecutive.memory.workspace_settings import get_workspace
        from openexecutive.prompts.executive_persona import default_persona

        return default_persona(get_workspace().mode)


def _build_executive_meta() -> AgentMeta:
    ov = get_override(EXECUTIVE_ID)
    role = (
        ov.role if ov is not None and ov.role is not None else _ExecutiveDefaults.role
    )
    model = (
        ov.model
        if ov is not None and ov.model is not None
        else _ExecutiveDefaults.model()
    )
    deep = (
        ov.use_deep_reasoning
        if ov is not None and ov.use_deep_reasoning is not None
        else _ExecutiveDefaults.use_deep_reasoning
    )
    return AgentMeta(
        name=EXECUTIVE_ID,
        role=role,
        model=model,
        deep_reasoning=deep,
        domains=[],
        has_override=ov is not None,
        visibility="core",
    )


def _build_executive_detail() -> AgentDetail:
    ov = get_override(EXECUTIVE_ID)
    overridden: list[str] = []
    if ov is not None:
        if ov.prompt is not None:
            overridden.append("prompt")
        if ov.model is not None:
            overridden.append("model")
        if ov.use_deep_reasoning is not None:
            overridden.append("use_deep_reasoning")
        if ov.role is not None:
            overridden.append("role")
        if ov.voice_persona_slug is not None:
            overridden.append("voice_persona_slug")
        if ov.instructions is not None:
            overridden.append("instructions")
        if ov.pushback_model is not None:
            overridden.append("pushback_model")
    role_default = _ExecutiveDefaults.role
    pushback_default = _ExecutiveDefaults.pushback_model()
    model_default = _ExecutiveDefaults.model()
    prompt_default = _ExecutiveDefaults.prompt()
    return AgentDetail(
        name=EXECUTIVE_ID,
        role=(ov.role if ov and ov.role is not None else role_default),
        role_default=role_default,
        model=(ov.model if ov and ov.model is not None else model_default),
        model_default=model_default,
        deep_reasoning=(
            ov.use_deep_reasoning
            if ov and ov.use_deep_reasoning is not None
            else _ExecutiveDefaults.use_deep_reasoning
        ),
        deep_reasoning_default=_ExecutiveDefaults.use_deep_reasoning,
        prompt=(ov.prompt if ov and ov.prompt is not None else prompt_default),
        prompt_default=prompt_default,
        domains=[],
        has_override=ov is not None,
        overridden_fields=overridden,
        updated_at=ov.updated_at if ov else None,
        voice_persona_slug=ov.voice_persona_slug if ov else None,
        instructions=ov.instructions if ov else None,
        pushback_model=(
            ov.pushback_model if ov and ov.pushback_model is not None else pushback_default
        ),
        pushback_model_default=pushback_default,
    )


def _domains_for(name: str) -> list[str]:
    from openexecutive.knowledge.retriever import DOMAIN_ALIASES

    return DOMAIN_ALIASES.get(name, [])


def _build_meta(name: str) -> AgentMeta:
    agent = _agent_registry()[name]
    ov = get_override(name)
    return AgentMeta(
        name=name,
        role=(ov.role if ov and ov.role is not None else _role_default(name)),
        model=agent.effective_model(),
        deep_reasoning=agent.effective_use_deep_reasoning(),
        domains=_domains_for(name),
        has_override=ov is not None,
        visibility=agent.visibility,
    )


def _build_detail(name: str) -> AgentDetail:
    from openexecutive.monitoring.research.prompts import default_research_focus

    agent = _agent_registry()[name]
    ov = get_override(name)
    overridden: list[str] = []
    if ov is not None:
        if ov.prompt is not None:
            overridden.append("prompt")
        if ov.model is not None:
            overridden.append("model")
        if ov.use_deep_reasoning is not None:
            overridden.append("use_deep_reasoning")
        if ov.role is not None:
            overridden.append("role")
        if ov.research_focus is not None:
            overridden.append("research_focus")
        if ov.instructions is not None:
            overridden.append("instructions")
    # null (not "") for agents with no research scope, so the UI can decide
    # whether to render the research-focus editor at all.
    rf_default = default_research_focus(name) or None
    rf_effective = (
        ov.research_focus if ov and ov.research_focus is not None else rf_default
    )
    return AgentDetail(
        name=name,
        role=(ov.role if ov and ov.role is not None else _role_default(name)),
        role_default=_role_default(name),
        model=agent.effective_model(),
        model_default=agent.model,
        deep_reasoning=agent.effective_use_deep_reasoning(),
        deep_reasoning_default=agent.use_deep_reasoning,
        prompt=agent.base_system_prompt(),
        prompt_default=agent.get_system_prompt(),
        domains=_domains_for(name),
        has_override=ov is not None,
        overridden_fields=overridden,
        updated_at=ov.updated_at if ov else None,
        research_focus=rf_effective,
        research_focus_default=rf_default,
        instructions=ov.instructions if ov else None,
    )


@router.get("/agents/models", response_model=list[str])
def list_models(agent_id: str | None = None) -> list[str]:
    """Return the model allowlist. ``agent_id`` is accepted (and forwarded)
    for call-site stability, but every agent currently gets the same list."""
    return _allowed(agent_id)


@router.get("/agents/models/options", response_model=list[ModelOption])
def list_model_options(agent_id: str | None = None) -> list[ModelOption]:
    """The ``/agents/models`` allowlist (same ids, same order) annotated with
    provider, route and a display label so the UI can group it."""
    return [ModelOption(**o) for o in _model_options_for(agent_id)]


def _is_known_agent(agent_id: str) -> bool:
    return agent_id == EXECUTIVE_ID or agent_id in _agent_registry()


class QualityPreset(BaseModel):
    id: PresetId
    label: str
    description: str
    # False when this install allows none of the preset's models.
    available: bool
    # The model the preset moves agents to on this install; null for
    # Balanced (each agent keeps its own default) or when unavailable.
    model: str | None = None


class QualityPresets(BaseModel):
    presets: list[QualityPreset]
    # The preset every agent matches, or null when the council is "Custom".
    active: PresetId | None
    # The preset most agents match, and the agents that differ from it.
    base: PresetId
    custom_agents: list[str]


# Agents whose calls never send thinking fields, so a preset leaves their
# deep-reasoning flag alone.
_NO_DEEP_REASONING = frozenset({EXECUTIVE_ID, "utility_fast"})


def _agent_states() -> list[AgentState]:
    states: list[AgentState] = []
    for name, agent in _agent_registry().items():
        ov = get_override(name)
        if name == EXECUTIVE_ID:
            model_default = _ExecutiveDefaults.model()
            deep_default = _ExecutiveDefaults.use_deep_reasoning
        else:
            model_default = agent.model
            deep_default = agent.use_deep_reasoning
        states.append(
            AgentState(
                agent_id=name,
                model_default=model_default,
                deep_default=deep_default,
                model_override=ov.model if ov is not None else None,
                deep_override=ov.use_deep_reasoning if ov is not None else None,
                uses_deep_reasoning=name not in _NO_DEEP_REASONING,
                core=agent.visibility == "core",
            )
        )
    return states


def _quality_presets() -> QualityPresets:
    allowed = _allowed()
    status_ = preset_status(_agent_states(), allowed=allowed)
    return QualityPresets(
        presets=[
            QualityPreset(
                id=pid,
                label=PRESETS[pid].label,
                description=PRESETS[pid].description,
                available=preset_available(pid, allowed),
                model=preset_model(pid, allowed),
            )
            for pid in PRESET_IDS
        ],
        active=status_.active,
        base=status_.base,
        custom_agents=status_.custom_agents,
    )


@router.get("/agents/presets", response_model=QualityPresets)
def list_presets() -> QualityPresets:
    """Fast, Balanced and Thorough, resolved against this install's model
    allowlist, plus which one the council is on."""
    return _quality_presets()


@router.post("/agents/presets/{preset_id}", response_model=QualityPresets)
def apply_preset(preset_id: str) -> QualityPresets:
    """Move every agent onto a preset by writing ordinary overrides.

    Only the model and deep-reasoning fields change; prompts, roles, voice
    and instructions stay as they are. Each agent that changes gets one
    history row, so a single agent can be rolled back on its own. An
    override left with nothing in it is removed, so Balanced returns an
    untouched agent to its plain defaults.
    """
    if preset_id not in PRESETS:
        raise HTTPException(status_code=404, detail="Unknown preset")
    pid: PresetId = PRESETS[preset_id].id
    allowed = _allowed()
    if not preset_available(pid, allowed):
        raise HTTPException(
            status_code=409,
            detail=f"The {PRESETS[pid].label} preset needs a model this install doesn't offer",
        )
    for write in writes_for(pid, _agent_states(), allowed=allowed):
        ov = get_override(write.agent_id)
        keeps_other_fields = ov is not None and any(
            v is not None
            for v in (
                ov.prompt,
                ov.role,
                ov.voice_persona_slug,
                ov.research_focus,
                ov.instructions,
            )
        )
        if write.model is None and write.deep is None and not keeps_other_fields:
            clear_override(write.agent_id)
            continue
        set_override(
            write.agent_id,
            model=write.model,
            use_deep_reasoning=write.deep,
            model_set=True,
            deep_set=True,
        )
    return _quality_presets()


@router.get("/agents", response_model=list[AgentMeta])
async def list_agents() -> list[AgentMeta]:
    # Executive is rendered first so the Council UI puts it at the top of
    # the list. Specialists follow in registry order. The registry includes
    # "executive" as a key (for detail/lookup paths), so skip it here to
    # avoid duplicating the Executive card.
    return [_build_executive_meta()] + [
        _build_meta(name) for name in _agent_registry() if name != EXECUTIVE_ID
    ]


@router.get("/agents/{agent_id}", response_model=AgentDetail)
def get_agent(agent_id: str) -> AgentDetail:
    if agent_id == EXECUTIVE_ID:
        return _build_executive_detail()
    if agent_id not in _agent_registry():
        raise HTTPException(status_code=404, detail="Unknown agent")
    return _build_detail(agent_id)


@router.patch("/agents/{agent_id}", response_model=AgentDetail)
def patch_agent(agent_id: str, patch: AgentPatch) -> AgentDetail:
    if not _is_known_agent(agent_id):
        raise HTTPException(status_code=404, detail="Unknown agent")

    raw = patch.model_dump(exclude_unset=True)
    if patch.model is not None and patch.model not in _allowed(agent_id):
        raise HTTPException(
            status_code=400,
            detail=f"Model {patch.model!r} is not in the allowed list",
        )

    if "pushback_model" in raw:
        if agent_id != EXECUTIVE_ID:
            raise HTTPException(
                status_code=400, detail="Only the Executive has a pushback model"
            )
        if patch.pushback_model not in (None, PUSHBACK_OFF) and (
            patch.pushback_model not in _allowed(agent_id)
        ):
            raise HTTPException(
                status_code=400,
                detail=f"Model {patch.pushback_model!r} is not in the allowed list",
            )

    if "voice_persona_slug" in raw and patch.voice_persona_slug is not None:
        from openexecutive.personas.loader import persona_exists
        if not persona_exists(patch.voice_persona_slug):
            raise HTTPException(
                status_code=400,
                detail=f"Voice persona {patch.voice_persona_slug!r} does not exist",
            )

    set_override(
        agent_id,
        prompt=patch.prompt,
        model=patch.model,
        use_deep_reasoning=patch.use_deep_reasoning,
        role=patch.role,
        voice_persona_slug=patch.voice_persona_slug,
        research_focus=patch.research_focus,
        # Blank text clears the field rather than storing an empty block.
        instructions=(
            patch.instructions
            if patch.instructions is not None and patch.instructions.strip()
            else None
        ),
        prompt_set="prompt" in raw,
        model_set="model" in raw,
        deep_set="use_deep_reasoning" in raw,
        role_set="role" in raw,
        voice_persona_slug_set="voice_persona_slug" in raw,
        research_focus_set="research_focus" in raw,
        instructions_set="instructions" in raw,
        pushback_model=patch.pushback_model,
        pushback_model_set="pushback_model" in raw,
    )
    return (
        _build_executive_detail()
        if agent_id == EXECUTIVE_ID
        else _build_detail(agent_id)
    )


@router.delete("/agents/{agent_id}/override", status_code=status.HTTP_204_NO_CONTENT)
def reset_agent(agent_id: str) -> Response:
    if not _is_known_agent(agent_id):
        raise HTTPException(status_code=404, detail="Unknown agent")
    clear_override(agent_id)
    return Response(status_code=status.HTTP_204_NO_CONTENT)


@router.get(
    "/agents/{agent_id}/history",
    response_model=list[AgentHistoryEntry],
)
def get_history(agent_id: str, limit: int = 50) -> list[AgentHistoryEntry]:
    if not _is_known_agent(agent_id):
        raise HTTPException(status_code=404, detail="Unknown agent")
    return list_history(agent_id, limit=limit)


@router.post(
    "/agents/{agent_id}/rollback/{history_id}",
    response_model=AgentDetail,
)
def rollback_agent(agent_id: str, history_id: int) -> AgentDetail:
    if not _is_known_agent(agent_id):
        raise HTTPException(status_code=404, detail="Unknown agent")
    restored = rollback_to(history_id)
    if restored is None or restored.agent_id != agent_id:
        raise HTTPException(status_code=404, detail="Unknown history entry")
    return (
        _build_executive_detail()
        if agent_id == EXECUTIVE_ID
        else _build_detail(agent_id)
    )


async def _test_executive(req: AgentTestRequest) -> str:
    """One-shot preview of the Executive's voice with a draft prompt.

    Bypasses the full orchestrator (tool use, specialists, RAG) — this is
    a single messages.create so the Council UI can preview how an edited
    persona reads, not a real chat turn.
    """
    from openexecutive.config import get_settings
    from openexecutive.providers import get_provider

    settings = get_settings()
    ov = get_override(EXECUTIVE_ID)
    prompt = (
        req.prompt
        if req.prompt is not None
        else (
            ov.prompt
            if ov is not None and ov.prompt is not None
            else _ExecutiveDefaults.prompt()
        )
    )
    prompt = append_instructions(
        prompt,
        req.instructions
        if req.instructions is not None
        else (ov.instructions if ov is not None else None),
    )
    model = (
        req.model
        if req.model is not None
        else (
            ov.model
            if ov is not None and ov.model is not None
            else settings.default_model
        )
    )
    message = await get_provider(model).messages_create(
        model=model,
        max_tokens=2048,
        system=[
            {
                "type": "text",
                "text": prompt,
                "cache_control": {"type": "ephemeral"},
            }
        ],
        messages=[{"role": "user", "content": req.query}],
    )
    log_model_usage(message, model=model, actor="agent_test")
    text_blocks = [b for b in message.content if b.type == "text"]
    return text_blocks[0].text if text_blocks else ""


@router.post("/agents/{agent_id}/test", response_model=AgentTestResponse)
async def test_agent(agent_id: str, req: AgentTestRequest) -> AgentTestResponse:
    """Run a one-off analyze() with the draft config — never persisted."""
    if req.model is not None and req.model not in _allowed(agent_id):
        raise HTTPException(
            status_code=400, detail=f"Model {req.model!r} is not in the allowed list"
        )
    if not req.query.strip():
        raise HTTPException(status_code=400, detail="query must not be empty")

    if agent_id == EXECUTIVE_ID:
        try:
            response = await _test_executive(req)
        except Exception as exc:  # noqa: BLE001
            logger.exception("Executive test failed")
            raise HTTPException(status_code=502, detail="Agent call failed") from exc
        return AgentTestResponse(response=response)

    registry = _agent_registry()
    agent = registry.get(agent_id)
    if agent is None:
        raise HTTPException(status_code=404, detail="Unknown agent")

    # Triage has its own non-`analyze` entry point; call analyze with the
    # draft anyway so the UI test box still works for it — it'll return a
    # plain text completion using the triage prompt.
    # The draft prompt and instructions win; whatever the draft leaves out
    # comes from the saved config, joined the way a real call joins them.
    ov = get_override(agent_id)
    system_prompt = append_instructions(
        req.prompt if req.prompt is not None else agent.base_system_prompt(),
        req.instructions
        if req.instructions is not None
        else (ov.instructions if ov is not None else None),
    )
    try:
        response = await agent.analyze(
            query=req.query,
            system_prompt_override=system_prompt,
            model_override=req.model,
            deep_reasoning_override=req.use_deep_reasoning,
            # Sandbox runs must not read as production specialist spend in
            # the /audit/usage by-source breakdown.
            actor="agent_test",
        )
    except Exception as exc:  # noqa: BLE001
        logger.exception("Agent test failed for %r", agent_id)
        raise HTTPException(status_code=502, detail="Agent call failed") from exc
    return AgentTestResponse(response=response)