agents

Handler for POST /api/v2/agents/agent_config - Per-agent UI config.

Code
Returns runtime UI configuration for an agent so the frontend can gate
features on the agent's real capabilities: whether the chat-history surface
should be shown (``history_enabled``) and whether the Jobs/Ingestion surface
should be shown (``jobs_enabled``).

Both flags are derived from a single read of the agent's behavior block
(see ``AIAgentService.get_ui_capabilities``).

``history_enabled`` reflects **durable** conversation memory, not just
recording. It is the AND of the agent's behavior flags:

- ``use_memory`` (env ``USE_MEMORY``) -- the agent records conversation
  turns at all; and
- ``ai_db_available`` -- DB-backed persistent storage is actually active,
  which on the agent side requires ``USE_PERSISTENT_STORAGE`` enabled AND a
  reachable ``AI_DB_HOST`` (the agent reports the effective storage state,
  not merely the config intent).

Recording without persistence is ephemeral (history would reset on restart),
so the drawer is hidden in that case as well.

``jobs_enabled`` reflects the agent's ``JOBS_ENABLED`` env (whether the async
job routes are mounted on the pod), so the frontend hides the
Jobs/Ingestion entry points instead of surfacing controls that would 404.

Both checks fail OPEN: a transient error, a partial config, or an older
agent that doesn't expose these flags yet leaves the features enabled; only
an explicit ``false`` from a reachable agent hides them.

Parameters
----------
agent : str, required
    Frontend agent key (e.g. 'lines', 'rules', 'insured').

Returns
-------
success : bool
    True if successful
data : dict
    {'history_enabled': bool, 'jobs_enabled': bool}

Handler for POST /api/v2/agents/agent_create_job - Create an async job.

Code
Parameters
----------
agent : str, required
    Frontend agent key ('lines' or 'rules').
job_name : str, required
prompt : str, required
context : dict, optional
files : list, optional

Handler for POST /api/v2/agents/agent_delete_job - Delete a job.

Code
Soft-deletes a terminal job (completed/failed/stopped) so it no longer
appears in the Jobs list. Active jobs must be stopped first (the agent
returns 409 otherwise).

Parameters
----------
agent : str, required
    Frontend agent key ('lines' or 'rules').
job_id : str, required

Handler for POST /api/v2/agents/agent_delete_session - Delete a session.

Code
Parameters
----------
agent : str, required
    Frontend agent key (e.g. 'lines', 'rules', 'quote').
session_id : str, required
    The session ID to delete

Returns
-------
success : bool
    True if successful
data : dict
    Deletion result

Handler for POST /api/v2/agents/agent_get_job - Fetch a single job.

Code
Parameters
----------
agent : str, required
    Frontend agent key ('lines' or 'rules').
job_id : str, required

Handler for POST /api/v2/agents/agent_list_jobs - List jobs.

Code
Parameters
----------
agent : str, required
    Frontend agent key ('lines' or 'rules').
status : str, optional
limit : int, optional (default 100)

Handler for POST /api/v2/agents/agent_rename_session - Rename a session.

Code
Parameters
----------
agent : str, required
    Frontend agent key (e.g. 'lines', 'rules', 'quote').
session_id : str, required
    The session ID to rename
title : str, required
    New title; stripped, must be non-empty (length bounded upstream)

Returns
-------
success : bool
    True if successful
data : dict
    Echo payload ``{session_id, title}``

Handler for POST /api/v2/agents/agent_resume_job - Resume a paused job.

Code
Parameters
----------
agent : str, required
    Frontend agent key ('lines' or 'rules').
job_id : str, required
message : str, optional
selected_option : str, optional
data : dict, optional

Handler for POST /api/v2/agents/agent_session_messages - Get session messages.

Code
Parameters
----------
agent : str, required
    Frontend agent key (e.g. 'lines', 'rules', 'quote').
session_id : str, required
    The session ID to retrieve messages for

Returns
-------
success : bool
    True if successful
data : list
    Array of message objects

Handler for POST /api/v2/agents/agent_sessions - List chat sessions.

Code
When ``claim_id`` is supplied the listing is scoped to sessions tagged
with that claim (entity_type='claim'), so the Claims Copilot history is
filtered to the claim the adjuster is viewing. Omitting it returns the
user's unscoped history, leaving all other agents unaffected.

