AgentQ Architecture

프로젝트 전체 구조

csharp/
├── AgentQ.Api                    계약 계층 (DTO, Enum, 도구 정의)
├── AgentQ.Core                   공통 핵심 (모델, Provider 추상화, 설정 로더)
├── AgentQ.Providers.Anthropic    Anthropic API 구현
├── AgentQ.Providers.OpenAi       OpenAI / OpenCode Go 호환 구현
├── AgentQ.Tools                  내장 도구 (bash, read_file, write_file, ...)
├── AgentQ.Cli                    콘솔 CLI 앱 (REPL + 자동화)
├── AgentQ.Desktop                WPF 데스크톱 앱 + 서비스 계층
├── AgentQ.MockService            Provider 패리티 테스트용 Mock 서버
└── AgentQ.Tests                  단위/통합/데스크톱 서비스 테스트

계층별 아키텍처

AgentQ.Api

모든 모듈이 공유하는 순수 DTO와 계약 계층입니다. ToolDefinition, MessageRequest, StreamEvents, ContentBlocks를 정의합니다.

AgentQ.Core

Provider와 도메인 모델의 추상화 계층입니다. ILlmProvider, ProviderFactory, 설정 로더, ToolCallDeltaBuffer, ChatModels를 담당합니다.

Providers / Tools

OpenAI 호환 Provider와 Anthropic Provider, 파일 읽기/수정, grep/glob, semantic/symbol/hybrid search 같은 도구를 연결합니다.

CLI / Desktop

CLI는 REPL과 자동화 실행을 담당하고, Desktop은 WPF UI와 프로젝트 분석, 검증, 권한, 메모리, Git 패널을 통합합니다.

데이터 흐름

CLI 대화형 흐름

사용자 입력
  ↓
CliApplication.RunAsync()
  ↓
ChatConversationHistory.AddUserMessage()
  ↓
CliToolLoopRunner.ExecuteConversationTurnAsync()
  ├── ChatContext + ToolDefinitions 조립
  ├── provider.GenerateStreamAsync()
  ├── StreamingProcessor.ProcessAsync()
  └── toolUses 있음?
        ├── ToolExecutor.ExecuteAsync()
        ├── history.AddToolResults()
        └── 최대 stepLimit까지 반복

Desktop 실행 흐름

사용자 입력 + Attachments
  ↓
DesktopAgentRunWorkflowService.SendCurrentMessageAsync()
  ├── WorkspaceIndexer / ProjectMemory / SystemSkill 컨텍스트 조립
  ├── DesktopPromptAssemblyService.BuildSystemPrompt()
  ├── provider.GenerateStreamAsync()
  ├── Guardrail 체크
  ├── ExecuteToolsAsync()
  │     ├── 권한 확인
  │     ├── 도구 실행
  │     └── FileMutationSnapshotService 기록
  └── Telemetry / Diagnostics / Replay 저장

핵심 설계 패턴

Tool-use Conversation Loop

LLM 응답에 도구 호출이 있으면 실행하고, 결과를 다시 메시지에 추가해 LLM을 재호출하는 ReAct 기반 루프입니다.

Dynamic Prompt Assembly

요청 종류와 권한 상태, 작업 프로필, 증거 기반 규칙을 조합해 런타임에 시스템 프롬프트를 구성합니다.

Hybrid Context Bank

워크스페이스 인덱스, URL 컨텍스트, 프로젝트 메모리, MCP, 시스템 스킬, 실행 실패 기록을 요청별로 조립합니다.

Guardrail System

빈 응답, 도구 없는 코딩 응답, 수동 복붙 안내, 읽기 전용 반복처럼 잘못된 흐름을 코드 레벨에서 감지하고 교정합니다.

Evidence Trail

AgentRunStep, FileChangeRecord, ToolReplayEntry, Confidence Scoring으로 에이전트 행동의 근거를 추적합니다.

HITL 권한 흐름

위험한 파일 수정과 셸 실행은 IPermissionEnforcer를 통해 사용자 승인 후 실행되도록 설계했습니다.

확장성 포인트

확장 지점	방법
새 LLM Provider	ILlmProvider 구현 후 ProviderFactory에 등록합니다.
새 도구	ITool 구현 후 ToolRegistry에 등록합니다.
새 프롬프트 규칙	IDesktopPromptRule 구현 후 PromptRules 목록에 추가합니다.
새 Task 분류	DesktopTaskClassifier와 DesktopTaskProfile을 확장합니다.
새 언어 Worker	TypeScript, Python, Native worker처럼 외부 분석 스크립트를 추가합니다.
새 MCP 서버	McpServerRegistry 설정 후 McpBridgeTool과 연동합니다.

설계 철학

AgentQ는 LLM에게 모든 것을 맡기는 도구가 아니라, 계획, 가드레일, 검증, 롤백, 증거 추적을 코드 레벨에서 관리하는 에이전트 프레임워크입니다. 핵심은 결정적 안전망, 관찰 가능성, 점진적 학습입니다.