iusztinpaul/designing-real-world-ai-agents-workshop

AI Engineering Conference Europe에서 발표된 실습 워크숍으로, 두 개의 MCP (Model Context Protocol) 서버인 **Deep Research Agent (심층 조사 에이전트)**와 **LinkedIn Writing Workflow (LinkedIn 작성 워크플로우)**를 사용하여 멀티 에이전트 AI 시스템을 구축합니다. 두 서버 모두 Claude Code 또는 Cursor와 같은 하네스 (harness)에 연결됩니다.

🎬 전체 워크숍은 YouTube에서 시청 가능합니다 ↓

📑 슬라이드는 여기에서 확인하세요.

이 워크숍은 2~4시간 분량의 맛보기 과정입니다. 기초부터 시작하여 프로덕션급 (production-grade) AI 에이전트를 배포하고 싶다면, Towards AI와 함께 제작한 **Agentic AI Engineering Course (에이전트 기반 AI 엔지니어링 코스)**를 확인해 보세요.

34개의 레슨. 3개의 엔드 투 엔드 (end-to-end) 포트폴리오 프로젝트. 수료증. 그리고 업계 전문가 및 저희에게 직접 문의할 수 있는 Discord 커뮤니티가 제공됩니다.

300명 이상의 학생들로부터 5/5점을 받았습니다. 처음 6개 레슨은 무료입니다:

이 리포지토리 (repo)를 사용하는 세 가지 방법입니다. 보유한 시간에 맞는 모드를 선택하세요. 또는 각 단계가 이전 단계를 기반으로 하므로 세 가지를 순서대로 진행해도 좋습니다:

워크숍을 시청하고 패턴을 처음부터 끝까지 확인하세요. 약 2시간 소요. 위에서 제공된 2시간 분량의 YouTube 워크숍과 슬라이드로 시작하세요. 도구 사용 에이전트 (tool-use agents), 평가자-최적화 루프 (evaluator-optimizer loops), 근거 기반 검색 (grounded search), 구조화된 LLM 출력 (structured LLM output), 그리고 MCP 서버 설계에 대한 전체적인 멘탈 모델 (mental model)을 얻을 수 있습니다. -
완성된 코드를 실행하세요. 실제 결과물이 생성되는 것을 확인하세요. 약 30분 소요. 시스템이 조사 브리프 (research brief)를 생성하고, 평가자-최적화 루프를 통해 LinkedIn 게시물 초안을 작성하며, LLM-as-judge (판사로서의 LLM) 방식으로 스스로 점수를 매기는 과정을 지켜보세요. 프로젝트를 설치하고 MCP 서버, 스킬 (skills), 그리고 평가 파이프라인 (evaluation pipeline)을 실행하려면 Getting Started 및 Running the Code 섹션을 따르세요. -
에이전트 기반 코딩 (agentic coding)으로 직접 구현해 보세요. 약 2~4시간 내에 처음부터 1:1 복제본을 구축합니다. implement_yourself/를 여세요.

이 디렉토리는 25개의 사전 정리된 티켓 (tickets)과, 디렉토리가 src/와 일치할 때까지 티켓별로 SWE (Software Engineer) 에이전트와 Tester (테스터) 에이전트를 루프 내에서 조율하는 커스텀 /implement Claude Code 스킬이 준비된 간소화된 스켈레톤 (skeleton)입니다. 시작 가이드는 implement_yourself/README.md를 참조하세요. 설계 단계부터 부정행위는 불가능합니다. implement_yourself/

is 독립적인 프로젝트입니다. 작업 디렉터리가 스켈레톤(skeleton) 범위 내로 제한되도록, 사용자의 하네스(harness, Claude Code, Cursor, …)를 (리포지토리 루트가 아닌) 해당 폴더에서 직접 여세요. 에이전트들은 ../src/에 있는 참조 구현(reference implementation)을 볼 수 없으며, grep할 수도 없고, 그 파일들을 읽을 수도 없습니다. 복사-붙여넣기가 아닌 실제 빌드(build)를 경험하게 됩니다.

Deep Research Agent — Google Search 그라운딩(grounding)과 네이티브 YouTube 비디오 분석 기능이 포함된 Gemini를 사용하여 심층 연구를 수행하는 MCP 서버입니다:

사용자 주제 → [deep_research] × N → analyze_youtube_video (URL이 있는 경우) → [deep_research gap-fill] → compile_research → research.md

LinkedIn Writing Workflow — 평가자-최적화 루프(evaluator-optimizer loop)를 통해 LinkedIn 게시물을 생성하는 MCP 서버입니다:

research.md + 가이드라인 → 게시물 생성 → [검토 → 수정] × N → post.md → 이미지 생성

두 서버 모두 Model Context Protocol (MCP)을 통해 도구(tools), 리소스(resources), 프롬프트(prompts)를 노출하므로, MCP 호환 하네스라면 무엇이든 워크플로우를 오케스트레이션(orchestrate)할 수 있습니다.

학습하게 될 패턴 및 개념:

도구 사용 에이전트 (Tool-use agents) — LLM이 어떤 도구를 언제 호출할지 결정하도록 함
평가자-최적화 루프 (Evaluator-optimizer loop) — 생성, 검토, 수정을 사이클로 반복
그라운디드 검색 (Grounded search) — 사실 기반 연구를 위해 Google Search 그라운딩이 적용된 Gemini 사용
구조화된 LLM 출력 (Structured LLM output) — 타입 안정성이 보장된 모델 응답을 위한 Pydantic 스키마 사용
MCP 서버 설계 (MCP server design) — FastMCP를 사용하여 도구, 리소스, 프롬프트 등록
LLM-as-judge 평가 (LLM-as-judge evaluation) — Opik을 이용한 자동화된 품질 점수 산정

주제 씨앗(topic seed)부터 AI가 생성한 이미지가 포함된 게시 준비 완료된 LinkedIn 게시물까지, 전체 파이프라인을 실제로 실행하는 과정입니다.

단계별 분석 (씨앗 → 연구 → 가이드라인 → 초안)

2~3개의 질문과 참조 링크가 포함된 짧은 연구 브리프(research brief):

# 연구 주제: AI 에이전트 아키텍처 — 적을수록 더 나은 경우 (When Less Is More)
## 핵심 질문
1. 왜 스마트한 도구를 갖춘 단일 에이전트 아키텍처가 멀티 에이전트 시스템보다 성능이 뛰어난가?
...

에이전트는 Gemini 기반의 여러 검색 쿼리를 실행하고 YouTube 비디오를 분석한 다음, 출처가 포함된 구조화된 연구 브리프 (research brief)로 모든 내용을 정리합니다.

이 예제의 전체 research.md는 2개의 쿼리와 1개의 비디오 트랜스크립트(transcript)를 통해 약 20k 토큰에 달합니다.

게시물의 관점, 대상 독자 및 핵심 사항을 설명하는 짧은 브리프:

# LinkedIn 게시물 가이드라인
## 주제
왜 대부분의 AI 팀은 12개의 에이전트 대신 1개의 에이전트를 사용해야 하는가.
...

평가자-최적화 루프 (evaluator-optimizer loop)는 초안을 생성한 다음, 3라운드의 검토 및 편집 과정을 수행합니다:

예시 2 — Harness Engineering (클릭하여 확장)

Harness engineering은 단순히 프롬프트 엔지니어링 (prompt engineering)을 일컫는 새로운 용어가 아닙니다. 이것이 바로 AI가 나아가는 방향입니다.
에이전트가 코드와 도구에 유용할 만큼 발전했지만, 신뢰성이 부족했습니다. 실수를 반복하곤 했습니다. 병목 현상은 코드 생성에서 실제 시스템에서의 일관되고 신뢰할 수 있는 동작으로 이동했습니다.
이렇게 생각해보세요: 프롬프트 엔지니어링은 '무엇을 물을 것인가'입니다. 컨텍스트 엔지니어링 (context engineering)은 '모델에 무엇을 보낼 것인가'입니다. Harness engineering은 '이 모든 것이 어떻게 작동하는가'입니다. 이는 단순히 토큰을 넘어 모델을 둘러싼 환경을 의미합니다.
...

예시 3 — AI 엔지니어를 위한 Angine de Poitrine (클릭하여 확장)