Parameters
----------
agent : str, required
    Frontend agent key (e.g. 'lines', 'rules', 'quote', 'adjuster').
limit : int, optional
    Maximum number of sessions to return (default 100)
claim_id : str, optional
    Claim id to scope the listing to (Claims Copilot only).

Returns
-------
success : bool
    True if successful
data : list
    Array of session objects

Handler for POST /api/v2/agents/agent_status.

Code
Whether ``agent`` is turned on for the carrier and permitted for this user,
so a page can decide whether to draw it. Ungated: it reports only the
caller's own access.

Handler for POST /api/v2/agents/agent_stop_job - Stop an active job.

Code
Transitions a pending/running/paused job to 'stopped'. Terminal jobs
(completed/failed/stopped) get a 409 from the agent. Returns the updated
job so the UI can reflect the new status without a follow-up fetch.

Parameters
----------
agent : str, required
    Frontend agent key ('lines' or 'rules').
job_id : str, required

Handler for POST /api/v2/agents/claims - Non-streaming chat.

Code
Authentication is handled by the @requires_permission decorator.
The api_key should be passed for authentication (typically via header or form).

Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information
files : list, optional
    Files to upload (multipart form data)

Returns
-------
success : bool
    True if successful
messages : list[str]
    List of human-readable messages
data : dict
    Response from AI agent with 'response' and 'session_id'

Handler for POST /api/v2/agents/claims_analytics - Non-streaming chat.

Code
Claims Analytics is the Claims Analytics Copilot that provides insights
and analysis based on claims data.

Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Context data (JSON string with metrics, filters, claims data, etc.)
files : list, optional
    Files to upload (multipart form data)

Returns
-------
success : bool
    True if successful
messages : list[str]
    List of human-readable messages
data : dict
    Response from AI agent with 'response', 'session_id', and 'metadata'

Handler for POST /api/v2/agents/claims_analytics_stream - SSE streaming chat.

Code
Claims Analytics is the Claims Analytics Copilot that provides streaming
insights and analysis based on claims data.

Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Context data (JSON string with metrics, filters, claims data, etc.)

Returns
-------
SSE stream with events: start, content, metadata, done, error

Handler for POST /api/v2/agents/claims_stream - SSE streaming chat.

Code
Authentication is handled by the @requires_permission decorator.
The api_key should be passed for authentication (typically via header or form).

Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information

Returns
-------
SSE stream with events: start, content, metadata, done, error

Handler for POST /api/v2/agents/documents_templates - Non-streaming chat.

Code
Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information
files : list, optional
    Files to upload (multipart form data)

Returns
-------
success : bool
    True if successful
messages : list[str]
    List of human-readable messages
data : dict
    Response from AI agent with 'response' and 'session_id'

Handler for POST /api/v2/agents/documents_templates_carbone_context.

Code
Returns the Carbone context the Documents and Forms Copilot should reason
over. Used by the bc-documents-templates MCP server's get_carbone_context
tool - the MCP is a thin proxy; this endpoint is the source of truth for
both the data shape and the calculated-field schema.

Authenticated via the standard `api_key` parameter; the MCP authenticates
using its service key (MCP_BRITECORE_API_KEY / MCP_CONTACT_API_KEY) wired
through bc_common.britecore_client.

Behavior:
- If `entity_number` is provided: live mode. The same SQLRunner-derived
  context that would be used at production render time is returned,
  with `apply_calculated_fields()` already applied.
- If `entity_number` is absent: example mode. The canonical example
  context shipped with BriteCore is returned, also with calculated
  fields applied so values appear under `calculated.*`. When a policy
  type is selected (`policy_type_name` [+ `location_id`]), the fixture's
  static line items are replaced by items generated from that policy
  type's configured items - real names, sections, limit/deductible
  columns, rating categories and rate variables, with synthesized
  amounts - so the copilot maps against coverages the site actually has.

In both modes, a `_schema` map is attached describing fields whose
meaning isn't obvious from their key name (date zoo, display/raw money
pairs, dec/status family, calculated fields). Calc-field descriptions
are merged on top of the static BriteCore context schema and keyed by
path (e.g. `calculated.tax_total`, `drivers[i].calculated.age`).

Parameters
----------
entity_number : str, optional
    Policy or claim number. When present, fetches live data.
