프로덕션 운영 패턴

// trace context 전파 구조
interface TraceContext {
  traceId: string       // 요청 전체를 관통하는 ID
  spanId: string        // 현재 작업 단위 ID
  parentSpanId?: string // 부모 span ID (root span이면 없음)
  baggage: Record<string, string> // 추가 전파 데이터 (tenant, env 등)
}

function propagateContext(
  parentCtx: TraceContext,
  operationName: string
): TraceContext {
  return {
    traceId: parentCtx.traceId,
    spanId: crypto.randomUUID(),
    parentSpanId: parentCtx.spanId,
    baggage: { ...parentCtx.baggage },
  }
}

// parent → child agent 호출 시
async function delegateToChild(
  childAgent: Agent,
  task: string,
  parentCtx: TraceContext
) {
  const childCtx = propagateContext(parentCtx, `agent.${childAgent.name}`)
  const span = tracer.startSpan(childCtx, {
    'agent.name': childAgent.name,
    'agent.role': childAgent.role,
  })

  try {
    const result = await childAgent.execute(task, childCtx)
    span.setStatus('ok')
    return result
  } catch (error) {
    span.setStatus('error')
    span.recordException(error)
    throw error
  } finally {
    span.end()
  }
}

import { trace, SpanKind, SpanStatusCode } from '@opentelemetry/api'

const tracer = trace.getTracer('agent-orchestrator', '1.0.0')

async function tracedLLMCall(
  model: string,
  messages: Message[],
  parentCtx: TraceContext
) {
  const span = tracer.startSpan(
    'gen_ai.chat',
    {
      kind: SpanKind.CLIENT,
      attributes: {
        // GenAI Semantic Conventions
        'gen_ai.system': 'anthropic',
        'gen_ai.request.model': model,
        'gen_ai.request.max_tokens': 4096,
        'gen_ai.request.temperature': 0.7,

        // 에이전트 오케스트레이션 커스텀 속성
        'agent.id': parentCtx.baggage['agent_id'],
        'agent.step': parentCtx.baggage['step_index'],
        'orchestration.run_id': parentCtx.baggage['run_id'],
      },
    },
    parentCtx
  )

  try {
    const response = await llm.chat({ model, messages })

    // 응답 메트릭 기록
    span.setAttributes({
      'gen_ai.response.model': response.model,
      'gen_ai.response.finish_reason': response.stopReason,
      'gen_ai.usage.input_tokens': response.usage.inputTokens,
      'gen_ai.usage.output_tokens': response.usage.outputTokens,
      'gen_ai.cost.estimate_usd': calculateCost(
        model,
        response.usage.inputTokens,
        response.usage.outputTokens
      ),
    })

    span.setStatus({ code: SpanStatusCode.OK })
    return response
  } catch (error) {
    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
    span.recordException(error)
    throw error
  } finally {
    span.end()
  }
}

// Hybrid sampling 설정 예시
const samplerConfig = {
  // 기본: 10% head-based sampling
  defaultRate: 0.1,

  // 다음 조건에 해당하면 무조건 수집
  alwaysSample: {
    onError: true,                    // 에러 발생 시
    onHighCost: { thresholdUsd: 1.0 }, // 비용 임계값 초과 시
    onSlowResponse: { thresholdMs: 30_000 }, // 30초 초과 시
    onHumanEscalation: true,          // 사람 승인 요청 시
    onHighRisk: true,                 // risk_level === 'high'
  },

  // agent 역할별 샘플링 오버라이드
  perAgent: {
    'write-executor': 1.0,  // write agent는 항상 수집
    'classifier': 0.05,     // 분류기는 5%로 줄임
  },
}

interface AgentBudget {
  agentId: string
  maxInputTokens: number
  maxOutputTokens: number
  maxCostUsd: number
  model: string
  priority: 'critical' | 'normal' | 'optional'
}

interface RunBudgetPlan {
  totalMaxCostUsd: number
  agents: AgentBudget[]
  reservePercent: number  // 재시도 여유분 (권장 15~20%)
}

