From 403793cbb93a4cad908e4811d79b0254846a431d Mon Sep 17 00:00:00 2001 From: Godopu Date: Fri, 26 Jun 2026 08:08:05 +0900 Subject: [PATCH] docs: update project documentation in README.md --- README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 50 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 244c106..5992b4c 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,25 @@ LLM 기반 에이전트 시스템 아키텍처는 크게 다음 3가지 핵심 3. **Tool Use (도구 활용)** - 에이전트가 학습되지 않은 외부 정보에 접근하거나 외부 시스템에 영향을 미치기 위해 계산기, 코드 실행용 샌드박스, 웹 브라우저, 외부 API 등을 주도적으로 호출하는 능력입니다. + ![Screenshot 2026-06-25 at 9.39.07 pm](assets/images/Screenshot%202026-06-25%20at%209.39.07%20pm.png) + ## AI Agent를 더욱 강력하게 만드는 Skills Skills(기술/도구 패키지)는 AI 에이전트가 외부 환경과 동적으로 상호작용할 수 있도록 결합하는 기능적 실행 모듈입니다. 단순히 LLM에게 행동 지침을 주는 프롬프트 엔지니어링 수준을 넘어, 에이전트가 특정 목표를 위해 직접 실행할 수 있는 코드, 도구의 명세 스키마(Tool Schema), 사용 설명 및 예시(Few-shot Examples) 등이 하나의 단위로 패키징된 자율적 확장 도구 모음입니다. - **동적 모듈화**: 에이전트는 상황에 따라 특정 기술을 필요할 때 로드하여 사용하고 완료 후 반환합니다. - **작업 수행 한계 돌파**: 텍스트 생성이라는 언어 모델 자체의 한계를 넘어, 시스템 레벨의 파일 제어, 서버 배포, 물리 데이터 수집 등의 적극적인 업무 대행 능력을 에이전트에 제공합니다. +## Claude cowork와 code +- AI Agent의 대표 주자인 Claude는 Claude desktop 이라는 프로그램으로 자신들의 뛰어난 모델을 서비스하고 있으며, Claude Desktop App에서 우리는 Claude Cowork와 Claude Code라는 다른 서비스를 사용할 수 있음 +- Claude Cowork와 Claude Code는 같은 모델을 사용하지만 작동하는 방식이 완전히 다름. Claude Cowork의 경우 사무 작업 등 일상적인 업무의 비서 역할을 수행하며, Claude Code는 Coding 작업에 특화된 Coding Agent라고 소개함 +- 두 서비스는 동일하게 내부 컴퓨터의 특정 디렉터리에서 작업을 수행하지만 내부적인 작동 절차를 확인해보면 Claude Cowork는 Cloud에서 모델이 필요한 기능을 제공하여 pdf, word, excel, ppt 등 다양한 파일을 읽고 쓸 수 있도록 AI 모델의 기능을 확장한 서비스임 +- 반면에 Claude Code는 필요한 모듈, 소프트웨어가 있다면 Local Computer에 설치해서 사용한다는 차이점이 있음. + + ![Screenshot 2026-06-25 at 10.04.54 pm](assets/images/Screenshot%202026-06-25%20at%2010.04.54%20pm.png) + +- Claude Cowork와 Claude Code를 비교하면 Claude Cowork가 더 좋아보일 수 있지만 Claude Code를 잘 조련하면 Claude Cowork 보다 훨씬 좋은 결과를 기대할 수 있음. + + + ## Skills 사례 소개 에이전트가 업무 현장에서 유용하게 사용하는 대표적인 Skills 사례들은 다음과 같습니다: 1. **코드베이스 분석 및 관리 Skill** @@ -33,6 +47,21 @@ Skills(기술/도구 패키지)는 AI 에이전트가 외부 환경과 동적으 4. **학술/도메인 특화 API Skill** - 생화학 데이터베이스(ChEMBL), 의학 학술 논문(PubMed, arXiv), 유전학 정보(dbSNP, ClinVar) 등 전문 영역의 연구용 OpenAPI와 연동하여 자율 연구원(Researcher) 역할을 돕는 조사용 Skill입니다. +### Github를 점령한 Skills +![Screenshot 2026-06-25 at 9.43.29 pm](assets/images/Screenshot%202026-06-25%20at%209.43.29%20pm.png) + +### Understand skill +Turn any codebase, knowledge base, or docs into an interactive knowledge graph you can explore, search, and ask questions about. +![Screenshot 2026-06-25 at 9.41.27 pm](assets/images/Screenshot%202026-06-25%20at%209.41.27%20pm.png) + +### 유행이라 개발해본 multi-agent-mux skill + +![Screenshot 2026-06-25 at 9.45.01 pm](assets/images/Screenshot%202026-06-25%20at%209.45.01%20pm.png) + +![Recording Jun 25, 2026 - 11_56 AM](assets/images/Recording%20Jun%2025,%202026%20-%2011_56%20AM.mp4) + + + # Multi-Agent란 ## General @@ -50,23 +79,33 @@ Subagent는 부모 에이전트(Parent Agent 또는 Orchestrator)에 의해 동 - **컨텍스트 격리**: 상위 에이전트의 전체 대화 컨텍스트를 오염시키지 않기 위해 하위 작업의 맥락만을 분기(Branch)하여 처리함으로써, 에이전트 실행 도중 누적되는 토큰 소모량을 최적화하고 속도를 개선합니다. - **예시**: 메인 에이전트가 "전체 코드 리팩토링"을 수행하면서, 특정 모듈에 대한 에러 복구 작업만을 subagent에게 위임하여 독립적으로 문제를 해결하게 하는 경우입니다. +![Pasted image 20260625224821](assets/images/Pasted%20image%2020260625224821.png) + +![Pasted image 20260625224849](assets/images/Pasted%20image%2020260625224849.png) + ### Team agent란 Team agent는 단일 계층적인 수직 구조를 넘어, 수평적이고 다양한 역할을 맡은 여러 독립 에이전트가 협의체(Crew/Team)를 구성하여 대화형 협력(Multi-agent Debate) 및 협상을 통해 목표를 완수하는 협동형 에이전트 구성 방식입니다. - **의견 충돌 및 합의**: 특정 설계안에 대해 아키텍트 에이전트와 보안 담당 에이전트가 서로의 입장에서 논쟁(Debate)을 벌이고, 최종적으로 합의된 결과를 PM 에이전트가 도출하는 식의 인간 워크플로우 모사가 가능합니다. - **협력적 의사결정**: 복잡한 비선형적 문제 해결에 있어 각 에이전트가 피드백을 실시간으로 주고받으며 점진적으로 답을 고도화합니다. +![Pasted image 20260625230135](assets/images/Pasted%20image%2020260625230135.png) + +![Pasted image 20260625224919](assets/images/Pasted%20image%2020260625224919.png) + ### Context Engineering (Lang Graph)란 컨텍스트 엔지니어링(Context Engineering)은 다중 에이전트 시스템에서 에이전트들 간의 대화 흐름, 전달되는 컨텍스트(State), 복잡한 제어 루프를 효율적으로 설계하고 유지하는 방법론적 학문입니다. 이를 구현하는 대표적인 상태 보존형 프레임워크가 LangGraph입니다. - **상태 보존 및 순환 제어(Stateful & Cyclic Control)**: 단순 선형적 체인 구조를 탈피하여, 에이전트 간의 루프(반복 검증), 조건부 분기(Conditional branching), 실패 시 롤백 등을 순환형 그래프(Cyclic Graph) 구조로 관리합니다. - **영속적 상태 관리**: 협업 과정에서 축적되는 다양한 상태 변화(State)를 중앙 저장소에서 추적 및 동기화하므로, 대형 워크플로우 도중 특정 노드가 실패하더라도 이전 상태부터 안전하게 재시작할 수 있습니다. ### CrewAI, Sana 등 Multi agent orchestration을 지원하기 위한 소프트웨어 + +![Screenshot 2026-06-25 at 10.52.04 pm](assets/images/Screenshot%202026-06-25%20at%2010.52.04%20pm.png) 1. **CrewAI** - - 역할 기반(Role-based) 협업을 설계하는 데 특화된 프레임워크입니다. 각 에이전트에게 명확한 역할(Role), 목표(Goal), 배경 설명(Backstory)을 부여하고, 이들을 업무 프로세스(Sequential 또는 Hierarchical)에 따라 배치해 '크루(Crew)' 단위로 조율합니다. -2. **Sana** - - 최근 Workday가 약 11억 달러에 인수한(2025년 9월 발표, 11월 인수 완료) Sana(스웨덴의 Sana Labs)는 기업 내부 정보 검색 및 다단계 워크플로우를 자동화하는 대표적인 통합 AI 플랫폼이자 비즈니스 오케스트레이션 레이어입니다. 여러 LLM을 모델 비종속적으로 결합해 검색·추론·실행을 수행하는 에이전트 플랫폼인 Sana Agents와 AI 기반 학습 관리 시스템인 Sana Learning을 통해 사내 데이터베이스 및 Slack, Salesforce, Jira 등 서드파티 도구와 연동하여 복잡한 비선형적 업무 프로세스를 자율적으로 조율(Orchestration)합니다. -3. **Microsoft AutoGen** - - 다중 에이전트 간 대화(Conversational Agentic Design)에 중점을 둔 프레임워크입니다. 다양한 LLM과 도구(Tools)가 연결된 여러 에이전트가 서로 대화를 주고받으며 코드 실행 및 피드백을 처리할 수 있으며, 동적 워크플로우 및 인간의 개입(Human-in-the-loop)을 풍부하게 지원합니다. +- 역할 기반(Role-based) 협업을 설계하는 데 특화된 프레임워크입니다. 각 에이전트에게 명확한 역할(Role), 목표(Goal), 배경 설명(Backstory)을 부여하고, 이들을 업무 프로세스(Sequential 또는 Hierarchical)에 따라 배치해 '크루(Crew)' 단위로 조율합니다. +1. **Microsoft AutoGen** +- 대중 에이전트 간 대화(Conversational Agentic Design)에 중점을 둔 프레임워크입니다. 다양한 LLM과 도구(Tools)가 연결된 여러 에이전트가 서로 대화를 주고받으며 코드 실행 및 피드백을 처리할 수 있으며, 동적 워크플로우 및 인간의 개입(Human-in-the-loop)을 풍부하게 지원합니다. +1. **BeeAI** +- BeeAI는 프레임워크 전반에서 [AI 에이전트](https://www.ibm.com/kr-ko/think/topics/ai-agents)를 탐색, 실행 및 공유할 수 있는 중앙 집중형 환경을 제공하는 [오픈소스](https://www.ibm.com/kr-ko/think/topics/open-source) 플랫폼입니다. IBM이 개발한 BeeAI는 에이전트 통신 프로토콜(ACP)을 기반으로 구축되었으며 Linux Foundation에서 호스팅됩니다. 팀은 BeeAI 프레임워크를 사용하여 사일로화된 에코시스템 외부에 에이전트를 배포할 수 있습니다. ## Multi Agent 환경 구성을 위한 Protocols @@ -80,6 +119,8 @@ Team agent는 단일 계층적인 수직 구조를 넘어, 수평적이고 다 - **Agent Card (에이전트 카드)**: A2A 생태계에서 에이전트의 기능 명세서 역할을 하는 JSON 포맷의 표준 규격서입니다. 에이전트 카드에는 해당 에이전트의 명칭, 제공 가능한 역량(Capabilities), 호출 엔드포인트 정보, 요청 시 통과해야 하는 보안 인증 사양(Authentication) 등이 명시되어 있어 서비스 검색 시스템(Service Discovery)이 에이전트의 역할을 실시간으로 탐색할 수 있도록 돕습니다. 주로 `/.well-known/agent-card.json` 경로에서 탐색 가능하도록 배포됩니다. # 실제 Multi Agent Orchestration을 구현하며 겪은 문제점들 + +![Pasted image 20260625230628](assets/images/Pasted%20image%2020260625230628.png) 1. **Agent들과 각 Agent들의 세션 관리** - 다수의 에이전트와 그 아래에 동적으로 생성되는 subagent들의 생명주기(Lifecycle) 및 고유 식별자(UUID)를 동기화하고 상태를 지속적으로 보존하는 일관된 세션 관리 시스템이 필요합니다. 2. **에이전트 상호 탐색(Service Discovery)과 역할 식별** @@ -92,6 +133,7 @@ Team agent는 단일 계층적인 수직 구조를 넘어, 수평적이고 다 - **무한 대기 및 리소스 누수(Deadlock & Resource Leak)**: 작업을 전달받은 subagent가 아무런 예외 통보(Timeout 또는 Error Event) 없이 갑자기 고사(Silent death)하는 경우, 작업을 위임하고 대기하던 부모 에이전트는 무한 대기(Blocking) 상태에 빠져 리소스를 계속 낭비하게 되며 시스템 모니터링에서도 이를 감지하기 어렵습니다. # Multi Agent Orchestration 의 장점 + 1. **프롬프트의 간소화 및 루프 엔진의 진화** - 기존의 길고 장황한 단일 "Super Prompt" 엔지니어링 시대에서 벗어나, 에이전트를 구동하고 제어하는 자율 루프(Loop Architecture) 설계 중심으로 패러다임이 이동하고 있습니다. - *PSPDFKit 창업자이자 오픈소스 AI 에이전트 프로젝트인 OpenClaw의 크리에이터인 페터 슈타인베르거(Peter Steinberger, 2026년 초 OpenAI 합류)는 **"코딩 에이전트에 프롬프트를 더 넣지 말고, 에이전트를 구동하는 루프를 설계하라"**(Stop prompting your coding agents; start designing loops that prompt your agents)고 강조한 바 있습니다.* @@ -111,6 +153,9 @@ Team agent는 단일 계층적인 수직 구조를 넘어, 수평적이고 다 - 에이전트들이 통신에 사용할 서비스 주소와 포트를 동적으로 조회할 수 있는 서비스 디스커버리(Service Discovery) 기능 및 자동 라우팅 체계가 내재되어야 합니다. 3. **일관성 있는 워크플로우 추적 및 공유 (Issue & Workflow Tracking)** - 서로 다른 에이전트가 동일한 작업을 재수행할 때 동일한 프로세스와 출력을 일관되게 얻을 수 있도록 워크플로우 사양이 제어되어야 합니다. 또한 에러나 중간 정지가 일어났을 때 복구 및 추적이 용이하도록 규격화된 이슈 추적 인터페이스(Issue Tracking Interface)를 마련해야 합니다. + + ![Pasted image 20260625230351](assets/images/Pasted%20image%2020260625230351.png) + 4. **고성능 양방향 메시징 시스템 (Advanced Messaging System)** - 고용량의 코드 블록, 이미지 및 멀티모달 센서 데이터 등을 대량으로 빠르고 정확하게 공유하기 위해서는 기존의 MQTT나 단순 메시지 큐(MQ) 방식은 토픽 세분화와 페이로드 크기 한계로 인해 통신 병목을 겪을 수밖에 없습니다. - 단편적인 이벤트 알림만 전송하는 구조에서 탈피하여 상세 에러 트레이스, 상태 구조체, 이미지 바이너리 등을 한꺼번에 담을 수 있는 풍부한 페이로드 지원 메시징 규격이 필수적입니다. 나아가 대용량 멀티모달 푸시(Push)와 양방향 스트리밍을 지원하기 위해 HTTP/3의 멀티 스트리밍 등 고성능 통신이 수반되어야 합니다.