entity_type : str, optional
    'policy' or 'claim'. Defaults to 'policy'. Only used in live mode.
deliverable_id : str, optional
    XReportLocation id of the deliverable being authored. Drives the
    calculated-field scope; falls back to globals only when missing.
policy_type_name : str, optional
    The Carbone-template page's policy-type dropdown selection. Resolves
    the policy type when no `entity_number` is given, which is what
    drives both the item-name catalog and the generated example items.
location_id : str, optional
    The business-location dropdown selection, narrowing
    `policy_type_name` to one location. Without it, a name matching
    several locations resolves to all of them.

Returns
-------
dict
    success : bool
    data : dict
        context : dict (Carbone context with `calculated.*` populated)
        _schema : dict (path-to-description map; static + calc-field
            descriptions merged)

Handler for GET /api/v2/agents/documents_templates_download - File download proxy.

Code
Fetches a file generated by the Documents and Forms Copilot and streams it
back to the browser. Used to download generated DOCX templates and rendered PDFs.

Authentication is handled by the @requires_permission decorator.
The api_key should be passed for authentication (typically via query parameter).

Parameters
----------
session_id : str, required
    The agent session ID (returned in the SSE start event)
filename : str, required
    The file to download (e.g., 'document_template.docx')

Returns
-------
bytes
    Binary file content with Content-Type and Content-Disposition headers

Raises
------
BCServiceError
    If session_id or filename is missing, contains path traversal characters,
    or the agent is unreachable

Handler for POST /api/v2/agents/documents_templates_stream - SSE streaming chat.

Code
Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information

Returns
-------
SSE stream with events: start, token/content, tool_execution, interrupt (HITL), metadata, done, error

Handler for POST /api/v2/agents/fnol - Non-streaming chat.

Code
Authentication is handled by the @requires_permission decorator.
The api_key should be passed for authentication (typically via header or form).

Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information
files : list, optional
    Files to upload (multipart form data)

Returns
-------
success : bool
    True if successful
messages : list[str]
    List of human-readable messages
data : dict
    Response from AI agent with 'response' and 'session_id'

Handler for POST /api/v2/agents/fnol_stream - SSE streaming chat.

Code
Authentication is handled by the @requires_permission decorator.
The api_key should be passed for authentication (typically via header or form).

Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information

Returns
-------
SSE stream with events: start, content, metadata, done, error

Handler for POST /api/v2/agents/init_quote_session - Initialize quote session.

Code
Proxies to AIAgents POST /quote/sessions/init, which creates the session,
seeds the agent workspace with the form data, stores the uploads, and
schedules the background turns that read the documents and rate the quote.

Create Quote sends this once, as multipart form data: the form fields JSON
under ``data``, and the agent's documents as repeated ``files`` parts.

Parameters
----------
state : str, required
    US state or Canadian province abbreviation (e.g. 'TX')
policy_type_id : str, required
    UUID of the selected policy type
policy_type_name : str, optional
    Display name of the selected policy type (e.g. 'Standard Auto Policy')
policy_type_kind : str, optional
    The policy type's kind: 'Property', 'Auto' or 'Umbrella'
underlying_policy_ids : list[str], optional
    Umbrella only: the one policy the quote sits on. Forwarded with an
    ``underlying`` summary of what linking it copies into the quote.
line_name : str, optional
    Name of the selected line/product group (e.g. 'Personal Auto')
effective_date : str, required
    Policy effective date in YYYY-MM-DD format
term_type : str, optional
    Policy term selected by agent (e.g. '1 Year', '6 Months')
knockout_answers : list, optional
    List of underwriting question answers [{questionId, yesNoAnswer, explanation}]

Returns
-------
success : bool
    True if successful
data : dict
    session_id: str - UUID of the created session
    filenames: list[str] - the documents stored by this call
    pdf_filename: str - the first PDF stored, when there is one
    file_errors: list[str] - per-file failures; the session still opens

Handler for POST /api/v2/agents/lines - Non-streaming chat.

Code
Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information
files : list, optional
    Files to upload (multipart form data)

Returns
-------
success : bool
    True if successful
messages : list[str]
    List of human-readable messages
data : dict
    Response from AI agent with 'response' and 'session_id'

Handler for POST /api/v2/agents/lines_stream - SSE streaming chat.

Code
Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information

