AI 애플리케이션을 구축하든 복잡한 작업을 자동화하든, AI 에이전트가 적절한 데이터와 도구로 작동하도록 만드는 일은 쉽지 않을 수 있습니다. 단순한 AI 시스템은 여러 소스에 걸쳐 추론하거나 정보를 검색하거나 작업을 처리해야 할 때 어려움을 겪는 경우가 많습니다. LlamaIndex 에이전트는 AI 모델을 도구, 데이터, 검색 시스템과 연결해 이런 작업을 더 효과적으로 처리할 수 있게 해줍니다. 이 글을 통해 더 스마트하고 유연한 AI 애플리케이션을 위한 LlamaIndex 에이전트 워크플로를 구축하고 배포하는 방법을 알아보세요.
LlamaIndex 에이전트란 무엇인가요?
LlamaIndex 에이전트는 작업에 대해 추론하고 작업을 완료하는 데 필요한 단계를 스스로 결정할 수 있는 AI 시스템입니다. 복잡한 요청을 더 작은 작업으로 나누고, 도구를 선택하며, 필요할 때 외부 데이터를 활용할 수 있습니다. 에이전트는 이전 단계를 기억하고 검색된 정보를 활용해 응답을 개선할 수도 있습니다. 이를 통해 단순한 질의응답 이상의 작업을 처리할 수 있습니다.
LlamaIndex 에이전트는 어떻게 작동하나요?
LlamaIndex 에이전트는 모델이 작업에 대해 추론하고, 도구를 선택하고, 다단계 워크플로를 완료할 수 있게 함으로써 LLM 애플리케이션이 단순한 질의응답을 넘어설 수 있도록 합니다. 고정된 파이프라인을 따르는 대신, 에이전트는 사용자의 목표와 사용 가능한 기능을 바탕으로 필요한 작업을 동적으로 결정합니다.
일반적인 LlamaIndex 에이전트 워크플로는 다음과 같은 과정을 따릅니다:
User request
↓
Understand the task
↓
Select tools
↓
Execute actions
↓
Process results
↓
Return final response사용자 목표 이해하기
에이전트가 요청을 받으면, 기반이 되는 LLM은 작업, 사용 가능한 컨텍스트, 연결된 도구를 분석해 최적의 접근 방식을 결정합니다.
단순한 질의의 경우 에이전트는 바로 응답을 생성할 수 있습니다. 복잡한 작업의 경우에는 요청을 더 작은 단계로 나누고 어떤 작업이 필요한지 결정할 수 있습니다.
도구 선택 및 사용하기
도구는 에이전트의 기능을 LLM 자체를 넘어 확장해줍니다. LlamaIndex 에이전트는 FunctionTool, QueryEngineTool과 같은 도구를 통해 커스텀 Python 함수, 쿼리 엔진, API, 데이터베이스, 검색 시스템에 연결할 수 있습니다.
예를 들어 에이전트는 검색 도구를 사용해 정보를 수집하거나, 데이터베이스 도구를 사용해 레코드를 조회하거나, 커스텀 함수를 사용해 계산을 수행할 수 있습니다.
에이전트 루프를 통해 작업 실행하기
도구를 선택한 후 에이전트는 해당 작업을 실행하고, 결과를 관찰하고, 다음 단계를 결정합니다. 이러한 추론-실행 루프를 통해 에이전트는 여러 작업이 필요한 복잡한 워크플로를 처리할 수 있습니다.
Reason → Act → Observe → Repeat작업이 완료되지 않은 경우 에이전트는 최종 답변을 생성할 때까지 도구 호출을 계속하거나 접근 방식을 조정할 수 있습니다.
컨텍스트와 워크플로 관리
LlamaIndex 에이전트는 실행 과정 전반에서 관련 컨텍스트를 유지하므로 다단계 작업을 관리하고 이전 단계의 결과를 활용하는 데 도움이 됩니다. 더 복잡한 애플리케이션의 경우 개발자는 워크플로와 멀티 에이전트 아키텍처를 사용해 여러 에이전트를 조율할 수 있으며, 이때 각 에이전트는 특정 역할이나 작업을 담당합니다.
예를 들어:
Research Agent
↓
Analysis Agent
↓
Writing Agent이러한 특성 덕분에 LlamaIndex react 에이전트는 AI 리서치 어시스턴트, 엔터프라이즈 지식 시스템, 자동화된 데이터 워크플로 같은 애플리케이션에 적합합니다.
LlamaIndex 에이전트의 핵심 구성 요소
LlamaIndex 멀티 에이전트는 여러 구성 요소를 결합해 LLM을 추론하고 외부 함수를 사용하며 컨텍스트를 유지할 수 있는 시스템으로 만듭니다. 각 구성 요소는 역할이 다르지만 함께 작동하여 에이전트가 작업을 더 효과적으로 처리할 수 있도록 돕습니다. 다음은 핵심 구성 요소 중 일부입니다.
LLM: 에이전트의 추론 엔진
LLM은 사용자 요청을 해석하고 다음에 무엇을 할지 결정하는 주요 추론 엔진 역할을 합니다. 사용 가능한 컨텍스트를 분석해 직접 답변할지 도구를 사용할지 판단할 수 있습니다. LlamaIndex는 다양한 LLM 제공업체를 지원하므로 개발자는 애플리케이션 요구 사항에 맞는 모델을 선택할 수 있습니다. 따라서 LLM은 에이전트의 의사 결정과 응답 생성을 제어합니다.
도구: 에이전트 기능 확장
도구를 사용하면 에이전트가 텍스트 생성 이상의 작업을 수행할 수 있습니다. 도구는 단순한 Python 함수일 수도 있고, API, 쿼리 엔진, 기타 외부 서비스와 작업하기 위한 전용 도구일 수도 있습니다. 에이전트는 사용자 요청을 바탕으로 어떤 도구를 사용할지 결정하고 필요한 입력을 제공합니다. 이후 도구 실행 결과는 대화에 추가되어 에이전트가 다음 단계에서 활용할 수 있습니다.
메모리: 컨텍스트 유지
메모리를 통해 LlamaIndex 에이전트는 작업을 완료하는 동안 관련 정보를 유지할 수 있습니다. 기본적으로 에이전트는 ChatMemoryBuffer를 사용하여 실행 중에 대화 기록을 유지합니다. 개발자는 애플리케이션에 맞춰 토큰 제한을 설정하는 등 메모리 구성을 커스터마이즈할 수도 있습니다. 이는 에이전트가 컨텍스트를 유지하고 여러 단계가 필요한 작업을 처리하는 데 도움이 됩니다.
LlamaIndex 에이전트의 유형
LlamaIndex는 필요한 추론 수준, 도구 사용, 제어 수준에 따라 작업을 처리하는 여러 에이전트 유형을 제공합니다. 주요 유형과 그 차이점을 살펴보겠습니다.
| 에이전트 유형 | 작동 방식 | 주요 기능 | 최적의 사용 사례 |
|---|---|---|---|
| FunctionAgent | 최신 LLM의 함수 호출 기능을 사용해 사용자 요청에 따라 미리 정의된 도구를 선택하고 실행합니다. | 네이티브 도구 호출 구조화된 입력 및 출력 신뢰할 수 있는 도구 실행 간단한 구현 | AI 어시스턴트 업무 자동화 워크플로우 API 기반 애플리케이션 작업 지향형 에이전트 |
| ReActAgent | 추론과 행동(Reasoning + Acting) 방식을 사용하며, 에이전트가 작업에 대해 반복적으로 추론하고 행동을 취하고 결과를 관찰하며 완료될 때까지 계속합니다. | 단계별 추론 동적 도구 선택 다단계 작업 처리 유연한 문제 해결 | 연구 어시스턴트 복잡한 질의응답 데이터 탐색 개방형 워크플로우 |
| CodeActAgent | 코드 기반 추론이 더 효과적인 경우 에이전트가 코드를 생성하고 실행해 작업을 해결할 수 있게 합니다. | 코드 생성 및 실행 프로그래밍 방식의 문제 해결 연산 작업에 적합 | 데이터 분석 과학 워크플로우 프로그래밍 어시스턴트 |
| 멀티 에이전트 시스템 | 여러 전문화된 에이전트가 협력하고 작업을 위임하며 함께 복잡한 워크플로우를 완료합니다. | 에이전트 협업 작업 위임 역할 전문화 확장 가능한 워크플로우 | 자동화된 연구 파이프라인 엔터프라이즈 워크플로우 복잡한 비즈니스 프로세스 |
이러한 에이전트들은 개발자가 다양한 작업과 워크플로에 맞는 접근 방식을 선택할 수 있는 유연성을 제공합니다. 에이전트 유형을 선택한 후에는 추론과 도구 사용을 뒷받침할 수 있는 강력한 LLM 백엔드에 연결하는 단계로 넘어갑니다. LlamaIndex와 Kimi API를 사용해 AI 에이전트를 구축하는 방법을 살펴보겠습니다.
LlamaIndex와 Kimi API로 AI 에이전트를 구축하는 방법은?
LlamaIndex를 LLM API에 연결하면 에이전트가 요청을 이해하고 올바른 작업을 선택하는 데 필요한 추론 능력을 얻게 됩니다. 다음 단계는 모델 구성부터 에이전트 실행까지, LlamaIndex와 Kimi API로 AI 에이전트를 설정하는 방법을 보여줍니다.
1단계: 사전 준비 사항
시작하기 전에 다음 사항을 준비하세요.
Python 3.9+ 설치
Moonshot AI Platform에서 발급받은 유효한 Kimi API 키
LlamaIndex 에이전트와 RAG 개념에 대한 기본적인 이해
2단계: 종속성 설치
원래 예제에서는 llama-index-llms-ollama를 사용합니다. Kimi의 OpenAI 호환 API에 연결하려면 이를 llama-index-llms-openai로 교체하세요. 로컬 무료 임베딩을 사용하려면 HuggingFace 임베딩 패키지는 그대로 유지하세요.
pip install llama-index llama-index-llms-openai llama-index-embeddings-huggingface3단계: 환경 변수 구성
Kimi API 키는 환경 변수를 사용해 안전하게 저장하세요. 스크립트에 직접 하드코딩하지 마세요.
export KIMI_API_KEY = "your-kimi-api-key-here"Windows(PowerShell)의 경우:
$env:KIMI_API_KEY = "your-kimi-api-key-here"4단계: Kimi API로 기본 에이전트 만들기
starter_kimi.py라는 이름의 파일을 만듭니다. 이 파일은 동일한 에이전트 로직과 도구 정의를 유지하면서 Ollama LLM을 Kimi로 대체합니다.
from llama_index.core.agent.workflow import FunctionAgent; import os
from llama_index.llms.openai import OpenAI; import asyncio
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings
# Configure global settings
Settings.llm = OpenAI(
model="kimi-latest", # Or: kimi-k2, kimi-k2.5, etc.
api_key=os.getenv("KIMI_API_KEY"),
api_base="https://api.moonshot.ai/v1",
temperature=0.3,
request_timeout=120.0,
)
Settings.embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-base-en-v1.5"
)
# Define a calculator tool
def multiply(a: float, b: float) -> float:
"""Useful for multiplying two numbers."""
return a * b
# Create the agent
agent = FunctionAgent(
tools=[multiply],
llm=Settings.llm,
system_prompt="You are a helpful assistant that can multiply two numbers.",
)
async def main():
response = await agent.run("What is 1234 * 4567?")
print(str(response))
if __name__ == "__main__":
asyncio.run(main())스크립트를 실행합니다:
python starter_kimi.py예상 출력:
The answer to 1234 * 4567 is 5635678.5단계: 채팅 기록(컨텍스트) 추가
여러 턴에 걸친 대화를 지원하려면 Context 객체를 전달합니다. 에이전트는 호출 간에도 메모리를 유지합니다.
from llama_index.core.workflow import Context
# Create context
ctx = Context(agent)
# Run agent with context
response = await agent.run("My name is Logan", ctx=ctx)
print(response)
response = await agent.run("What is my name?", ctx=ctx)
print(response)6단계: Kimi API로 RAG 기능 추가
문서 검색 기능을 추가하여 에이전트를 강화합니다. 임베딩 단계는 로컬에서 처리되고, 생성은 Kimi를 통해 이루어집니다.
샘플 데이터 준비
mkdir data
wget https://raw.githubusercontent.com/run-llama/llama_index/main/docs/examples/data/paul_graham/paul_graham_essay.txt -O data/paul_graham_essay.txtRAG 기능이 포함된 전체 에이전트 스크립트
starter_kimi_rag.py를 만듭니다:
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings; import os
from llama_index.core.agent.workflow import AgentWorkflow; import asyncio
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
# Global settings
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-base-en-v1.5")
Settings.llm = OpenAI(
model="kimi-k3",
api_key=os.getenv("KIMI_API_KEY"),
api_base="https://api.moonshot.ai/v1",
temperature=0.3,
)
# Load documents and build index
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
# Define tools
def multiply(a: float, b: float) -> float:
"""Useful for multiplying two numbers."""
return a * b
async def search_documents(query: str) -> str:
"""Useful for answering natural language questions about Paul Graham's essay."""
response = await query_engine.aquery(query)
return str(response)
# Create enhanced agent
agent = AgentWorkflow.from_tools_or_functions(
[multiply, search_documents],
llm=Settings.llm,
system_prompt="""You are a helpful assistant that can perform calculations
and search through documents to answer questions.""",
)
async def main():
response = await agent.run(
"What did the author do in college? Also, what's 7 * 8?"
)
print(response)
if __name__ == "__main__":
asyncio.run(main())스크립트를 실행합니다:
python starter_kimi_rag.pypython starter_kimi_rag.py7단계: RAG 인덱스 저장
매번 실행할 때마다 문서를 다시 처리하지 않으려면 벡터 인덱스를 디스크에 저장합니다.
# Save the index
index.storage_context.persist("storage")
# Later, load the index
from llama_index.core import StorageContext, load_index_from_storage
storage_context = StorageContext.from_defaults(persist_dir="storage")
index = load_index_from_storage(storage_context)
query_engine = index.as_query_engine()# Save the index
index.storage_context.persist("storage")
# Later, load the index
from llama_index.core import StorageContext, load_index_from_storage
storage_context = StorageContext.from_defaults(persist_dir="storage")
index = load_index_from_storage(storage_context)
query_engine = index.as_query_engine()문제 해결
에이전트를 설정하는 과정에서 문제가 발생하면 인증, 연결, 패키지 설치, 임베딩 속도와 관련된 몇 가지 흔한 문제가 원인일 수 있습니다. 아래 표는 가장 흔한 오류와 해결 방법을 정리한 것이니, 설정 문제를 빠르게 해결하는 데 참고하세요:
| 문제 | 원인 | 해결 방법 |
|---|---|---|
AuthenticationError | 잘못되었거나 누락된 API 키 | KIMI_API_KEY가 올바르게 export되었는지 확인하세요 |
Connection timeout | api.moonshot.ai로의 네트워크 지연 | request_timeout을 300.0 이상으로 늘리세요 |
ModuleNotFoundError | 패키지 누락 | pip install llama-index-llms-openai를 다시 실행하세요 |
| CPU에서 임베딩이 느림 | CPU에서 실행 중인 Hugging Face 모델 | 더 작은 모델을 사용하거나 GPU 가속을 활성화하세요 |
Kimi API 사용의 이점
에이전트를 연결해 정상적으로 작동시키면, LlamaIndex와 Kimi API의 조합은 강력한 AI 애플리케이션을 구축하는 데 여러 실질적인 장점을 제공합니다. LlamaIndex 에이전트와 함께 Kimi API를 사용할 때의 주요 이점은 다음과 같습니다:
더 스마트한 AI 에이전트 구축: Kimi API는 뛰어난 언어 이해력과 추론 능력으로 LlamaIndex 에이전트를 강화하여, 도구 선택, 정보 처리, 작업 완수를 더 효과적으로 수행할 수 있게 도와줍니다.
데이터 검색 및 분석 개선: LlamaIndex의 데이터 프레임워크와 결합하면, Kimi는 비공개 문서와 지식 베이스를 활용해 더 정확하고 맥락에 맞는 응답을 생성할 수 있습니다.
유연한 AI 워크플로 지원: LlamaIndex는 에이전트를 도구, API, 쿼리 엔진과 연결하고, Kimi는 이러한 기능을 언제 어떻게 사용할지 결정하는 데 필요한 지능을 제공합니다.
복잡한 AI 애플리케이션 지원: 긴 컨텍스트 이해력과 에이전트 기능을 갖춘 LlamaIndex 기반 Kimi API는 연구 어시스턴트, 지식 에이전트, 문서 분석 애플리케이션을 구축하는 데 적합합니다.
LlamaIndex 에이전트의 실제 활용 사례
LlamaIndex 에이전트는 AI가 추론하고, 정보에 접근하고, 행동을 취해야 하는 다양한 작업에 활용할 수 있습니다. LLM을 도구 및 데이터와 연결하는 능력 덕분에 연구, 비즈니스, 분석, 고객 지원 등 여러 분야에서 유용하게 쓰입니다. 실제 활용 사례는 다음과 같습니다:
AI 연구 어시스턴트
AI 연구 어시스턴트는 문서를 검색하고 관련 정보를 찾아내어 복잡한 질문에 답하는 데 도움을 줍니다. 연구 작업을 더 작은 단계로 나누고 필요에 따라 다양한 도구를 사용할 수 있습니다. 이를 통해 대량의 정보를 분석하고 상세한 응답을 준비하기가 더 쉬워집니다.
기업 지식 에이전트
기업 지식 에이전트는 직원들을 내부 문서, 데이터베이스, 지식 베이스와 연결할 수 있습니다. 관련 회사 정보를 검색하고 사용 가능한 비즈니스 데이터를 바탕으로 답변을 제공할 수 있습니다. 이를 통해 직원들은 여러 시스템을 일일이 찾아보지 않고도 더 빠르게 정보를 찾을 수 있습니다.
데이터 분석 에이전트
데이터 분석 에이전트는 데이터셋을 다루고 도구를 사용해 정보를 처리, 분석, 해석할 수 있습니다. 계산을 수행하고 패턴을 파악하며 결과를 쉽게 설명하는 데 도움을 줄 수 있습니다. 이는 보고, 데이터 탐색, 비즈니스 분석 같은 작업에 유용합니다.
고객 서비스 에이전트
고객 서비스 에이전트는 제품 정보, FAQ, 지원 자료에 접근하여 고객 문의에 응답할 수 있습니다. 도구를 사용해 관련 세부 정보를 조회하고 주어진 컨텍스트를 바탕으로 요청을 처리할 수 있습니다. 이를 통해 반복적인 지원 업무를 자동화하면서 더 빠르고 일관된 응답을 제공할 수 있습니다.
결론
LlamaIndex 에이전트는 추론하고 도구를 사용하며 관련 정보를 다룰 수 있는 AI 시스템을 구축하는 실용적인 방법을 제공합니다. 유연성이 높아 단순한 대화를 넘어서는 애플리케이션을 만드는 데 유용합니다. 적절한 LLM 백엔드를 사용하면 이러한 에이전트를 다양한 작업과 워크플로에 맞게 조정할 수 있습니다. Kimi API를 LlamaIndex와 함께 사용해 나만의 AI 에이전트를 구축하고 테스트해 보세요. Kimi를 살펴보고 무엇을 만들 수 있는지 확인해 보세요.