에이전트 프레임워크 문제 해결

이 페이지는 Agent Framework를 사용할 때 발생하는 일반적인 문제를 진단하고 해결하는 데 도움이 됩니다.

다음은 이 페이지에서 다루는 내용입니다.

설치 및 설정

일반적인 문제: 설치 실패, 가져오기 오류, API 인증 문제

확인:

  • Python 및 pip 버전
  • .whl 파일 무결성 및 경로
  • .env 파일 구성(API 키, 프로젝트 세부정보)
  • gcloud auth 설정(Vertex AI)
  • 종속 항목 설치(requirements.txt)
  • 가상 환경 활성화

에이전트 정의 문제

일반적인 문제: 에이전트가 예상대로 작동하지 않음, 도구가 호출되지 않음, agent.py에 오류가 있음

확인:

  • agent.py 코드 구문(린트 작업)
  • 에이전트 instruction 명확성 및 정확성
  • 도구 정의(이름, 설명, 파라미터)
  • 에이전트 속성(name, model, tools, flow) - 오타, 유효성
  • agent.py 내 코드 로직 - 디버깅에는 print 문 사용

실행 문제

일반적인 문제: CLI 명령어 실패(af run, af web, af test), 웹 UI 오류, API 서버 문제

확인:

  • CLI 명령어 구문 및 인수(--help)
  • 작업 디렉터리(에이전트 프로젝트 루트)
  • 터미널 오류 메시지(전체 오류 복사)
  • 포트 충돌(웹 UI/API 서버 - 다른 포트 사용해 보기)
  • 브라우저 호환성 (웹 UI)
  • 브라우저 콘솔 오류 (웹 UI)

평가 문제

일반적인 문제: 테스트 실패, 예상치 못한 평가 결과

확인:

  • *.test.json 파일 구문(유효한 JSON)
  • 테스트 파일 콘텐츠(쿼리, expected_tool_use, reference 정확성)
  • af test 명령어 또는 pytest 코드의 파일 경로
  • test_config.json의 평가 기준(사용된 경우)
  • 시각적 피드백을 위해 웹 UI에서 테스트 실행

일반적인 오류 메시지

  • 설치 관련 문제
  • API 키 또는 인증 문제
  • 잘못된 model 속성
  • 웹/API 서버의 포트 충돌

일반적인 문제 해결 팁:

  • 단순화 및 격리: 간단하게 시작한 후 단계적으로 복잡성 추가
  • 로그 확인: 터미널, Cloud Logging, 브라우저 콘솔
  • 문서 참고: 관련 섹션 다시 읽기
  • 온라인 검색: Stack Overflow, 포럼
  • 도움을 요청할 때 세부정보 제공: 코드, 오류, 단계, 환경