Returns
-------
SSE stream with events: start, content, metadata, done, error

Handler for POST /api/v2/agents/quote - Non-streaming chat.

Code
Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information
files : list, optional
    Files to upload (multipart form data)

Returns
-------
success : bool
    True if successful
messages : list[str]
    List of human-readable messages
data : dict
    Response from AI agent with 'response' and 'session_id'

Handler for GET /api/v2/agents/quote_context - Fetch the live quote preview for a session.

Code
Proxies to AIAgents ``GET {quote-endpoint}/quote/sessions/{session_id}/context``, which returns
the extracted-quote context plus a ``preview`` projection (named insured, drivers, vehicles,
coverages, estimated premium) of the session's ``quote.json``.

The Create-Quote left-side live preview (BC-23114) is fed from this request/response endpoint
rather than SSE: the extraction/"present" turns run in the background (the UI polls for them), so
no streaming ``quote_preview`` event reaches the browser. Fetching the projected context on demand
(after background processing and after each turn) keeps the preview in sync regardless of how a
given turn was delivered.

Parameters
----------
session_id : str, required
    UUID of the quote Copilot session.

Returns
-------
dict
    The AIAgents context payload, including ``preview`` (None until ``quote.json`` exists).

Handler for GET /api/v2/agents/quote_processing_status - Check background processing.

Handler for POST /api/v2/agents/quote_stream - SSE streaming chat.

Code
Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information

Returns
-------
SSE stream with events: start, content, metadata, done, error

Handler for POST /api/v2/agents/report_copilot - Non-streaming chat.

Code
Pattern parity with the other agents. The Report Copilot frontend uses
the streaming variant (``report_copilot_stream``); this endpoint is
available for non-streaming clients and follows the canonical multipart
file-upload shape (plural ``files``).

Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information (sheet query + last error)
files : list, optional
    Files to upload (canonical multipart form-data with plural ``files``)

Returns
-------
success : bool
    True if successful
messages : list[str]
    List of human-readable messages
data : dict
    Response from AI agent with 'response', 'session_id', and 'metadata'

Handler for POST /api/v2/agents/report_copilot_attach_entity.

Code
Attach an opaque ``(entity_type, entity_id)`` tag to an existing
Report Copilot conversation. Idempotent on the AIAgents side via
``INSERT IGNORE``: re-attaching the same triple is a no-op.

Used by ``sqlEditor.js`` after a brand-new report is saved to wire
the session that started before the save (orphan conversation) to
the freshly-minted report id.

Parameters
----------
session_id : str, required
    The session id to attach to.
entity_type : str, required
    Opaque entity type (e.g. ``'report'``).
entity_id : str, required
    Opaque entity id (e.g. the BriteCore report uuid).

Returns
-------
success : bool
    True on a 201 response from the agent service.
data : dict
    Echo payload ``{session_id, entity_type, entity_id, inserted}``.

Handler for POST /api/v2/agents/report_copilot_capabilities.

Code
Returns the report-agent runtime capabilities so the SQL Editor can adapt
its UI to whichever agent the site is actually running: the deep-agent
Report Copilot (a single unified answer/build flow, a machine-readable
delivery envelope, a plan-approval interrupt) or the classic orchestrated
agent (explicit Explore/Build modes). The frontend reads this once at init
rather than assuming from a deployment env var it cannot see.

Proxies the agent's ``GET /`` capability block; any failure degrades to
``classic`` so a slow or unreachable agent never hides UI controls.

Returns
-------
success : bool
    True (the probe always resolves; failures fall back to ``classic``).
data : dict
    ``{report_agent_kind, unified_explore_build, delivers_report_envelope,
    uses_plan_interrupt}``.

Handler for POST /api/v2/agents/report_copilot_client_error.

Code
Counts an error the Report Copilot UI displayed.

A missing ``error_class`` is a 400: the caller is required to say what it
rendered, and coercing that away would hide a frontend bug. An *unrecognised*
one is recorded as ``other``, so a frontend that adds a site before the
backend knows about it still counts.

Returns the tags actually recorded, which differ from those sent when a value
is coerced.

Handler for POST /api/v2/agents/report_copilot_delete_session - Delete a session.

Code
Parameters
----------
session_id : str, required
    The session ID to delete

Returns
-------
success : bool
    True if successful