// 예시: 복합 분석 파이프라인의 budget 분배
const analysisPlan: RunBudgetPlan = {
  totalMaxCostUsd: 0.50,
  reservePercent: 0.15,
  agents: [
    {
      agentId: 'classifier',
      maxInputTokens: 2_000,
      maxOutputTokens: 500,
      maxCostUsd: 0.01,
      model: 'claude-haiku',
      priority: 'critical',
    },
    {
      agentId: 'researcher',
      maxInputTokens: 50_000,
      maxOutputTokens: 4_000,
      maxCostUsd: 0.20,
      model: 'claude-sonnet',
      priority: 'critical',
    },
    {
      agentId: 'synthesizer',
      maxInputTokens: 30_000,
      maxOutputTokens: 8_000,
      maxCostUsd: 0.15,
      model: 'claude-sonnet',
      priority: 'critical',
    },
    {
      agentId: 'quality-checker',
      maxInputTokens: 10_000,
      maxOutputTokens: 2_000,
      maxCostUsd: 0.05,
      model: 'claude-haiku',
      priority: 'normal',
    },
  ],
}

// prompt caching ROI 계산기
function calculateCachingROI(params: {
  systemPromptTokens: number
  avgContextTokens: number
  dailyRequests: number
  cacheHitRate: number      // 예상 캐시 적중률 (0~1)
  inputPricePerMToken: number   // $/1M tokens
  cachePricePerMToken: number   // 캐시 적중 시 가격
  cacheWritePricePerMToken: number // 캐시 기록 시 가격
}) {
  const totalTokens = params.systemPromptTokens + params.avgContextTokens
  const dailyTokens = totalTokens * params.dailyRequests

  // 캐시 미사용 비용
  const noCacheCost =
    (dailyTokens / 1_000_000) * params.inputPricePerMToken

  // 캐시 사용 비용
  const hitTokens = dailyTokens * params.cacheHitRate
  const missTokens = dailyTokens * (1 - params.cacheHitRate)
  const cacheCost =
    (hitTokens / 1_000_000) * params.cachePricePerMToken +
    (missTokens / 1_000_000) * params.cacheWritePricePerMToken

  return {
    dailySavings: noCacheCost - cacheCost,
    savingsPercent: ((noCacheCost - cacheCost) / noCacheCost) * 100,
    monthlyROI: (noCacheCost - cacheCost) * 30,
  }
}

// 실행 전략별 비용/지연 시뮬레이션
function simulateExecution(
  agents: AgentBudget[],
  strategy: 'sequential' | 'parallel' | 'hybrid',
  dependencyGraph: Map<string, string[]>
) {
  if (strategy === 'sequential') {
    return {
      estimatedLatencyMs: agents.reduce((sum, a) => sum + a.avgLatencyMs, 0),
      estimatedCost: agents.reduce((sum, a) => sum + a.maxCostUsd, 0),
      wastedCost: 0, // 불필요한 호출 없음
    }
  }

  if (strategy === 'parallel') {
    const independentAgents = agents.filter(
      (a) => !dependencyGraph.has(a.agentId)
    )
    return {
      estimatedLatencyMs: Math.max(...agents.map((a) => a.avgLatencyMs)),
      estimatedCost: agents.reduce((sum, a) => sum + a.maxCostUsd, 0),
      wastedCost: independentAgents.length * 0.02, // 불필요 결과 비용 추정
    }
  }
}

interface CostAlert {
  level: 'info' | 'warning' | 'critical'
  thresholdUsd: number
  action: 'log' | 'notify' | 'throttle' | 'halt'
  cooldownMinutes: number
}

const costAlertPolicy: CostAlert[] = [
  {
    level: 'info',
    thresholdUsd: 0.50,        // 요청 1건당 $0.50 초과
    action: 'log',
    cooldownMinutes: 0,
  },
  {
    level: 'warning',
    thresholdUsd: 2.00,        // 요청 1건당 $2.00 초과
    action: 'notify',          // Slack/PagerDuty 알림
    cooldownMinutes: 5,
  },
  {
    level: 'critical',
    thresholdUsd: 5.00,        // 요청 1건당 $5.00 초과
    action: 'throttle',        // 저비용 모델로 자동 전환
    cooldownMinutes: 1,
  },
  {
    level: 'critical',
    thresholdUsd: 10.00,       // 요청 1건당 $10.00 초과
    action: 'halt',            // 즉시 실행 중단
    cooldownMinutes: 0,
  },
]

// 일/주/월 단위 총액 알림도 별도 설정
const aggregateCostPolicy = {
  daily: { warningUsd: 100, criticalUsd: 300 },
  weekly: { warningUsd: 500, criticalUsd: 1500 },
  monthly: { warningUsd: 2000, criticalUsd: 5000 },
}

