LlamaIndex 에이전트 만들기

LlamaIndex 에이전트 만들기

LlamaIndex에서 에이전트(agent)는 LLM이 구동하는 반자율(semi-autonomous) 소프트웨어예요. 작업을 받으면 그 작업을 해결하기 위해 일련의 단계를 실행하죠. 에이전트는 도구(tool) 집합을 부여받는데, 이 도구는 임의의 함수부터 완전한 LlamaIndex 쿼리 엔진까지 무엇이든 될 수 있어요. 에이전트는 각 단계를 완료할 가장 좋은 도구를 스스로 고릅니다. 단계가 끝나면 작업이 끝났는지 판단해서, 끝났다면 사용자에게 결과를 돌려주고, 아직 더 단계가 필요하다면 처음으로 돌아가 반복해요.

LlamaIndex에서 에이전트를 만드는 방법은 크게 두 가지예요. '빌딩 워크플로' 섹션에서 다루는 처음부터 나만의 에이전틱 워크플로 만들기를 쓰거나, 미리 만들어진 에이전틱 워크플로를 쓰는 거예요. 미리 만들어진 것에는 단순한 함수/도구 호출 에이전트인 FunctionAgent, 여러 에이전트를 관리할 수 있는 AgentWorkflow가 있어요. 이 튜토리얼에서는 FunctionAgent로 함수 호출 에이전트를 만드는 방법을 다뤄요.

출처: 공식문서

시작하기

이 튜토리얼의 전체 코드는 에이전트 튜토리얼 저장소에서 찾을 수 있어요.

충돌을 피하고 깔끔하게 유지하기 위해, 새 Python 가상환경을 만들어 시작할게요. 어떤 가상환경 매니저를 써도 되지만 여기서는 poetry를 쓰겠어요.

poetry init
poetry shell

그리고 LlamaIndex 라이브러리와 유용하게 쓸 다른 의존성들을 설치할게요.

pip install llama-index-core llama-index-llms-openai python-dotenv

설치 중 문제가 생기면 더 자세한 설치 가이드를 확인하세요.

OpenAI 키 설정

우리 에이전트는 OpenAI의 gpt-4o-mini LLM으로 동작할 거라서 API 키가 필요해요. 키를 받았으면 프로젝트 루트의 .env 파일에 넣어주세요.

OPENAI_API_KEY=sk-proj-xxxx

OpenAI를 쓰기 싫다면 로컬 모델을 포함해 다른 어떤 LLM도 쓸 수 있어요. 다만 에이전트는 성능 좋은 모델을 요구해서, 작은 모델은 덜 안정적일 수 있다는 점만 알아두세요.

의존성 불러오기

필요한 LlamaIndex 컴포넌트를 import 하고, .env 파일에서 환경 변수를 불러올게요.

from dotenv import load_dotenv

load_dotenv()

from llama_index.llms.openai import OpenAI
from llama_index.core.agent.workflow import FunctionAgent

기본 도구 만들기

이 간단한 예제에서는 두 개의 도구를 만들 거예요. 하나는 숫자를 곱하는 도구, 하나는 숫자를 더하는 도구예요.

def multiply(a: float, b: float) -> float:
    """Multiply two numbers and returns the product"""
    return a * b


def add(a: float, b: float) -> float:
    """Add two numbers and returns the sum"""
    return a + b

보시다시피 이건 평범한 Python 함수예요. 어떤 도구를 쓸지 결정할 때 에이전트는 도구의 이름·파라미터·docstring을 보고 이 도구가 뭘 하는지, 지금 작업에 맞는지 판단해요. 그러니 docstring을 설명적으로 유용하게 작성하는 게 중요해요. 타입 힌트는 기대하는 파라미터와 반환 타입을 결정하는 데 쓰이죠.

LLM 초기화

오늘 작업은 gpt-4o-mini가 맡을 거예요.

llm = OpenAI(model="gpt-4o-mini")

API로 접근 가능한 다른 인기 모델(Mistral, Anthropic의 Claude, Google의 Gemini)을 골라도 돼요.

에이전트 초기화

이제 에이전트를 만들어 볼게요. 에이전트는 도구 배열, LLM, 그리고 어떤 에이전트가 될지 알려주는 시스템 프롬프트가 필요해요. 실전에서는 시스템 프롬프트가 보통 이보다 훨씬 더 상세하답니다.

workflow = FunctionAgent(
    tools=[multiply, add],
    llm=llm,
    system_prompt="You are an agent that can perform basic mathematical operations using tools.",
)

GPT-4o-mini는 이렇게 단순한 수학에는 사실 도구가 필요 없을 만큼 똑똑해요. 그래서 프롬프트에 도구를 쓰라고 명시한 거예요.

FunctionAgent 말고도 LlamaIndex에는 ReActAgent, CodeActAgent처럼 다른 프롬프팅 전략으로 도구를 실행하는 에이전트들도 있어요.

질문하기

이제 에이전트에게 간단한 수학을 시켜볼게요.

response = await workflow.run(user_msg="What is 20+(2*4)?")
print(response)

이건 비동기 코드예요. 노트북 환경에서는 그대로 동작하지만, 일반 Python에서 돌리려면 아래처럼 비동기 함수로 감싸야 해요.

async def main():
    response = await workflow.run(user_msg="What is 20+(2*4)?")
    print(response)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

실행하면 대략 다음과 같은 출력이 나와요.

The result of (20 + (2 times 4)) is 28.

한 가지 팁을 드릴게요. 일부 모델은 LLM 출력 스트리밍을 지원하지 않아요. 스트리밍은 기본적으로 켜져 있는데, 에러가 나면 FunctionAgent(..., streaming=False)로 스트리밍을 끌 수 있어요.

축하합니다! 가장 기본적인 형태의 에이전트를 만든 거예요. 다음으로 넘어가기 전에, 이어지는 가이드에서 미리 만들어진 도구를 어떻게 쓰는지 배워볼게요.

더 알아보기

에이전트 내부 동작을 더 깊이 이해하고 싶다면 FunctionAgent와 함께 AgentWorkflow를 비교해 보는 것도 좋아요. 여러 에이전트를 한데 모아 관리하는 멀티 에이전트 시스템은 'Multi-agent systems' 가이드에서 다뤄요.