langchain-ai/agents-from-scratch

이 저장소는 에이전트를 처음부터 구축하는 방법에 대한 가이드입니다. Gmail API 연결을 통해 이메일을 관리할 수 있는 '앰비언트(ambient)' 에이전트까지 구현합니다. 내용은 4개의 섹션으로 구성되어 있으며, 각 섹션에는 노트북과 src/email_assistant 디렉터리에 동반되는 코드가 있습니다.

이 섹션들은 에이전트의 기초부터 시작하여 에이전트 평가(agent evaluation), 인간 개입형 루프(human-in-the-loop)를 거쳐 최종적으로 메모리(memory)에 이르기까지 구성됩니다. 이 모든 원칙들이 결합되어 배포할 수 있는 에이전트를 만들며, 그 원리는 광범위한 다양한 작업의 다른 에이전트에도 적용될 수 있습니다.

• Python 3.11 이상을 사용해야 합니다.
• 이 버전은 LangGraph와의 최적 호환성을 위해 필수입니다.

python3 --version

• OpenAI API 키가 없다면 여기서 가입할 수 있습니다.

• LangSmith API 키를 생성합니다.

• 루트 디렉터리에 .env 파일을 만듭니다:

# .env.example 파일을 .env로 복사하세요
cp .env.example .env

• 다음 내용으로 .env 파일을 수정합니다:

LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"
...

• 터미널에서 환경 변수를 설정할 수도 있습니다:

export LANGSMITH_API_KEY=your_langsmith_api_key
export LANGSMITH_TRACING=true
export OPENAI_API_KEY=your_openai_api_key

권장: uv 사용 (더 빠르고 안정적)

# 아직 설치하지 않았다면 uv를 설치합니다
pip install uv
# 개발 종속성을 포함하여 패키지를 설치합니다
...

대안: pip 사용

$ python3 -m venv .venv
$ source .venv/bin/activate
# pyproject.toml을 사용한 편집 가능한(editable) 설치에는 최신 버전의 pip이 필요합니다
...

: 패키지 설치 단계를 건너뛰지 마세요! 이 편집 가능한 설치는⚠️ 중요하며 노트북이 올바르게 작동하는 데 필수적입니다. 패키지는 interrupt_workshop으로 설치되며 임포트 이름은 email_assistant를 사용하므로, 어디서든 from email_assistant import ...로 임포트할 수 있습니다.

저장소는 4개의 섹션으로 구성되어 있으며, 각 섹션별 노트북과 src/email_assistant 디렉터리에 동반되는 코드가 제공됩니다.

LangGraph와 이 저장소에서 사용된 일부 개념에 대한 간략한 소개는 LangGraph 101 노트북을 참고하세요. 이 노트북에서는 채팅 모델(chat models)의 기본, 도구 호출(tool calling), 에이전트 대 워크플로우(agents vs workflows), LangGraph 노드/엣지/메모리(LangGraph nodes / edges / memory), 그리고 LangGraph Studio에 대해 설명합니다.

• 노트북: notebooks/agent.ipynb
• 코드: src/email_assistant/email_assistant.py

이 노트북은 이메일 분류 단계와 이메일 응답을 처리하는 에이전트를 결합하여 이메일 비서(email assistant)를 구축하는 방법을 보여줍니다. 전체 구현에 대한 연결된 코드는 src/email_assistant/email_assistant.py에서 확인할 수 있습니다.

.

• 노트북: notebooks/evaluation.ipynb

이 노트북은 eval/email_dataset.py의 이메일 데이터셋을 사용하여 평가(evaluation)를 소개합니다. Pytest와 LangSmith evaluate API를 사용하여 평가를 실행하는 방법을 보여줍니다. LLM-as-a-judge 방식과 도구 호출 및 분류 결정에 대한 평가 모두를 수행합니다.

• 노트북: notebooks/hitl.ipynb
• 코드: src/email_assistant/email_assistant_hitl.py

이 노트북은 인간 개입(human-in-the-loop, HITL)을 추가하는 방법을 보여주어 사용자가 특정 도구 호출(예: 이메일 보내기, 회의 예약)을 검토할 수 있게 합니다. 이를 위해 에이전트 인박스(Agent Inbox)를 인간 개입 인터페이스로 사용합니다. 전체 구현에 대한 연결된 코드는 src/email_assistant/email_assistant_hitl.py에서 확인할 수 있습니다.

이 노트북은 이메일 비서에 메모리(memory)를 추가하는 방법을 보여주어 사용자 피드백으로부터 학습하고 시간이 지남에 따라 선호도에 적응할 수 있게 합니다. 메모리가 활성화된 비서(email_assistant_hitl_memory.py)는 LangGraph Store를 사용하여 메모리를 영속화합니다. 전체 구현에 대한 연결된 코드는 src/email_assistant/email_assistant_hitl_memory.py에서 확인할 수 있습니다.

위의 노트북들은 목업 이메일 및 캘린더 도구를 사용합니다.

Gmail Tools README의 지침에 따라 Google API 자격 증명(credentials)을 설정하세요.

README에는 그래프를 LangGraph Platform에 배포하는 방법도 설명되어 있습니다.

Gmail 통합의 전체 구현은 src/email_assistant/email_assistant_hitl_memory_gmail.py에 있습니다.

저장소에는 이메일 어시스턴트를 평가하기 위한 자동화된 테스트 스위트가 포함되어 있습니다.

테스트는 LangSmith를 사용하여 추적함으로써 정확한 도구 사용 및 응답 품질을 검증합니다.

python tests/run_all_tests.py

테스트 결과는 .env 파일에 지정된 프로젝트 이름(LANGSMITH_PROJECT) 아래 LangSmith에 기록됩니다. 이를 통해 다음이 가능합니다:

• 에이전트 추적(agent traces)의 시각적 검사
• 상세한 평가 지표
• 다양한 에이전트 구현 간의 비교

테스트 가능한 사용 가능한 구현체는 다음과 같습니다:

email_assistant

• 기본적인 이메일 어시스턴트

또한 모든 노트북이 오류 없이 실행되는지 확인하기 위해 테스트를 실행할 수도 있습니다:

# 모든 노트북 테스트 실행
python tests/test_notebooks.py
# 또는 pytest를 통해 실행
...

LangMem을 추가하여 메모리를 관리하세요:

• 배경 메모리(background memories) 모음 관리.
• 배경 메모리에서 사실을 조회할 수 있는 메모리 도구 추가.