// 에이전트별 권한 정의
interface AgentPermissions {
  agentId: string
  allowedTools: ToolPermission[]
  dataAccess: DataAccessPolicy
  networkAccess: NetworkPolicy
  maxTokenBudget: number
  requiresApproval: boolean
}

interface ToolPermission {
  toolName: string
  operations: ('read' | 'write' | 'delete')[]
  resourcePattern: string  // glob 패턴 (예: "docs/*", "users/self")
  rateLimit?: { maxPerMinute: number }
}

interface DataAccessPolicy {
  allowedTables: string[]
  allowedColumns: string[]     // PII 컬럼 제외 가능
  rowFilter?: string           // tenant 격리 등
  maxRowsPerQuery: number
}

interface NetworkPolicy {
  allowedDomains: string[]     // 접근 가능한 외부 도메인
  blockedDomains: string[]
  maxRequestsPerMinute: number
}

// 예시: Researcher agent — read-only, 외부 API 접근 가능
const researcherPermissions: AgentPermissions = {
  agentId: 'researcher',
  allowedTools: [
    {
      toolName: 'web_search',
      operations: ['read'],
      resourcePattern: '*',
      rateLimit: { maxPerMinute: 30 },
    },
    {
      toolName: 'database_query',
      operations: ['read'],
      resourcePattern: 'public.*',
    },
  ],
  dataAccess: {
    allowedTables: ['documents', 'knowledge_base'],
    allowedColumns: ['*'],
    maxRowsPerQuery: 100,
  },
  networkAccess: {
    allowedDomains: ['api.search.com', 'docs.internal.com'],
    blockedDomains: ['*.payment.*'],
    maxRequestsPerMinute: 60,
  },
  maxTokenBudget: 50_000,
  requiresApproval: false,
}

// 예시: Writer agent — write 가능, 반드시 승인 필요
const writerPermissions: AgentPermissions = {
  agentId: 'writer',
  allowedTools: [
    {
      toolName: 'database_query',
      operations: ['read', 'write'],
      resourcePattern: 'drafts/*',
    },
    {
      toolName: 'publish',
      operations: ['write'],
      resourcePattern: 'content/*',
    },
  ],
  dataAccess: {
    allowedTables: ['drafts', 'content'],
    allowedColumns: ['*'],
    rowFilter: 'tenant_id = :current_tenant',
    maxRowsPerQuery: 10,
  },
  networkAccess: {
    allowedDomains: [],
    blockedDomains: ['*'],
    maxRequestsPerMinute: 0,
  },
  maxTokenBudget: 30_000,
  requiresApproval: true,
}

interface AuditRecord {
  // WHO — 행위 주체
  who: {
    agentId: string
    agentRole: string
    parentAgentId?: string  // 위임한 상위 에이전트
    userId: string          // 요청을 시작한 사용자
    tenantId: string
  }

  // WHAT — 수행한 행위
  what: {
    action: string          // 'tool_call', 'llm_call', 'approval_request' 등
    toolName?: string
    operation?: 'read' | 'write' | 'delete'
    resourceId?: string     // 대상 리소스
    inputSummary: string    // 입력 요약 (PII 마스킹 적용)
    outputSummary: string   // 출력 요약 (PII 마스킹 적용)
    tokensUsed?: { input: number; output: number }
    costUsd?: number
  }

  // WHEN — 시점
  when: {
    timestamp: string       // ISO 8601
    durationMs: number
    traceId: string
    spanId: string
  }

  // CONTEXT — 맥락
  context: {
    requestId: string
    runId: string
    stepIndex: number
    riskLevel: 'low' | 'medium' | 'high'
    policyVersion: string   // 적용된 정책 버전
    modelName: string
    approvalStatus?: 'pending' | 'approved' | 'rejected'
    approvedBy?: string
  }
}

// 감사 로그 저장소 인터페이스
interface AuditStore {
  // 불변 저장 (append-only)
  append(record: AuditRecord): Promise<void>

  // 조회 (규제 대응, 사고 조사)
  query(filter: {
    userId?: string
    agentId?: string
    action?: string
    timeRange?: { from: string; to: string }
    riskLevel?: string
  }): Promise<AuditRecord[]>

  // 보존 정책
  retentionPolicy: {
    minRetentionDays: number  // 규제 요건에 따라 결정
    immutable: boolean        // 변조 불가 여부
  }
}

type RunBudget = {
  maxSteps: number
  maxCostUsd: number
}

