SuperBizAgent-java/openspec/specs/single-react-diagnosis-agent/spec.md

single-react-diagnosis-agent Specification

Purpose

定义内部单体 Diagnosis ReactAgent 的极简输入、框架 ReAct/tool loop、Harness 模型与 Tool 边界、结构化 DiagnosisDraft、无证据停止、确定性预算和审计隔离要求。

Requirements

Requirement: Diagnosis execution SHALL use one framework ReactAgent

The internal diagnosis path SHALL create exactly one diagnosis_agent with the framework-provided ReAct/tool loop. It SHALL NOT create Planner, Executor, Verifier, Composer, SequentialAgent, SupervisorAgent, an outer business Graph, or a hand-written model/Tool loop. One use-case invocation SHALL call the Diagnosis Agent once and SHALL NOT wrap the Agent or any individual model call in Harness retry.

Scenario: Diagnosis needs Tool evidence

• WHEN the model emits one or more Tool actions before its final response
• THEN the same Diagnosis ReactAgent executes those actions through its framework loop and returns one final Draft without invoking another Agent

Scenario: Agent execution fails

• WHEN the single Diagnosis Agent invocation throws or returns invalid structured output
• THEN the internal use case fails closed without automatically invoking the Agent or model again

Requirement: Diagnosis input SHALL contain only current Query and optional PreviousTurn

The internal use case SHALL accept a non-blank current Query and an optional frozen PreviousTurn, serialize them as the fixed query and previous_turn input fields, and SHALL NOT load or accept complete Session history, Redis memory, prior raw Tool results, or model-generated history summaries. The current Query SHALL retain its original text and SHALL NOT be rewritten or silently truncated.

Scenario: Follow-up diagnosis has a safe previous turn

• WHEN a caller supplies a PreviousTurn
• THEN the Agent receives exactly the frozen previous-turn fields plus the current Query and no complete conversation history

Scenario: Query exceeds configured context budget

• WHEN the current Query exceeds its UTF-8 byte limit
• THEN the use case rejects it before any model call instead of truncating or rewriting it

Requirement: Every model round SHALL be controlled by RunContext

The Diagnosis Agent SHALL receive RunContext explicitly and SHALL use a model interceptor to call DiagnosisHarnessCore.beforeModelCall for every framework ReAct model round. Non-streaming model response Usage SHALL be recorded into the same Run budget when available. Cancellation, deadline, model-call exhaustion, or Token exhaustion SHALL prevent subsequent controlled work.

Scenario: ReAct performs two model rounds

• WHEN one model round requests a Tool and the next produces the Draft
• THEN the same Run budget records two model calls and no Harness retry attempt

Scenario: Model-call budget is exhausted

• WHEN the framework attempts a model round beyond the configured maximum
• THEN the call is rejected before reaching ChatModel and the Run records budget exhaustion

Requirement: Evidence Tools SHALL execute through the Harness boundary

The Diagnosis Agent SHALL expose only the frozen lookup_knowledge, query_logs, and query_mysql definitions. A Tool interceptor SHALL propagate the exact framework Tool Call ID, Run ID, Tool name, and raw JSON arguments into the corresponding stage 3B/3C adapter and ToolBoundary. Successful observations SHALL contain only the bounded agent_result; failed observations SHALL contain only stable error semantics and SHALL NOT contain raw responses, internal exceptions, credentials, or invocation lifecycle internals.

Scenario: Framework requests RAG evidence

• WHEN the model calls lookup_knowledge with framework ID call-1
• THEN the RAG adapter and Agent observation use exactly call-1, and the canonical invocation is owned by the current Run

Scenario: Tool execution fails

• WHEN a registered adapter returns an error result
• THEN the Agent receives evidence_status=ERROR, the framework Tool Call ID and a stable error code without automatic Tool retry or raw failure detail

Scenario: Unknown Tool is requested

• WHEN a model requests a Tool outside the three registered definitions
• THEN the Harness does not authorize or emulate it and does not create a canonical evidence record

Requirement: Diagnosis output SHALL be a bounded DiagnosisDraft

The Agent SHALL receive the generated schema for DiagnosisDraft and SHALL return JSON that the internal use case strictly parses into the frozen record. The use case SHALL enforce configured UTF-8 limits for query, previous turn, total input and Draft output and account accepted input/output bytes against the Run capacity. It SHALL reject blank, fenced, prefixed, malformed, oversized or schema-incompatible output without repair or retry.

Scenario: Supported Draft is returned

• WHEN the Agent returns valid JSON containing Conclusion, Analysis items, Action Plan, Recommendations and Limitations
• THEN the use case returns a DiagnosisDraft whose Analysis Tool Call IDs are the exact strings emitted by the Agent

Scenario: Model returns prose around JSON

• WHEN the final response contains a Markdown fence or explanatory prefix around an otherwise valid object
• THEN strict parsing fails and the Diagnosis Agent is not invoked a second time

Requirement: Insufficient evidence SHALL terminate without a fabricated conclusion

The single Prompt SHALL require every normal Analysis item to cite current-Run evidence Tool Call IDs and SHALL restrict NO_EVIDENCE to scoped NEGATIVE_OBSERVATION. If current evidence cannot support a diagnosis, the Agent SHALL stop the current ReAct execution with conclusion=null, describe the actual scope and missing information in limitations, and SHALL NOT infer that the problem does not exist or fabricate a root cause.

Scenario: Tool finds no evidence

• WHEN the only completed Tool observation has evidence_status=NO_EVIDENCE
• THEN the final Draft has no confirmed Conclusion, records the bounded negative observation and missing information, and makes no additional automatic retry

Requirement: Stage-four execution SHALL remain internal and auditable

The new use case SHALL be callable only as an internal Java/test entry in this stage and SHALL NOT be wired into public Chat or AIOps controllers. It SHALL propagate the same sessionId/runId through RunnableConfig metadata, allow the existing AgentStep Hook to be injected, retain ToolBoundary canonical invocation audit, and leave final Run success/persistence ownership to later Guard/application stages.

Scenario: Internal audited execution completes

• WHEN an injected audit Hook observes a model round and a Tool executes
• THEN both observe the same RunContext sessionId/runId and the public Chat call path remains unchanged

Scenario: Stage four is archived

• WHEN focused Agent tests pass and the change is archived
• THEN ChatController, public SSE behavior and the old multi-Agent implementation remain available for stages 5, 6A and 6B