Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion docs/prd/current/06-diagnostic-agent-tool-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -693,9 +693,22 @@ interface ToolObservation {
정본 경계에서는 정제되고 정규화된 관찰 결과만 전달한다. 위 `rawResult` 분기는
PR #11 시제품의 진단 Tool message 경로를 설명하며 정본 인계 허용을 뜻하지 않는다.

### 수동 진단 실행 기록 시제품 (#14)

현재 시제품의 `DiagnosisHandoff`는 AMDC가 순번, `tool_call_id`, 도구 입력,
원천 어댑터의 제한된 결과 또는 정제된 오류를 기록하고, 모델이 기존 호출 ID에
선택적 `observation`·`hypothesis`·`limitation` comment를 연결한 내부 산출물이다.
실행 기록은 모델이 재작성하지 않으며 미존재·중복·자기 참조 ID를 거부한다.
도구 호출이 없으면 `completion_reason`은 `insufficient_evidence`로 고정한다.
이는 현재 `/diagnose`의 임시 표시 및 JSON 첨부를 위한 시제품 출력이다.
원시 결과를 포함할 수 있으므로 정본 `ReportAgentInputV1`, 정본 Evidence,
영속 Report 또는 영속화된 리포트 전용 Discord 전달에 직접 연결하지 않는다.
그 연결에는 PRD 02/03/06의 정제·정규화·검증 어댑터가 별도로 필요하다.

### 진단 에이전트 출력

진단 에이전트는 DiagnosisResult를 반환한다.
아래 `DiagnosisResult`는 정본 인계에 요구되는 계약이다. 현재 수동 진단
시제품은 위 `DiagnosisHandoff`를 반환하며 이 정본 계약의 구현 완료를 뜻하지 않는다.

~~~ts
interface DiagnosisResult {
Expand Down
2 changes: 2 additions & 0 deletions docs/prd/current/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
리포트 전달 계약 게이트 상태: ready_for_implementation
라이브 소스 게이트 상태: ready_for_design
전달 상태: not_started
수동 진단 시제품: 실행 기록과 선택적 comment를 `DiagnosisHandoff`로 조립한다.
원시 결과를 포함할 수 있어 정본 Report Agent 입력·영속 Report의 완료 증거가 아니다.
아키텍처 결정일: 2026-07-07
최종 검토: 2026-09-11 (리뷰 보정안, 팀 승인 대기)

Expand Down
15 changes: 13 additions & 2 deletions src/adapters/discord/bot.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import {
import type { AppConfig } from "../../config/env.js";
import { runDiagnosis } from "../../app/run-diagnosis.js";
import { buildDiagnoseCommand } from "./commands.js";
import { formatDiagnosticPresentation } from "./format-report.js";
import { formatDiagnosticPresentationMessages } from "./format-report.js";
import {
toSafeErrorMetadata,
type SafeErrorMetadata
Expand Down Expand Up @@ -78,7 +78,18 @@ async function handleDiagnoseCommand(
}
);

await interaction.editReply(formatDiagnosticPresentation(result.presentation));
const messages = formatDiagnosticPresentationMessages(result.presentation);
await interaction.editReply({
content: messages[0],
files: [{
attachment: Buffer.from(JSON.stringify(result.presentation, null, 2), "utf8"),
name: "amdc-diagnosis.json"
}],
allowedMentions: { parse: [] }
});
for (const content of messages.slice(1)) {
await interaction.followUp({ content, allowedMentions: { parse: [] } });
}
} catch (error) {
const safeError = toSafeDiagnosticError(error);
console.error("Failed to handle /diagnose interaction", safeError);
Expand Down
67 changes: 49 additions & 18 deletions src/adapters/discord/format-report.ts
Original file line number Diff line number Diff line change
@@ -1,30 +1,61 @@
import type { DiagnosticPresentation } from "../../report/types.js";

export function formatDiagnosticPresentation(presentation: DiagnosticPresentation): string {
const actions = presentation.recommendedActions
.map((action, index) => `${index + 1}. ${action}`)
.join("\n");
return truncateDiscordMessage(buildMessage(presentation));
}

export function formatDiagnosticPresentationMessages(presentation: DiagnosticPresentation): string[] {
const chunks: string[] = [];
let current = "";
for (const line of buildMessage(presentation).split("\n")) {
if (current.length + line.length + 1 > 1900 && current) {
chunks.push(current);
current = "";
}
let rest = line;
while (rest.length > 1900) {
const boundary = rest.lastIndexOf(" ", 1900);
const cut = boundary > 0 ? boundary : 1900;
chunks.push(rest.slice(0, cut));
rest = rest.slice(cut);
}
current += (current ? "\n" : "") + rest;
}
if (current) chunks.push(current);
return chunks;
}

function buildMessage(presentation: DiagnosticPresentation): string {
const message = [
"## AMDC Diagnostic Agent Result",
"",
`**Status:** ${presentation.status}`,
`**Summary:** ${presentation.summary}`,
`**Suspected Cause:** ${presentation.suspectedCause}`,
"",
"**Recommended Actions**",
actions
"## AMDC 진단 인계 자료", "",
`진단 ID: ${presentation.diagnosis_id}`,
`요청: ${presentation.request}`,
`종료 사유: ${presentation.completion_reason}`,
"전체 구조화 결과: amdc-diagnosis.json 첨부 파일",
...presentation.observations.flatMap(call => [
"", `**${call.seq}. ${call.plugin} / ${call.tool}**`,
`호출 ID: ${call.tool_call_id}`,
`조회 시각: ${call.observed_at} · 실행 상태: ${call.status}`,
`입력: ${JSON.stringify(call.input)}`,
`결과: ${resultPreview(call.result)}`,
...(call.error ? [`실행 오류: ${call.error.code} — ${call.error.message}`] : []),
...(call.comment?.observation ? [`관찰 comment: ${call.comment.observation}`] : []),
...(call.comment?.hypothesis ? [`가설 comment: ${call.comment.hypothesis}`] : []),
...(call.comment?.limitation ? [`한계 comment: ${call.comment.limitation}`] : []),
...(call.related_call_ids.length ? [`관련 호출: ${call.related_call_ids.join(", ")}`] : [])
]),
...(!presentation.observations.length ? ["", "도구 실행 결과 없음. 정상 판정을 의미하지 않습니다."] : [])
].join("\n");
return message;
}

return truncateDiscordMessage(message);
function resultPreview(result: unknown): string {
const text = JSON.stringify(result);
return text.length <= 600 ? text : text.slice(0, 600) + " … [표시 생략: 전체 결과는 JSON 첨부에 보존]";
}

function truncateDiscordMessage(message: string): string {
const maxLength = 1900;

if (message.length <= maxLength) {
return message;
}

return `${message.slice(0, maxLength)}\n\n...truncated`;
const notice = "\n\n… 표시 길이를 초과했습니다. 전체 조사 내용은 진단 결과에 보존됩니다.";
return message.length <= maxLength ? message : message.slice(0, maxLength - notice.length) + notice;
}
141 changes: 26 additions & 115 deletions src/agent/langchain-diagnostic-agent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,26 +8,16 @@ import {
} from "../observability/diagnostic-trace.js";
import { toSafeErrorMetadata } from "../observability/safe-error-metadata.js";
import { PluginRegistry } from "../tools/plugin-registry.js";
import type {
ObservationStatus,
RawToolResult,
PluginName,
SanitizedToolError,
ToolObservation,
ToolRuntime
} from "../tools/types.js";
import { isPluginName } from "../tools/types.js";
import type { ToolRuntime } from "../tools/types.js";
import { assertSafeHandoffData, DiagnosisLedger } from "../report/diagnosis-handoff.js";
import {
type AgentDiagnosisResult,
type DiagnosticAgentInput,
type DiagnosticAgentPort,
type InferredDomain,
type PreliminaryFinding,
type SuspectedCause
type DiagnosticAgentPort
} from "./types.js";
import { createAmdcLangChainTools } from "./langchain-tool-wrapper.js";
import { createPluginLazyLoadingMiddleware } from "./plugin-lazy-loading.js";
import { type DiagnosisDraft, diagnosisDraftSchema } from "./langchain-schemas.js";
import { diagnosisDraftSchema } from "./langchain-schemas.js";

export interface LangChainDiagnosticAgentOptions {
readonly model: string;
Expand All @@ -44,7 +34,9 @@ export class LangChainDiagnosticAgent implements DiagnosticAgentPort {
) {}

async diagnose(input: DiagnosticAgentInput): Promise<AgentDiagnosisResult> {
const runId = randomUUID();
assertSafeHandoffData(input);
const runId = `diag-${randomUUID()}`;
const ledger = new DiagnosisLedger(runId);
const startedAt = Date.now();
const traceSink = this.options.traceSink ?? new NoopDiagnosticTraceSink();
const referenceTime = new Date(input.receivedAt);
Expand All @@ -66,9 +58,10 @@ export class LangChainDiagnosticAgent implements DiagnosticAgentPort {
const tools = createAmdcLangChainTools(toolDescriptors, this.toolRuntime, {
environment: input.environment,
referenceTime,
disabledTools,
runId,
traceSink
traceSink,
ledger,
disabledTools
});
const pluginMiddleware = createPluginLazyLoadingMiddleware(this.registry, {
runId,
Expand Down Expand Up @@ -108,32 +101,14 @@ export class LangChainDiagnosticAgent implements DiagnosticAgentPort {
errorStage = "structured_response_validation";
const draft = diagnosisDraftSchema.parse(result.structuredResponse);
errorStage = "diagnosis_assembly";
const toolArtifacts = extractToolArtifacts(result.messages);
const diagnosis = {
symptom: input.symptom,
environment: input.environment,
inferredDomains: toInferredDomains(draft),
selectedTools: toolDescriptors.filter((descriptor) =>
toolArtifacts.toolNames.has(descriptor.name)
),
observations: toolArtifacts.observations,
rawResults: toolArtifacts.rawResults,
toolErrors: toolArtifacts.toolErrors,
preliminaryFindings: toPreliminaryFindings(draft),
suspectedCauses: toSuspectedCauses(draft),
recommendedChecks: draft.recommendedChecks,
incompleteReasons: [
...draft.incompleteReasons,
...toolArtifacts.toolErrors.map((error) => `${error.toolName}: ${error.message}`)
]
} satisfies AgentDiagnosisResult;
const diagnosis = ledger.assemble(input.symptom, draft);

await traceSink.record({
event: "diagnosis.completed",
runId,
occurredAt: new Date().toISOString(),
durationMs: Date.now() - startedAt,
selectedTools: diagnosis.selectedTools.map((tool) => tool.name)
selectedTools: [...new Set(diagnosis.observations.map((call) => call.tool))]
});

return diagnosis;
Expand All @@ -155,7 +130,13 @@ export class LangChainDiagnosticAgent implements DiagnosticAgentPort {
function buildSystemPrompt(environment: AmdcEnvironment): string {
return [
"You are AMDC Diagnostic Agent.",
"Your job is to inspect AMDB infrastructure state with AMDC-provided read-only tools and produce structured diagnosis data for a separate Report Agent.",
"Your job is to inspect AMDB infrastructure state with AMDC-provided read-only tools and hand off an evidence-based first-pass diagnosis to a separate Report Agent.",
"Record what you checked, what the tool returned, and which observed fact motivated each follow-up read. Keep these links short and evidence-based, not a narration of private reasoning.",
"Explain the operational meaning of results and identify evidence-supported anomalies or suspicious conditions. Connect each concern to its observations and follow-up outcome, distinguishing confirmed impact from possible impact that was not observed.",
"Include relevant identifiers, values, scope and observation times where they support interpretation. Distinguish current samples, historical counters, empty results, and failed queries. Omit routine returnedRows, limit, truncated=false, daemon listings, and diagnostic sessions unless they affect the conclusion. Counts of real connections or waits can be meaningful evidence.",
"Continue relevant read-only investigation when returned facts warrant follow-up. Changing the output format does not mean stopping after the first check.",
"First-pass interpretation and evidence-supported suspicion are required when warranted. Do not assign an unobserved root cause, a global severity/health verdict, recommended actions or remediation. Do not call a count abnormal without a relevant baseline, limit or other evidence. Include counter-evidence and uncertainty, and do not manufacture suspicious findings when none were observed.",
"State unobserved areas as limitations. Do not turn missing data into a service fault or a clean bill of health. Write human-readable text in Korean while preserving source identifiers.",
"Do not write Discord messages. Do not produce the final operator report.",
"Do not ask for shell, SSH, database credentials, endpoint URLs, PromQL, LogQL, SQL, or arbitrary HTTP access.",
"Use only the provided AMDC tools. Tool execution commands, endpoints, and credentials are owned by AMDC and are not model inputs.",
Expand All @@ -165,7 +146,12 @@ function buildSystemPrompt(environment: AmdcEnvironment): string {
`The server-owned environment is ${environment}. Never change or override it.`,
"Call tools based on their functional capability, not because a tool is tied to a specific incident case.",
"Prefer a small set of relevant tools, but use multiple tools when needed to correlate health, logs, metrics, proxy, MySQL, and backup state.",
"Return structured diagnosis data only."
"AMDC records tool results independently. Each execution returns tool_call_id and seq. Never invent or rewrite execution IDs, inputs, results or timestamps.",
"Return only completion_reason and comments referencing those exact tool_call_id values. Do not reference plugin selection or model calls.",
"Each optional comment separates observation (what this result establishes), hypothesis (tentative interpretation), and limitation (what it cannot establish). Use null for absent fields or omit the annotation; never fill them with speculation.",
"related_call_ids may reference other existing calls in this diagnosis regardless of execution order, including parallel or later reads. Do not reference the annotated call itself or repeat IDs. These are evidence links, not causal ordering or an internal chain of thought. A Report Agent must assess original results independently of your comments.",
"completion_reason is investigation_complete when relevant investigation is finished, or insufficient_evidence when unavailable evidence prevents finishing. Neither is a health verdict.",
"Return structured annotation data only."
].join("\n");
}

Expand All @@ -184,81 +170,6 @@ function buildUserPrompt(
.join("\n"),
"",
"Select the smallest relevant plugin first. Use its loaded tools, then expand to another plugin only if the observations require it.",
"Return inferred domains, preliminary findings, suspected causes, recommended checks, and incomplete reasons."
"Return completion_reason and optional per-call comments using the tool_call_id supplied in each execution result. Separate observations, hypotheses and limitations. No final root-cause verdict or recommended actions."
].join("\n");
}

export function extractToolArtifacts(messages: readonly unknown[]): {
readonly observations: readonly ToolObservation[];
readonly rawResults: readonly RawToolResult[];
readonly toolErrors: readonly SanitizedToolError[];
readonly toolNames: ReadonlySet<string>;
} {
const observations: ToolObservation[] = [];
const rawResults: RawToolResult[] = [];
const toolErrors: SanitizedToolError[] = [];
const toolNames = new Set<string>();

for (const message of messages) {
const maybeMessage = message as { content?: unknown; name?: unknown };

if (typeof maybeMessage.name === "string") {
toolNames.add(maybeMessage.name);
}

const text = typeof maybeMessage.content === "string" ? maybeMessage.content : null;
if (!text) {
continue;
}

try {
const parsed = JSON.parse(text) as unknown;
if (!isRecord(parsed) || typeof parsed.ok !== "boolean") {
continue;
}

if (parsed.ok === true && isRecord(parsed.observation)) {
observations.push(parsed.observation as unknown as ToolObservation);
} else if (parsed.ok === true && isRecord(parsed.rawResult)) {
rawResults.push(parsed.rawResult as unknown as RawToolResult);
} else if (parsed.ok === false && isRecord(parsed.error)) {
toolErrors.push(parsed.error as unknown as SanitizedToolError);
}
} catch {
continue;
}
}

return { observations, rawResults, toolErrors, toolNames };
}

function toInferredDomains(draft: DiagnosisDraft): readonly InferredDomain[] {
return draft.inferredDomains.map((domain) => ({
domain: toPluginName(domain.domain),
reason: domain.reason
}));
}

function toPreliminaryFindings(draft: DiagnosisDraft): readonly PreliminaryFinding[] {
return draft.preliminaryFindings.map((finding) => ({
finding: finding.finding,
basis: finding.basis,
level: finding.level as ObservationStatus
}));
}

function toSuspectedCauses(draft: DiagnosisDraft): readonly SuspectedCause[] {
return draft.suspectedCauses.map((cause) => ({
cause: cause.cause,
reason: cause.reason,
confidence: cause.confidence
}));
}

function toPluginName(value: string): PluginName {
return isPluginName(value) ? value : "system";
}

function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
35 changes: 3 additions & 32 deletions src/agent/langchain-schemas.ts
Original file line number Diff line number Diff line change
@@ -1,38 +1,9 @@
import { z } from "zod/v3";
import type { JsonObjectSchema, JsonSchemaProperty } from "../tools/types.js";

export const diagnosisDraftSchema = z.object({
inferredDomains: z
.array(
z.object({
domain: z.string().min(1),
reason: z.string().min(1)
})
)
.default([]),
preliminaryFindings: z
.array(
z.object({
finding: z.string().min(1),
basis: z.array(z.string().min(1)).default([]),
level: z.enum(["normal", "warning", "critical", "unknown"])
})
)
.default([]),
suspectedCauses: z
.array(
z.object({
cause: z.string().min(1),
reason: z.string().min(1),
confidence: z.enum(["low", "medium", "high"])
})
)
.default([]),
recommendedChecks: z.array(z.string().min(1)).default([]),
incompleteReasons: z.array(z.string().min(1)).default([])
});

export type DiagnosisDraft = z.infer<typeof diagnosisDraftSchema>;
export { handoffDraftSchema as diagnosisDraftSchema } from "../report/diagnosis-handoff.js";

export type { HandoffDraft as DiagnosisDraft } from "../report/diagnosis-handoff.js";

export function jsonObjectSchemaToZod(schema: JsonObjectSchema): z.ZodObject<Record<string, z.ZodTypeAny>> {
const properties = schema.properties ?? {};
Expand Down
Loading
Loading