Skip to main content
create_agent 품질은 도구 설계에서 크게 갈립니다. 도구는 많을수록 좋은 것이 아니라, 정확한 계약이 중요합니다.

1) 기본 도구 정의

from langchain.tools import tool

@tool
def search_docs(query: str) -> str:
    """내부 문서를 검색하고 요약 결과를 반환합니다."""
    return f"검색 결과: {query}"

@tool
def get_exchange_rate(base: str, quote: str) -> str:
    """기준 통화와 대상 통화의 환율을 반환합니다."""
    return f"1 {base} = 1350 {quote}"

2) 에이전트에 연결

from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4.1-mini",
    tools=[search_docs, get_exchange_rate],
)

3) 도구 계약 규칙

항목권장 규칙
함수명동작이 바로 드러나게 작성
docstring언제 써야 하는지 명시
인자단순하고 검증 가능한 타입 사용
반환LLM이 읽기 쉬운 텍스트/JSON 형태
오류 처리사용자에게 복구 가능한 오류 메시지 제공

4) 읽기/쓰기 도구 분리

  • 읽기 도구: 검색, 조회, 계산
  • 쓰기 도구: 메일 발송, DB 수정, 결제
쓰기 도구는 기본적으로 승인(HITL) 경유를 권장합니다.

5) 입문자 도구 세트 추천

  1. search_docs
  2. calculator 또는 도메인 계산기
  3. 외부 조회 API 1개
도구가 5개를 넘기기 시작하면 라우팅 정책 또는 멀티 에이전트를 고려합니다.

다음: 미들웨어

도구 실행 정책과 라우팅을 미들웨어로 분리합니다.

실무 적용 체크리스트

  • 목표와 성공 기준을 먼저 정의했습니다.
  • 예제를 현재 프로젝트 컨텍스트로 치환했습니다.
  • 실패 시 복구 절차를 문서화했습니다.
  • 다음 단계 문서로 연결해 학습 흐름을 유지합니다.

자주 나는 실수

  1. 학습 목표 없이 예제를 복사해 적용해 실패합니다.
  2. 성공/실패 기준이 없어 품질을 판단하지 못합니다.
  3. 다음 단계 연결 없이 문서를 단절적으로 소비합니다.

다음 문서

다음: LangChain 미들웨어

학습 흐름을 이어서 진행합니다.