수록 현황:261 건의 뉴스/91 개의 AI 도구/372 개의 오픈소스 프로젝트/64 개의 학습 자료
홈뉴스오픈소스모델AI 도구학습 자료
홈 / 오픈소스 / agents-from-scratch

agents-from-scratch

AI 에이전트를 처음부터 구축하는 완벽한 튜토리얼입니다. 이메일 도우미, 인간-기계 협업, 메모리 기능 및 Gmail 통합을 포함합니다.

Jupyter NotebookMITAgent
⭐ GitHubhttps://github.com/langchain-ai/agents-from-scratch
1,965
스타 수
+163
스타 증가율
Jun 16, 2026
최근 업데이트
1,691
클릭 수

Agents From Scratch - AI智能체 처음부터 구축 가이드

프로젝트 개요

이 저장소는 처음부터 지능형 에이전트(agents)를 구축하는 가이드입니다. Gmail API를 통해 이메일을 관리할 수 있는 "환경 인식" 에이전트를 단계별로 구축합니다. 이 프로젝트는 LangChain AI 팀에서 개발했으며, AI 에이전트 개발을 배우고 실습하기에 훌륭한 리소스입니다.

프로젝트 구조

핵심 구성 요소

프로젝트는 4개의 주요 부분으로 나뉘며, 각 부분은 Jupyter notebook과 해당 코드 구현을 포함합니다.

  1. 에이전트 기초 - 기본적인 에이전트 기능 구축
  2. 에이전트 평가 - 에이전트 성능 평가 메커니즘 구현
  3. 인간-기계 협업 - 인공 개입 및 검토 프로세스 통합
  4. 기억 시스템 - 장기 기억 및 학습 능력 추가

디렉토리 구조

  • notebooks/ - 교육용 Jupyter notebooks 포함
  • src/email_assistant/ - 이메일 도우미의 핵심 구현 코드
  • eval/ - 평가 관련 데이터 세트 및 도구
  • tests/ - 자동화 테스트 스위트

기술 요구 사항

환경 요구 사항

  • Python 버전: 3.11 이상 (LangGraph와의 최적 호환성을 위해)
  • 주요 종속성: LangGraph, OpenAI API, LangSmith

API 키 구성

다음 API 키를 구성해야 합니다.

  • OpenAI API 키 (언어 모델 호출용)
  • LangSmith API 키 (추적 및 평가용)

환경 설정

# Python 버전 확인
python3 --version

# 가상 환경 생성
python3 -m venv .venv
source .venv/bin/activate

# pip 업그레이드
python3 -m pip install --upgrade pip

# 프로젝트 설치 (편집 가능한 모드)
pip install -e .

환경 변수 구성

# 환경 변수 템플릿 복사
cp .env.example .env

.env 파일에 다음을 구성합니다.

LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"
OPENAI_API_KEY=your_openai_api_key

상세 기능 모듈

1. LangGraph 기초 입문

  • 파일: notebooks/langgraph_101.ipynb
  • 내용: 채팅 모델, 도구 호출, 에이전트와 워크플로의 차이점, LangGraph 노드/에지/기억 시스템, LangGraph Studio 사용을 포함한 LangGraph의 기본 개념 소개

2. 이메일 도우미 구축

  • Notebook: notebooks/agent.ipynb
  • 코드: src/email_assistant/email_assistant.py
  • 기능:
    • 이메일 분류 단계와 에이전트 응답 처리 결합
    • 완전한 이메일 처리 워크플로 구현
    • 이메일 자동 회신 기능 제공

3. 에이전트 평가 시스템

  • Notebook: notebooks/evaluation.ipynb
  • 데이터 세트: eval/email_dataset.py
  • 기능:
    • Pytest 및 LangSmith evaluate API를 사용하여 평가
    • LLM을 평가자로 사용하는 평가 메커니즘 구현
    • 도구 호출 및 분류 결정의 정확성 평가

4. 인간-기계 협업 (HITL)

  • Notebook: notebooks/hitl.ipynb
  • 코드: src/email_assistant/email_assistant_hitl.py
  • 기능:
    • 인공 검토 메커니즘 통합
    • 특정 도구 호출에 대한 인공 확인 지원 (예: 이메일 보내기, 회의 예약)
    • Agent Inbox를 인간-기계 상호 작용 인터페이스로 사용

5. 기억 시스템

  • 코드: src/email_assistant/email_assistant_hitl_memory.py
  • 기능:
    • 사용자 피드백에서 학습하고 적응
    • LangGraph Store를 사용하여 기억 지속
    • 개인화된 기본 설정 지원

6. Gmail 통합

  • 코드: src/email_assistant/email_assistant_hitl_memory_gmail.py
  • 기능:
    • 실제 Gmail API 연결
    • 완전한 이메일 관리 기능
    • LangGraph Platform에 배포 지원

테스트 시스템

자동화 테스트 스위트

프로젝트에는 이메일 도우미 구현의 정확성을 검증하기 위한 완전한 자동화 테스트 시스템이 포함되어 있습니다.

# 기본 구현 테스트 실행
python tests/run_all_tests.py

# 특정 구현 테스트 실행
python tests/run_all_tests.py --implementation email_assistant_hitl

# 모든 구현 테스트 실행
python tests/run_all_tests.py --all

# 실험 이름 지정하여 LangSmith 추적
python tests/run_all_tests.py --experiment-name "Custom Test Run"

테스트 가능한 구현 버전

  • email_assistant - 기본 이메일 도우미
  • email_assistant_hitl - 인간-기계 협업 버전
  • email_assistant_hitl_memory - 기억 기능이 있는 HITL 버전
  • email_assistant_hitl_memory_gmail - Gmail 통합 버전

평가 지표

  • 에이전트 추적의 시각적 검사
  • 상세한 평가 지표
  • 다양한 에이전트 구현의 비교 분석

배포 설명

LangGraph Platform 배포

프로젝트는 LangGraph Platform에 배포하여 생산 환경의 에이전트 서비스를 구현할 수 있습니다.

Gmail 도구 설정

src/email_assistant/tools/gmail/README.md의 지침에 따라 Google API 자격 증명을 설정해야 합니다.

학습 경로 제안

  1. 초보자: LangGraph 101 notebook부터 시작하여 기본 개념 이해
  2. 실무자: 네 개의 주요 notebook을 순서대로 완료하여 완전한 기능 구축
  3. 개발자: src 디렉토리의 구현 코드를 연구하여 엔지니어링 실습 이해
  4. 배포자: Gmail API를 구성하고 생산 환경에 배포

기술 특징

  • 점진적 학습: 기초에서 고급으로, 단계별 진행
  • 실제 응용: 실제 이메일 처리 시나리오
  • 완전한 엔지니어링: 테스트, 평가, 배포를 포함한 완전한 솔루션
  • 확장성: 원리를 다른 에이전트 작업에 적용 가능