data : dict
    Deletion result

Handler for POST /api/v2/agents/report_copilot_rename_session - Rename a session.

Code
Replaces the auto-generated title with a user-supplied one. Proxies
``PATCH {report-copilot-endpoint}/sessions/{session_id}`` body
``{"title": ...}``; ownership enforced upstream. Called by ``sqlEditor.js``
inline rename in the history drawer.

Parameters
----------
session_id : str, required
    The session id to rename.
title : str, required
    New title; stripped, must be non-empty (length bounded upstream).

Returns
-------
success : bool
    True on a 200 response from the agent service.
data : dict
    Echo payload ``{session_id, title}``.

Handler for POST /api/v2/agents/report_copilot_session_messages - Get session messages.

Code
Parameters
----------
session_id : str, required
    The session ID to retrieve messages for

Returns
-------
success : bool
    True if successful
data : list
    Array of message objects

Handler for POST /api/v2/agents/report_copilot_session_state - Get UI-restore state.

Code
Proxies ``GET {report-copilot-endpoint}/sessions/{session_id}/state`` so
the sqlEditor.js frontend can redraw the Report Copilot UI (phase pills,
report plan, per-sheet SQL, validation flags) when a user reloads or
switches conversations. Without this the only thing the UI gets on
resume is the message list, and the timeline / SQL state stays empty
until the next user-initiated message produces fresh SSE chunks.

Parameters
----------
session_id : str, required
    The session ID to retrieve UI state for.

Returns
-------
success : bool
    True on a 200 response from the agent service.
data : dict
    Pass-through of the agent service envelope:
    ``{session_id, agent_name, state, source}``. ``source`` is
    ``"extractor"`` when the Report Agent's ``aget_state_for_request``
    hook returned the variant-A2 payload, or ``"fallback"`` when only
    conversation metadata is available.

Handler for POST /api/v2/agents/report_copilot_sessions - List chat sessions.

Code
Parameters
----------
limit : int, optional
    Maximum number of sessions to return (default 100)
entity_type : str, optional
    Restrict listing to conversations attached to ``(entity_type,
    entity_id)`` (e.g. ``'report'``). Must be supplied with
    ``entity_id``; supplying only one is silently treated as no filter.
entity_id : str, optional
    Paired with ``entity_type``; the opaque external entity id (e.g.
    a saved report's id).

Returns
-------
success : bool
    True if successful
data : list
    Array of session objects (each with an inline ``entities`` array)

Handler for POST /api/v2/agents/report_copilot_stream - SSE streaming chat.

Code
Accepts the three request shapes the SQL editor frontend sends:

- JSON body, no file (plain chat / sheet context).
- JSON body with ``file_base64`` (file plus sheet context).
- Multipart ``FormData`` with singular ``file`` field (file, no sheet).

Emits the SSE event types the ``sqlEditor.js`` frontend consumes:
``start``, ``content``, ``tool_execution``, ``planning_complete`` (with
``report_plan``), ``agent_state`` (with ``agent_mode`` and
``current_phase``), ``done``, and ``error``.

Parameters
----------
prompt : str, required (or file)
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context (sheet query + last error)
initial_state_params : dict or JSON string, optional
    Structured per-agent state seed (e.g. ``{"agent_mode": "build"}``)
file_base64 : str, optional (JSON requests only)
    Base64-encoded file payload, with or without ``data:`` URL prefix
file_name : str, optional (JSON requests only)
    Filename for the base64 upload (default ``uploaded_file``)
file_type : str, optional (JSON requests only)
    MIME type for the base64 upload (default ``application/octet-stream``)

Returns
-------
SSE stream with events: start, content, tool_execution, planning_complete,
agent_state, done, error

Handler for POST /api/v2/agents/rules - Non-streaming chat.

Code
Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information
files : list, optional
    Files to upload (multipart form data)

Returns
-------
success : bool
    True if successful
messages : list[str]
    List of human-readable messages
data : dict
    Response from AI agent with 'response' and 'session_id'

Handler for POST /api/v2/agents/rules_stream - SSE streaming chat.

Code
Parameters
----------
prompt : str, required
    The user's message/question
session_id : str, optional
    Session ID for conversation continuity
context : str, optional
    Additional context information

Returns
-------
SSE stream with events: start, content, metadata, done, error