---
id: SVC-PFM-LLM-console-agent
title: Jazz AI conversation routes
product_area: platform
module: llm
repository: react-console
source_module: 'react-console: app/api/agent/** with lib/agent/** (store, schemas, client, types)'
revision: 1
status: draft
design_intent: open
implementation_evidence: observed
source_sha:
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
owns:
  - DOM-PFM-LLM-005
does_not_own:
  - 'Queries and its workspace retain query interpretation, validation and saving.'
  - Record directories retain their filter state and record-owning module authority.
  - Live query generation consumes Queries and the metered Platform runtime.
  - Security retains authenticated identity; these routes themselves have no AI permission check.
inference:
  - IOP-PFM-LLM-001
operations:
  - operation_id: listAgentProjects (GET /api/agent/projects)
    intent: List sample-owner projects by name with active conversation counts.
    access: console
    permission: 'none: a session cookie must be present; no AI permission or organization AI switch is checked'
    realises:
      - CAP-PFM-LLM-019
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: createAgentProject (POST /api/agent/projects)
    intent: Create a validated named project with an optional short description.
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: 'updateAgentProject (PATCH /api/agent/projects/{id})'
    intent: Change an existing project’s name or description.
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: 'deleteAgentProject (DELETE /api/agent/projects/{id})'
    intent: Remove a project while retaining its conversations as unfiled.
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: listAgentConversations (GET /api/agent/conversations)
    intent: Search and list sample-owner conversations within the chosen project and archive filter.
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: createAgentConversation (POST /api/agent/conversations)
    intent: Create history or reuse and restore an existing matching scope with optional initial messages.
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
      - CAP-PFM-LLM-020
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: 'getAgentConversation (GET /api/agent/conversations/{id})'
    intent: Return a sample-owner conversation and its message history.
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: 'updateAgentConversation (PATCH /api/agent/conversations/{id})'
    intent: 'Change conversation title, filing, scope or archive marker.'
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: 'deleteAgentConversation (DELETE /api/agent/conversations/{id})'
    intent: Remove the selected conversation and its messages from memory.
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
  - operation_id: 'postAgentConversationMessages (POST /api/agent/conversations/{id}/messages)'
    intent: 'Append externally produced turns, or generate and append a general exchange for unscoped history.'
    access: console
    permission: 'none: a session cookie must be present'
    realises:
      - CAP-PFM-LLM-019
      - CAP-PFM-LLM-020
    published_to_submissions: 'not published: console prototype history routes have no configurable-intake binding'
events: []
jobs: []
integrations:
  - system: Model gateway through the AI SDK (configured model openai/gpt-4.1-mini)
    direction: outbound
    contract: >-
      A direct text-generation request uses recent messages and project guidance outside Platform admission,
      usage capture and organization switches.
consistency:
  - rule: Synchronous store mutations are visible to callers reaching the same process.
    kind: transactional
    compensation: There is no durable rollback or replication; restart recreates the sample store.
  - rule: General exchanges append only after the model request returns.
    kind: eventual
    compensation: Model failure appends no exchange; an ambiguous response or concurrent deletion is not repaired.
evidence:
  - >-
    react-console at baf6dae: app/api/agent/projects/route.ts, projects/[id]/route.ts, conversations/route.ts,
    conversations/[id]/route.ts, conversations/[id]/messages/route.ts; lib/agent/store.ts, schemas.ts,
    client.ts, types.ts, tenant.ts; proxy.ts (the session-cookie gate for data routes).
controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-005, TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Jazz AI conversation routes

## What This Service Is For

The console prototype supplies project browsing, conversation history and general model replies. Its ten method-and-route operations allow the page and header panel to work against one process’s memory.

## Boundary

Conversation and project records use the same fixed sample owner for every caller. The routes append refinements produced by other pages but do not interpret or save their work. General replies call the gateway directly. There is no workspace isolation, AI permission evaluation or organization-switch enforcement in these handlers.

## Operations in Words

Project operations create, read, edit and remove folders. Conversation operations search, create or reuse scope, read, rename, refile, archive, restore and delete history. The message operation either appends supplied turns or asks for an unscoped general reply. The operation identifiers here are contract labels for those routes, not declared OpenAPI identifiers in the console.

## Events and Jobs

These handlers declare no business events, queue consumers or scheduled jobs. They provide no Submissions publication.

## Consistency Guarantees

Changes apply immediately to process memory and disappear on restart. Separate instances retain different histories. Replies read context before generation and append afterward, allowing concurrent exchanges to miss each other’s questions. Durable ownership and customer access remain open design decisions.