도구 호출과 에이전트: create_agent

LLM은 똑똑하지만 손발이 없습니다. 실시간 날씨를 모르고, 계산도 자주 틀리고, DB 조회도 못 합니다. 도구 호출(Tool Calling)은 AI에게 손발을 달아 주는 기술입니다. AI가 '이 질문엔 계산기가 필요해'라고 판단하면 우리가 만든 파이썬 함수를 대신 실행해 달라고 요청하는 방식입니다.

에이전트 = 판단하고 행동하는 루프

체인은 정해진 조립라인을 한 방향으로 흐르지만, 에이전트(Agent)는 유능한 신입사원과 같습니다. 과제를 주면 '어떤 도구를 쓸지' 스스로 정하고, 도구 결과를 보고 '더 조사할지, 이제 보고할지' 판단하며, 끝날 때까지 이 루프를 반복합니다.

에이전트 루프 (ReAct 패턴)

1. 생각: 질문을 보고 도구가 필요한지 판단합니다
2. 행동: 필요한 도구를 인자와 함께 호출합니다
3. 관찰: 도구 실행 결과를 확인합니다
4. 반복: 답이 완성될 때까지 1~3을 반복하고, 최종 답변을 냅니다

@tool: 함수를 도구로 만드는 마법

커스텀 도구 만들기

from langchain_core.tools import tool

@tool
def get_exchange_rate(currency: str) -> str:
    '''지정한 통화의 원화 환율을 조회합니다. currency는 USD, JPY 같은 통화 코드입니다.'''
    # 실전에서는 환율 API를 호출합니다. 여기서는 예시 데이터입니다.
    rates = {'USD': 1350.5, 'JPY': 9.2, 'EUR': 1480.0}
    rate = rates.get(currency.upper())
    if rate is None:
        return f'{currency}는 지원하지 않는 통화입니다.'
    return f'1 {currency.upper()} = {rate}원'

@tool
def calculate(expression: str) -> str:
    '''수식 문자열을 계산합니다. 예: "1350.5 * 100"'''
    return str(eval(expression))  # 실습용. 실전에서는 안전한 파서 사용

주목할 점은 docstring(함수 설명)입니다. AI는 이 설명을 읽고 '언제 이 도구를 쓸지' 판단합니다. 도구 설명은 사람이 아니라 AI가 읽는 사용설명서이므로, 언제 쓰는 도구인지와 인자의 의미를 구체적으로 적을수록 에이전트가 똑똑해집니다.

create_agent: 1.0의 표준 에이전트

에이전트 조립하고 실행하기

from langchain.agents import create_agent

# 모델 + 도구 + 시스템 프롬프트 = 에이전트
agent = create_agent(
    model='openai:gpt-4o-mini',
    tools=[get_exchange_rate, calculate],
    system_prompt='너는 환율 도우미야. 도구를 활용해 정확하게 계산해서 답해.',
)

# 에이전트는 messages 형식으로 대화합니다
result = agent.invoke({
    'messages': [
        {'role': 'user', 'content': '100달러는 원화로 얼마야?'}
    ]
})

# 마지막 메시지가 최종 답변입니다
print(result['messages'][-1].content)
# 에이전트가 스스로: 환율 조회 -> 계산기 사용 -> 답변 생성

이 예제에서 에이전트는 우리가 시키지 않아도 get_exchange_rate('USD')를 먼저 호출하고, 그 결과로 calculate('1350.5 * 100')를 실행한 뒤 '135,050원입니다'라고 답합니다. 도구를 쓰는 순서를 AI가 스스로 정하는 것이 에이전트의 핵심입니다.

웹검색 도구 붙이기

실시간 웹검색 에이전트

# pip install langchain-tavily (Tavily 검색 API 키 필요)
from langchain_tavily import TavilySearch
from langchain.agents import create_agent

search = TavilySearch(max_results=3)  # 검색 결과 3개까지

agent = create_agent(
    model='openai:gpt-4o-mini',
    tools=[search],
    system_prompt='최신 정보가 필요하면 웹검색을 활용해. 출처 URL도 알려줘.',
)

result = agent.invoke({
    'messages': [{'role': 'user', 'content': '오늘 서울 날씨 어때?'}]
})
print(result['messages'][-1].content)

도구는 3~7개 정도가 적당합니다. 도구가 너무 많으면 AI가 어떤 걸 쓸지 헷갈려 성능이 떨어집니다. 비슷한 도구는 하나로 합치고, 도구 설명으로 역할을 명확히 구분해 주세요.

도구는 AI가 임의의 인자로 실행하는 코드입니다. DB 삭제, 파일 쓰기, 결제 같은 위험한 기능을 도구로 줄 때는 반드시 인자 검증과 사람 승인(human-in-the-loop) 절차를 넣으세요. 예제의 eval()도 실서비스에서는 절대 금물입니다.