노트북에서 시작하기
노트북에서 'Hello World' 에이전트를 사용하여 Agent Framework를 시작합니다.
샘플 상담사
샘플 상담사의 예시 코드를 살펴보려면 이 Google Drive 폴더에서 .zip 파일을 로컬 개발 환경으로 다운로드합니다.
샘플 디렉터리에는 데모 에이전트가 있습니다. 특정 데모 에이전트의 requirements.txt 파일에 종속 항목을 설치합니다.
pip install -r samples/anthropic_demo/requirements.txt
다음 명령어를 실행합니다.
af web samples
af run samples/hello_world
튜토리얼
이 페이지에서는 에이전트 프레임워크를 사용할 때의 일반적인 작업에 관한 단계별 튜토리얼을 제공합니다. 시작하려면 튜토리얼을 선택하세요.
튜토리얼: 에이전트에 자체 데이터 통합
이 튜토리얼에서는 상담사에게 자체 데이터, 지식 또는 문서를 제공하는 다양한 방법을 설명합니다. 가장 적합한 접근 방식은 데이터의 크기와 유형, 지연 시간과 정확성 간의 원하는 균형에 따라 다릅니다.
자체 데이터 제공
데이터의 크기, 데이터 유형, 원하는 지연 시간 / 정확도 절충점을 기반으로 상담사에게 자체 데이터 / 지식/문서를 제공하는 방법에는 몇 가지가 있습니다.
| 유형 | 소량 | 대량 |
|---|---|---|
| 일반 텍스트 | 안내 또는 RAG에 삽입 | RAG |
| 문서 | 안내 또는 RAG에 삽입 | RAG |
| 기타 미디어 (이미지, 오디오, 동영상 등) |
진행 중 | 진행 중 |
다음 방법에서는 각 접근 방식에 대해 자세히 설명합니다.
안내에 데이터 삽입
상담사에게 소량의 문서를 제공하는 간단한 방법은 안내에 문서를 삽입하는 것입니다.
PDF 또는 기타 텍스트 파일을 일반 텍스트로 변환하여 안내에 삽입할 수 있습니다.
고려사항
파일의 콘텐츠가 모델로 전송되므로 파일이 클수록 지연 시간과 비용이 늘어납니다.
사용자의 쿼리가 콘텐츠와 관련이 없더라도 모든 요청의 콘텐츠가 모델에 전송됩니다.
파일에는 일반 텍스트 또는 읽을 수 있는 텍스트 형식(예: 마크다운)을 사용할 수 있습니다.
보안 위험
이러한 방식으로 콘텐츠를 삽입하면 서버가 삽입된 문서의 콘텐츠를 자체 안내로 간주할 수 있으므로 보안 위험이 있습니다.
아래 예와 같이 삽입된 콘텐츠의 시작과 끝을 명확하게 표시하면 이러한 보안 위험을 어느 정도 완화할 수 있습니다.
이러한 위험 때문에 신뢰할 수 없는 콘텐츠(예: 사용자 제작 콘텐츠)는 삽입하지 마세요.
예
안내를 읽기 쉽게 만들려면 일반적으로 파일을 로드하고 Python의 f 문자열 문법을 사용하여 안내에 삽입합니다.
XML 태그를 사용하여 파일의 콘텐츠를 나머지 안내문과 구분합니다. 모델에 명확하게 전달되는 한 다른 방법을 사용하여 구분할 수도 있습니다. 예: BEGIN_USER_GUIDE / END_USER_GUIDE과 같은 태그
def read_file(filename):
file_path = os.path.join(os.path.dirname(__file__), filename)
with open(file_path, 'r') as f:
return f.read()
agent_framework_bot = Agent(
# ...
instruction=f"""You are an agent that answers user's questions about the Agent Framework.
You answer users' questions based on the user guide below:
<user_guide>
{read_file('user_guide.md')}
</user_guide>
"""
)
RAG 사용
검색 증강 생성은 자체 데이터로 모델 응답을 보강하는 일반적인 패턴입니다. 데이터를 색인화하여 작동하고 쿼리와 관련된 소량의 데이터만 검색하므로 대용량 데이터에 특히 유용합니다.
상담사 프레임워크는 다양한 RAG 시스템과 통합하는 몇 가지 방법을 제공합니다.
| 시나리오 | 권장사항 |
|---|---|
| 데모 / 프로토타입 | FilesRetrieval |
| 소량의 데이터 (문서 몇 개) |
FilesRetrieval |
| 완전 관리형 RAG 솔루션 | VertexRagRetrieval |
| DIY 또는 기타 RAG 솔루션 | LlamaIndexRetrieval |
FilesRetrieval
FilesRetrieval은 상담사가 시작될 때 메모리 내 벡터 저장소를 빌드하며, 지연 시간이 추가되고 API 호스팅 환경의 메모리 및 성능으로 제한됩니다. 따라서 이 옵션은 데모 / 프로토타입 또는 문서 수가 매우 적은 프로덕션에만 적합합니다.
FilesRetrieval은 LlamaIndex를 기반으로 합니다. LlamaIndex 문서에 따라 설정해야 합니다.
설정이 완료되면 문서를 폴더에 넣고 다음과 같이 검색 도구를 만들 수 있습니다.
company_policies_retrieval = FilesRetrieval(
name='company_policies',
description='Company policies about flight cancelation and rebooking.',
input_dir=os.path.join(os.path.dirname(__file__), 'company_policies'),
)
root_agent = Agent(
# ...
tools=[company_policies_retrieval],
)
VertexRagRetrieval
Vertex RAG Engine은 데이터 수집, 변환, 임베딩, 색인 생성, 검색을 처리하는 완전 관리형 서비스입니다.
이를 사용하려면 빠른 시작에 따라 자료 모음을 설정하고 문서를 처리합니다. 그런 다음 상담사에게 도구를 추가합니다.
company_policies_retrieval = VertexRagRetrieval(
name='company_policies',
description='Company policies about flight cancelation and rebooking.',
rag_corpus_name='projects/.../locations/.../ragCorpora/...',
)
root_agent = Agent(
# ...
tools=[company_policies_retrieval],
)
Google 검색 사용하기
상담사는 Google 검색을 사용하여 실시간 실무 지식에 액세스하고 Google 검색을 통해 질문을 조사할 수 있습니다.
참고
- Google 검색을 사용한 그라운딩을 사용하면 추가 요금이 발생할 수 있습니다.
- Gemini 1.5의 경우:
- 상담사에게 Google 검색 도구를 추가하면 해당 상담사에게 다른 도구를 사용할 수 없습니다.
- Google 검색 도구는 검색어에 Google 검색이 필요한지와 관계없이 항상 실행됩니다.
- Gemini 2.0 이상:
- Google 검색 도구를 사용하는 동안 다른 도구를 사용할 수 있습니다.
- Google 검색 도구는 모델에서 필요하다고 판단하는 경우에만 실행됩니다.
- 서드 파티 모델은 Google 검색 도구를 지원하지 않습니다.
- Google 검색 도구를 사용하려면 관련 Google 검색어를 표시하는 배너를 항상 표시하는 등 Google 추천 검색어 사용의 가이드라인을 따라야 합니다. Google의 개발자 UI도 이러한 규칙을 따릅니다.
예
Google 검색 도구를 사용 설정하는 방법은 매우 간단합니다. 도구 목록에 google_search를 추가하기만 하면 됩니다.
from agents.tools import google_search
root_agent = Agent(
# ...
tools=[google_search],
)
튜토리얼: 상담사 실적 평가하기
에이전트가 예상대로 작동하고 품질 기준을 충족하는지 확인하려면 에이전트를 평가하는 것이 중요합니다. Agent Framework는 테스트 파일과 평가 기준을 사용하여 상담사 성능을 평가하는 여러 가지 방법을 제공합니다.
평가 작동 방식
각 테스트 파일에는 쿼리, 예상 도구 트rajectory, 참조 응답 목록이 포함됩니다. 테스트 파일은 폴더로 정리할 수 있습니다. 원하는 경우 폴더에 평가 기준을 지정하는 test_config.json 파일을 포함할 수 있습니다.
테스트 파일 예시
테스트 파일에는 쿼리, 예상되는 도구 사용, 참조 응답이 포함된 세션이 있습니다. 예를 들면 다음과 같습니다.
[
{
"query": "hi",
"expected_tool_use": [],
"reference": "Hello! What can I do for you?\n"
},
{
"query": "roll a die for me",
"expected_tool_use": [
{
"tool_name": "roll_die",
"tool_input": {
"sides": 6
}
}
]
},
{
"query": "what's the time now?",
"expected_tool_use": [],
"reference": "I'm sorry, I cannot access real-time information, including the current time. My capabilities are limited to rolling dice and checking prime numbers.\n"
}
]
평가 기준
test_config.json의 평가 기준은 상담사의 실적을 측정하는 방법을 정의합니다.
tool_trajectory_avg_score: 도구의 운동 궤적을 평가합니다.response_match_score: 대답을 평가합니다.
평가 기준을 제공하지 않으면 기본 구성이 적용됩니다.
평가 기준 예시 (test_config.json)
다음은 맞춤 평가 기준을 지정하는 test_config.json 파일의 예입니다.
{
"criteria": {
"tool_trajectory_avg_score": 1.0,
"response_match_score": 0.8
}
}
tool_trajectory_avg_score: 1.0으로 설정됩니다. 즉, 완벽한 도구 궤적 사용이 예상됩니다.response_match_score: 0.8로 설정하여 상담사의 응답에 약간의 오류 허용 범위를 허용합니다.
평가 실행 방법
1. af web - 웹 UI를 통한 평가 실행
웹 기반 UI를 사용하여 상담사를 양방향으로 평가할 수 있습니다.
단계:
bash af web를 실행하여 웹 서버를 시작합니다.- 웹 인터페이스에서 다음 단계를 따르세요.
- 에이전트를 선택합니다.
- '세션을 테스트 파일로 저장'을 클릭하여 세션을 테스트 파일로 저장합니다.
- '테스트 파일 실행'을 클릭하면 상담사 폴더에 테스트 파일이 포함된 팝업이 표시됩니다.
테스트 파일:
테스트 파일은 상담사와 동일한 폴더에 저장됩니다. 필요에 따라 테스트 파일을 수동으로 업데이트하거나 추가할 수 있습니다.
2. af test - 명령줄을 통한 테스트 실행
af test 명령어를 사용하여 지정된 폴더의 모든 테스트 파일을 실행할 수 있습니다.
폴더에는 에이전트 정의와 테스트 파일이 포함되어야 합니다.
예:
af test samples/agent_folder
이 명령어는 지정된 폴더에서 모든 테스트 파일 (*.test.json)을 찾아 실행합니다.
3. pytest - 프로그래매틱 방식으로 테스트 실행
pytest를 사용하여 통합 테스트의 일부로 테스트 파일을 실행할 수도 있습니다.
명령어 예시:
pytest tests/integrations/
테스트 코드 예:
다음은 단일 테스트 파일을 실행하는 pytest 테스트 사례의 예입니다.
def test_with_single_test_file():
"""Test the agent's basic ability via a session file."""
AgentEvaluator.evaluate(
"tests.integration.fixture.home_automation_agent",
"tests/integration/fixture/home_automation_agent/simple_test.test.json",
)
이 접근 방식을 사용하면 상담사 평가를 CI/CD 파이프라인 또는 더 큰 테스트 모음에 통합할 수 있습니다.