최신 AI 모델은 잊으세요. 인터넷을 뒤흔들고 있는 새로운 시스템이 있습니다: Angine de Poitrine.
퀘벡 출신의 이 가면을 쓴 듀오는 고해상도 오디오 아키텍처 (audio architecture)를 배포합니다. 이는 다른 모든 것을 저해상도처럼 들리게 만듭니다.
Khn의 커스텀 더블넥 미크로토날 기타 (double-necked microtonal guitar)는 2배의 해상도를 특징으로 합니다: 옥타브당 12음이 아닌 24음입니다. 미세한 주파수 변조 (frequency modulation)를 지원합니다.
...

더 많은 전체 예시(시드, 연구, 게시물 초안, 검토, 최종 게시물 + 이미지)는 examples/ 디렉토리에서 찾아볼 수 있습니다.

구성 요소	도구
LLM API	Google Gemini (`google-genai` SDK를 통해 사용)
...

Python에 대한 실무 지식과 LLM에 대한 기본적인 이해가 있다고 가정합니다.

요구 사항	확인	설치
Python 3.12+	`python --version`	`uv python install 3.12` 또는 python.org
uv 0.7+	`uv --version`	`curl -LsSf https://astral.sh/uv/install.sh
GNU Make	`make --version`	macOS/Linux에는 사전 설치됨. Windows: `choco install make`
Google API Key	—	aistudio.google.com/apikey (필수 — 모든 LLM 호출에 Gemini 사용)
Opik 계정	—	comet.com/site/products/opik (선택 사항, 관측성(observability) 및 평가(evals) 용도)

복제 및 설정:
git clone https://github.com/iusztinpaul/designing-real-world-ai-agents-workshop.git
cd designing-real-world-ai-agents-workshop
cp .env.example .env # 본인의 GOOGLE_API_KEY 추가 (+ 선택 사항인 OPIK_API_KEY)

의존성 설치:
uv sync

참고: Python 3.12+가 설치되어 있지 않은 경우, uv가 대신 설치할 수 있습니다: uv python install 3.12를 실행한 후, 다시 uv sync를 실행하세요.

설정 확인:
make test-end-to-end # 리서치 + 라이팅 파이프라인을 엔드 투 엔드(end-to-end)로 실행

오류 없이 완료되면 준비가 된 것입니다.

워크플로를 실행하는 네 가지 방법이 있습니다:

모드	최적의 용도
MCP 서버 (권장)	AI 하네스(harness)를 통한 대화형 사용, 기술(Skills), 가이드된 슬래시 명령(slash-command) 워크플로
Streamlit UI	실시간 진행 상황을 보여주는 시각적 엔드 투 엔드(end-to-end) 데모
스크립트	설정 확인, 스모크 테스트(smoke tests)

대화형 사용을 위해 서버를 MCP 호환 하네스(Claude Code, Cursor)에 연결하세요. 이것이 워크숍을 사용하는 주요 방법입니다.

설정: .mcp.json 파일이 사전 구성되어 있습니다. Claude Code 또는 Cursor에서 프로젝트를 열면 두 서버가 자동으로 시작됩니다.

서버	도구 (Tools)	프롬프트 (Prompt)
`deep-research`	`deep_research`, `analyze_youtube_video`, `compile_research`	`research_workflow`
`linkedin-writer`	`generate_post`, `edit_post`, `generate_image`	`linkedin_post_workflow`

사용법:

Claude Code 또는 Cursor에서 프로젝트를 엽니다.
MCP 프롬프트를 호출합니다 (예: research_workflow

)를 호출하여 전체 워크플로우의 안내를 받거나, 세밀한 제어를 위해 개별 도구를 직접 호출할 수 있습니다.

수동 서버 시작 (고급):

make run-research-server # stdio 전송 (stdio transport)
make run-writing-server # stdio 전송 (stdio transport)

합리적인 기본값과 함께 MCP 도구들을 조율하는 사전 구축된 슬래시 명령어 (slash commands)입니다. 모든 출력은 outputs/{topic-slug}/로 저장됩니다.

명령어	기능
`/research`	주제에 대한 심층 조사 (Deep research) → `research.md`
`/write-post`	기존 조사 내용을 바탕으로 LinkedIn 게시물 생성 → `post.md` + `post_image.png`
`/research-and-write`	전체 파이프라인: 주제 조사 후 이를 바탕으로 게시물 작성

예시:

/research-and-write

해당 스킬은 사용자에게 주제와 가이드라인을 요청한 후, 전체 파이프라인을 엔드 투 엔드 (end-to-end)로 실행합니다. 각 단계에서 무엇이 생성되는지 확인하려면 examples/를 참조하세요.

FastMCP를 통해 두 MCP 서버를 조율하는 독립형 채팅 UI입니다. 별도의 하네스 (harness)가 필요하지 않습니다. 주제를 입력하거나 (또는 .md / .txt 시드 파일을 업로드하면) 검색 카운터, 수집된 출처, 평가자-최적화 루프 (evaluator-optimizer loop), 이미지 생성 등 각 단계별 실시간 진행 상황과 함께 전체 파이프라인이 실행되는 것을 확인할 수 있습니다.

make run-ui

출력물은 outputs/{topic-slug}/에 저장됩니다 (스킬과 동일한 레이아웃).

스크립트 (Scripts) (터미널 전용, 스모크 테스트용)

make를 통해 터미널에서 직접 워크플로우를 실행합니다. 설정이 제대로 작동하는지 확인하고 빠른 스모크 테스트 (smoke tests)를 수행하는 데 유용합니다. 전체 엔드 투 엔드 출력 샘플은 [examples/](examples/)를 참조하세요.

테스트 워크플로우:

make test-research-workflow # 샘플 주제 조사 → test_logic/research.md
make test-writing-workflow # 조사 내용을 바탕으로 게시물 생성 → test_logic/post.md
make test-end-to-end # 두 단계를 순차적으로 실행

참고: test-writing-workflow를 실행하려면 test_logic/research.md 파일이 존재해야 합니다. 먼저 test-research-workflow를 실행하거나 test-end-to-end를 사용하세요.

전체 데이터셋 실행:

[datasets/](datasets/)

[datasets/](datasets/) 디렉토리에는 시드(seeds), 가이드라인(guidelines), 연구 문서(research documents), 정답 포스트(ground truth posts), 그리고 생성된 출력물(generated outputs)이 포함된 사전 구축된 LinkedIn 포스트 데이터셋이 들어 있으며, 이는 배치 실행(batch runs)과 평가(evaluation) 모두에 사용됩니다.

make run-dataset-writing # 모든 데이터셋 포스트에 대해 연구 + 작성 (이미지 포함)
make run-dataset-writing-no-image # 동일 작업, 이미지 생성 제외 (더 빠름)

본 워크숍에는 LLM-as-judge 평가 파이프라인(pipeline)이 포함되어 있습니다. 생성된 각 포스트를 수동으로 검토하는 대신, LLM이 품질 기준(구조, 어조, 정확성)에 따라 점수를 매깁니다. Opik은 실행 전반에 걸쳐 이러한 점수를 추적하므로, 프롬프트(prompt)나 파이프라인(pipeline)의 변경이 실제로 출력 품질을 개선했는지 측정할 수 있습니다.

make eval-dev # dev 분할 데이터에 대해 LLM judge 실행
make eval-test # test 분할 데이터에 대해 LLM judge 실행
make eval-online # 포스트를 즉석에서 생성 + judge 실행

각 명령은 실행 전 데이터셋을 Opik에 자동으로 업로드합니다. 평가 없이 업로드하려면(예: Opik UI에서 브라우징하기 위해), 다음을 사용하세요.

make upload-eval-dataset

├── src/
│ ├── research/ # Deep Research Agent MCP 서버
│ │ ├── server.py # FastMCP 엔트리 포인트
...

리소스	설명
Agentic AI Engineering Course	프로덕션급(production-grade) AI 에이전트를 출시하는 방법에 대한 당사의 전체 코스입니다. 34개의 레슨, 3개의 엔드 투 엔드(end-to-end) 포트폴리오 프로젝트, 수료증, 그리고 Discord 커뮤니티가 제공됩니다.
...



Louis-François Bouchard AI Engineer
Paul Iusztin AI Engineer
Samridhi Vaid AI Engineer

MIT License. 자세한 내용은 LICENSE를 참조하세요.

iusztinpaul/designing-real-world-ai-agents-workshop

요약

핵심 포인트

예시 2 — Harness Engineering (클릭하여 확장)

예시 3 — AI 엔지니어를 위한 Angine de Poitrine (클릭하여 확장)

댓글