ZoomProp

Document agents

Document agents

Last updated 5/3/2026

Document Agents

This document stores the source context for the Document Agents metric within the ZoomProp AI platform (zoomprop/zp-alpha).

Definition

FieldValue
KPI-IDKPI-001
Sourcesrc/app/api/ai/conversations/route.ts, src/app/api/ai/conversations/[id]/route.ts, src/app/api/ai/chat/route.ts, src/app/api/ai/personas/route.ts
OwnerAI Platform Team
FrequencyReal-time (per-request); aggregated daily via src/app/api/ai/performance-monitoring/route.ts

What It Measures

Document Agents tracks the count of active AI agent instances that are processing, generating, or responding to document-oriented tasks within the ZoomProp platform. In the context of zoomprop/zp-alpha, document agents include any LangChain- or LangGraph-backed agent invocations (via @langchain/langgraph ^0.3.5, @langchain/core ^0.3.61, and @langchain/openai ^0.5.16) that produce structured output tied to a persistent conversation or analysis artifact.

Concretely, a document agent is instantiated whenever one of the following routes handles a request that creates or appends to a named AI artifact:

  • /api/ai/chat (src/app/api/ai/chat/route.ts) — conversational agent sessions backed by @ai-sdk/openai ^2.0.30 and @ai-sdk/react ^2.0.72; each session correlates to an entry in the conversations store at /api/ai/conversations.
  • /api/ai/analysis (src/app/api/ai/analysis/route.ts) — general property analysis documents generated per property investigation.
  • /api/ai/property-analysis (src/app/api/ai/property-analysis/route.ts) and /api/ai/commercial-analysis (src/app/api/ai/commercial-analysis/route.ts) — specialist agents producing structured investment reports validated against the CapRateCalculationSchema defined in the database schema layer (fields: constMonthlyRent, constVacancy, constOperExpenses, constResEstimate, constClosingCosts, listPrice).
  • /api/ai/maintenance-analysis (src/app/api/ai/maintenance-analysis/route.ts) and /api/ai/property-inspection-analysis (src/app/api/ai/property-inspection-analysis/route.ts) — document agents that produce maintenance and inspection reports anchored to a property record.
  • /api/ai/offer-analysis (src/app/api/ai/offer-analysis/route.ts) — deal-document agents generating offer evaluation summaries.
  • /api/actions/analyze-property-investigation (src/app/api/actions/analyze-property-investigation/route.ts) — orchestrator agent that chains multiple sub-agents and emits a consolidated investigation document.
  • /api/ai/generate-title (src/app/api/ai/generate-title/route.ts) — lightweight agent invoked at conversation creation time to title a document artifact.

Agent lifecycle is tracked through conversation records managed at /api/ai/conversations and /api/ai/conversations/:id. Performance telemetry for all agents flows through /api/ai/performance-monitoring, which feeds the KPI dashboard at /api/analytics-dashboard and the analytics performance endpoint /api/analytics/performance.

The metric counts agents in three states:

  1. Active — agent is currently processing a request (streaming or awaiting LLM response via @langchain/langgraph).
  2. Idle — agent has completed its last task but its conversation context is still alive in the conversations store.
  3. Terminated — conversation record has been closed or the session expired.

Observability is instrumented via @opentelemetry/api ^1.9.0, @opentelemetry/core ^2.0.1, and @opentelemetry/sdk-trace-base ^2.0.1. Spans are emitted per agent invocation and correlated to a conversationId foreign key.

Test coverage for agent routes is exercised in tests/api/chat/route.test.ts and src/lib/ai/__tests__/portfolio-context-analysis.test.ts. The CI pipeline enforces this via .github/workflows/test-coverage.yml and .github/workflows/test.yml.

Thresholds

LevelValueAction
Healthy≤ 50 concurrent active document agentsNo action required; normal operating range for the current LangGraph orchestration layer.
Warning51–100 concurrent active document agentsPage the AI Platform Team; inspect /api/ai/performance-monitoring for latency spikes; review OpenTelemetry traces for stuck spans; consider rate-limiting /api/ai/chat and /api/actions/analyze-property-investigation.
Critical> 100 concurrent active document agents OR agent error rate > 5% over a 5-minute windowTrigger incident response; enforce request queuing at the Next.js API layer; scale the zp-fetch-service container (zp-fetch-service/Dockerfile); alert via Knock (@knocklabs/node ^1.11.1) using the /api/alerts/trigger route; escalate to on-call engineer.

Related IDs

  • BR-001 — Business requirement: AI-assisted property analysis must produce persisted document artifacts per session.
  • BR-002 — Business requirement: Unpaid users receive a monthly free query grant (see commit 3a74c26, /api/ free-query context), capping agent invocations per billing tier.
  • MON-001 — Monitoring hook: @opentelemetry/sdk-trace-base span instrumentation on all /api/ai/* routes, aggregated at /api/ai/performance-monitoring.
  • MON-002 — CI alert workflow: .github/workflows/alert-testing.yml validates that Knock-based agent failure notifications reach /api/alerts/trigger and /api/alerts/configure.
  • UJ-001 — User journey: Investor opens chat shell → /api/ai/chat instantiates a document agent → agent persists artifact via /api/ai/conversations → conversation title generated by /api/ai/generate-title → user reviews analysis document in dashboard.
  • UJ-002 — User journey: Property investigation initiated from the Discover page → /api/actions/analyze-property-investigation orchestrates sub-agents (property-analysis, commercial-estimates, offer-analysis) → consolidated document written to conversation record → user notified via /api/alerts/trigger.
  • API-001 — /api/ai/conversations (src/app/api/ai/conversations/route.ts)
  • API-002 — /api/ai/performance-monitoring (src/app/api/ai/performance-monitoring/route.ts)
  • API-003 — /api/actions/analyze-property-investigation (src/app/api/actions/analyze-property-investigation/route.ts)
  • TEST-001 — tests/api/chat/route.test.ts
  • TEST-002 — src/lib/ai/__tests__/portfolio-context-analysis.test.ts
  • TECH-001 — @langchain/langgraph ^0.3.5 (agent orchestration runtime)
  • TECH-002 — @opentelemetry/sdk-trace-base ^2.0.1 (agent telemetry)
  • TECH-003 — @knocklabs/node ^1.11.1 (agent failure notification delivery)