async function runProductionFlow(input: string, budget: RunBudget) {
  const trace = startTrace()
  const route = await routeModel(input)

  const result = await executeWithBudget(route, budget, trace.id)

  if (result.riskLevel === 'high') {
    return requestHumanApproval(result, trace.id)
  }

  return finalizeRun(result, trace.id)
}

interface AgentSystemSLO {
  // 응답 시간 SLO
  latency: {
    p50TargetMs: number  // 일반적 경험 품질
    p95TargetMs: number  // 최악 허용 범위
    p99TargetMs: number  // 극단치 감시 기준
    timeoutMs: number    // 이 시간 초과 시 강제 종료
  }

  // 성공률 SLO
  successRate: {
    targetPercent: number       // 월간 목표 (예: 95%)
    errorBudgetPercent: number  // 허용 실패 비율 (= 100 - target)
    countingWindow: 'rolling_7d' | 'calendar_month'
    excludeFromCount: string[]  // 사용자 입력 오류 등 제외 조건
  }

  // 비용 SLO
  cost: {
    maxPerRequestUsd: number    // 요청 1건 상한
    maxDailyUsd: number         // 일일 총액 상한
    p95PerRequestUsd: number    // P95 기준 비용 목표
  }

  // 품질 SLO (선택)
  quality?: {
    minAccuracyPercent: number  // 정답률 (평가 파이프라인 필요)
    maxHallucinationRate: number // 환각 비율 상한
    humanOverrideRateTarget: number // 사람 개입 비율 목표
  }
}

// 예시: 고객 지원 에이전트 시스템 SLO
const supportAgentSLO: AgentSystemSLO = {
  latency: {
    p50TargetMs: 5_000,
    p95TargetMs: 15_000,
    p99TargetMs: 30_000,
    timeoutMs: 60_000,
  },
  successRate: {
    targetPercent: 95,
    errorBudgetPercent: 5,
    countingWindow: 'rolling_7d',
    excludeFromCount: ['invalid_input', 'rate_limited'],
  },
  cost: {
    maxPerRequestUsd: 0.50,
    maxDailyUsd: 500,
    p95PerRequestUsd: 0.30,
  },
  quality: {
    minAccuracyPercent: 90,
    maxHallucinationRate: 0.02,
    humanOverrideRateTarget: 0.10,
  },
}

// SLO 자동 대응 정책
interface SLOBreachPolicy {
  sloType: 'latency' | 'cost' | 'successRate'
  severity: 'warning' | 'critical'
  actions: SLOAction[]
}

type SLOAction =
  | { type: 'circuit_breaker'; agentId: string; cooldownSec: number }
  | { type: 'model_downgrade'; from: string; to: string }
  | { type: 'disable_optional_agents'; agentIds: string[] }
  | { type: 'rate_limit'; maxRequestsPerMin: number }
  | { type: 'escalate'; channel: 'slack' | 'pagerduty' }

const breachPolicies: SLOBreachPolicy[] = [
  // 지연 SLO warning: 경량 모델로 전환
  {
    sloType: 'latency',
    severity: 'warning',
    actions: [
      { type: 'model_downgrade', from: 'claude-sonnet', to: 'claude-haiku' },
    ],
  },
  // 지연 SLO critical: circuit breaker + 에스컬레이션
  {
    sloType: 'latency',
    severity: 'critical',
    actions: [
      {
        type: 'circuit_breaker',
        agentId: 'slow-agent',
        cooldownSec: 300,
      },
      { type: 'escalate', channel: 'pagerduty' },
    ],
  },
  // 비용 SLO warning: 선택적 agent 비활성화
  {
    sloType: 'cost',
    severity: 'warning',
    actions: [
      {
        type: 'disable_optional_agents',
        agentIds: ['quality-checker', 'summarizer'],
      },
    ],
  },
  // 비용 SLO critical: rate limit + 모델 다운그레이드
  {
    sloType: 'cost',
    severity: 'critical',
    actions: [
      { type: 'rate_limit', maxRequestsPerMin: 10 },
      { type: 'model_downgrade', from: 'claude-sonnet', to: 'claude-haiku' },
      { type: 'escalate', channel: 'slack' },
    ],
  },
  // 성공률 SLO critical: 사람 에스컬레이션
  {
    sloType: 'successRate',
    severity: 'critical',
    actions: [
      { type: 'escalate', channel: 'pagerduty' },
    ],
  },
]