miniEvoAgent란 무엇인가요?
miniEvoAgent는 LLM 기반 에이전트가 어떻게 구성되고 개선되는지 학습하기 위한 컴팩트한 Python 프레임워크입니다. EvoAgentX에서 영감을 받은 이 프레임워크는 에이전트 실행, 도구 호출, 평가, 프롬프트 재작성, 자기 진화라는 핵심 개념을 유지하면서 대규모 에이전트 프레임워크의 복잡성은 제거했습니다.
현재 패키지 이름은 evo_repro입니다. 의도적으로 작은 설계 덕분에 각 메커니즘을 더 쉽게 읽고, 테스트하고, 확장할 수 있습니다. 워크플로 그래프, 메모리, 시각적 편집기, 벤치마크 어댑터 또는 대규모 도구 생태계를 제공하는 대신, 투명한 단일 작업 에이전트와 프롬프트 진화 루프에 집중합니다.
프레임워크 작동 방식
miniEvoAgent 애플리케이션은 몇 가지 핵심 구성 요소로 구성됩니다:
- PromptTemplate: 작업 입력을 프롬프트 템플릿에 삽입합니다.
- Action: LLM을 호출하고, 선택적으로 여러 라운드의 도구 실행을 수행하며, 최종 응답을 파싱합니다.
- Agent: 작업을 감싸 구조화된 메시지를 반환합니다.
- Evaluator functions: Exact match, 토큰 수준 F1, 정확도를 사용해 QA 예측을 평가합니다.
- PromptRewriter: 옵티마이저 LLM을 사용해 구체적인 피드백 예시를 바탕으로 수정된 프롬프트를 제안합니다.
- PromptSelector: 동일한 개발 세트에서 부모 프롬프트와 후보 프롬프트를 비교하고 더 나은 성능을 보이는 프롬프트를 유지합니다.
- evolve: 학습 실행, 피드백 생성, 재작성, 평가, 선택을 반복합니다.
주요 기능
- 최소한의 구조로 내부를 확인하기 쉬운 단일 작업 에이전트 추상화.
- 환경 변수 또는 로컬
.env파일을 통해 구성하는 OpenAI 호환 LLM 어댑터. - 여러 라운드의 도구 실행을 지원하는 OpenAI 스타일 함수 도구.
- 옵티마이저 LLM을 통한 피드백 기반 프롬프트 재작성.
- 점수가 향상되는 경우에만 후보를 수락하는 개발 세트 선택.
- 학습 실행, 재작성 입력, 개발 세트 점수, 선택 결정을 포함하는 진화 추적 정보.
- 원격 API 호출 없이 프레임워크 동작을 테스트할 수 있는 결정론적 가짜 LLM.
miniEvoAgent 설치
요구 사항
Python 3.10 이상을 사용하세요. 다음 PowerShell 명령은 저장소로 이동하고, 가상 환경을 생성 및 활성화하며, pip를 업데이트한 뒤 패키지를 편집 가능 모드로 설치합니다:
cd D:\Projects\RSIProject\student-project\Evo-repro
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .소스 코드를 학습하거나 수정하는 동안에는 편집 가능 설치가 유용합니다. 로컬 패키지 변경 사항을 Python 환경에서 즉시 사용할 수 있기 때문입니다.
OpenAI 호환 LLM 구성
기본 OpenAILLM 어댑터는 환경 변수 또는 로컬 .env 파일에서 설정을 읽습니다. PowerShell에서 다음과 같이 API 키와 모델을 설정하세요:
$env:OPENAI_API_KEY="your_api_key"
$env:OPENAI_MODEL="gpt-4o-mini"다른 OpenAI 호환 서비스를 사용하는 경우 엔드포인트를 설정하세요:
$env:OPENAI_BASE_URL="https://your-compatible-endpoint/v1"또는 .env.example을 .env로 복사한 뒤 동일한 구성 값을 추가할 수 있습니다.
기본 질의응답 에이전트 만들기
기본 에이전트에는 LLM, 프롬프트 템플릿, 출력 파서, 작업이 필요합니다. 그런 다음 에이전트는 간단한 실행 인터페이스를 통해 이러한 구성 요소를 제공합니다.
from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser
llm = OpenAILLM()
action = Action(
name="answer_question",
prompt_template=PromptTemplate(
template="Answer the following question:\n\n{question}"
),
llm=llm,
output_parser=TextOutputParser(),
)
agent = Agent(
name="qa_agent",
description="Answers a single user question.",
action=action,
)
message = agent.execute({
"question": "What is Retrieval-Augmented Generation?"
})
print(message.content)agent.execute에 제공하는 question 키는 템플릿의 {question} 자리 표시자에 대응합니다. 작업은 프롬프트를 생성하고, 구성된 LLM으로 전송하며, 반환된 텍스트를 파싱한 뒤 결과를 구조화된 메시지로 감쌉니다.
포함된 예제를 실행할 수도 있습니다:
python examples\simple_agent.py호출 가능한 Python 도구 추가
miniEvoAgent 도구는 Python 함수를 감싸는 얇은 래퍼입니다. 각 도구는 모델이 함수 호출에 사용할 수 있는 JSON 스키마를 제공하고 구조화된 ToolResult를 반환합니다.
패키지에는 get_word_length_tool이 포함되어 있으며, 이 도구는 tools 인수를 통해 작업에 연결할 수 있습니다:
from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser
from evo_repro import get_word_length_tool
agent = Agent(
name="tool_agent",
description="Answers a question and can use tools.",
action=Action(
name="answer_with_tools",
prompt_template=PromptTemplate(
template=(
"Answer the following question. "
"Use tools when useful:\n\n{question}"
)
),
llm=OpenAILLM(),
output_parser=TextOutputParser(),
tools=[get_word_length_tool],
),
)
message = agent.execute({
"question": 'How many characters are in "retrieval"?'
})
print(message.content)
print(message.metadata["tool_results"])LLM이 지원되는 함수를 요청하면 해당 작업이 함수를 실행하고 도구 결과를 대화에 반환합니다. 이 작업은 최종 모델 출력을 분석하기 전에 이 프로세스를 여러 차례 수행할 수 있도록 지원합니다. 도구 실행 기록은 message.metadata["tool_results"]를 통해 확인할 수 있습니다.
포함된 도구 예제를 다음 명령으로 실행합니다:
python examples\tool_agent.py프롬프트 자기 진화 이해하기
자기 진화 시스템은 통제된 피드백 및 평가 주기를 통해 프롬프트를 개선합니다.
- 현재 프롬프트를 학습 예제에 실행합니다.
- 예측, 기대 레이블, 평가 지표를 피드백 예제로 변환합니다.
- 옵티마이저 LLM을 기반으로 하는
PromptRewriter에 후보 프롬프트 하나를 생성하도록 요청합니다. - 동일한 개발 세트에서 기존 프롬프트와 후보 프롬프트를 모두 평가합니다.
PromptSelector를 사용해 더 나은 프롬프트를 유지합니다.- 설정된 세대 수만큼 이 과정을 반복합니다.
한 세대만 실행하려면 evolve_once(...)를 사용합니다. 이 함수는 EvolutionRoundTrace를 반환합니다. 여러 세대를 실행하고 최종 프롬프트와 전체 기록을 모두 받으려면 evolve(...)를 사용합니다.
원격 모델 없이 진화 감사하기
이 저장소에는 가짜 LLM 동작을 사용하는 결정론적 감사 예제가 포함되어 있습니다.
python examples\evolution_audit.py출력에는 각 세대의 기존 프롬프트, 학습 기록, 재작성 입력, 후보 프롬프트, 개발 세트 비교 결과, 수락 또는 거부 결정이 표시됩니다. 이를 통해 프롬프트 개선을 숨겨진 작업으로 취급하지 않고 최적화 과정을 직접 검토할 수 있습니다.
QA 예측 평가하기
내장 평가기는 의도적으로 단순화된 세 가지 QA 지표를 제공합니다.
- 완전 일치: 평가기의 비교 방식에 따라 예측이 기대 답변과 정확히 일치하는지 확인합니다.
- 토큰 수준 F1: 예측과 기대 답변 사이의 토큰 중복을 측정합니다.
- 정확도: 올바른 예측의 비율을 보고합니다.
이 지표는 진화 루프를 검증하고 시연하기 위해 설계되었습니다. 프로젝트 문서에서는 향후 특정 벤치마크나 작업에 적합한 평가기로 교체할 수 있다고 설명합니다.
테스트 모음 실행하기
저장소 루트에서 모든 테스트를 실행합니다.
python -m pytest집중 테스트 모음은 에이전트, 도구, 진화 동작을 다룹니다. 가능한 경우 가짜 LLM 구현을 사용하므로 API 키나 원격 모델 호출 없이도 대부분의 프레임워크 로직을 검증할 수 있습니다.
고급 팁
실시간 실험 전에 결정론적 테스트 사용하기
프롬프트 선택, 도구 처리 또는 진화 로직을 변경할 때는 가짜 LLM 예제와 테스트부터 시작합니다. 결정론적 출력은 오류를 재현 가능하게 만들고 프레임워크 버그와 실시간 모델 응답의 변동을 구분하는 데 도움이 됩니다.
각 세대의 추적 기록 검사하기
진화 실행을 최종 프롬프트만으로 평가하지 마세요. 기록된 학습 실행, 재작성기에 제공된 피드백, 후보 프롬프트, 개발 점수, 선택 결정을 검토하세요. 이러한 기록을 통해 후보가 수락되거나 거부된 이유를 확인할 수 있습니다.
학습과 개발의 역할을 구분해 유지하기
진화 과정은 학습 예제로부터 재작성 피드백을 생성하지만, 동일한 개발 세트에서 기존 프롬프트와 후보 프롬프트를 비교합니다. 선택 과정이 프레임워크의 의도된 절차를 따르도록 실험을 준비할 때 이 구분을 유지하세요.
구조화된 도구 결과 검사하기
도구를 사용하는 에이전트의 경우 최종 텍스트와 함께 message.metadata["tool_results"]를 확인하세요. 이를 통해 모델이 도구를 선택했는지, 실행이 성공했는지, 어떤 구조화된 결과가 반환되었는지 검증할 수 있습니다.
필요할 때 호환되는 사용자 지정 엔드포인트 사용하기
OPENAI_BASE_URL 설정을 사용하면 OpenAILLM이 OpenAI 호환 엔드포인트를 대상으로 요청을 보낼 수 있습니다. API 키와 선택한 모델이 해당 엔드포인트의 요구 사항에 맞는지 확인하세요.
프로젝트의 현재 범위 이해하기
miniEvoAgent는 EvoAgentX보다 의도적으로 범위가 좁습니다. 현재 워크플로 그래프, 다중 에이전트 오케스트레이션, 메모리, 휴먼 인 더 루프 기능, 벤치마크 통합, 시각적 편집, 광범위한 툴킷을 제공한다고 주장하지 않습니다. 로드맵에는 더욱 풍부한 워크플로 구성, 추가 프로바이더 어댑터, 벤치마크 로더, 재사용 가능한 툴킷, JSON 영속화, 추가 문서가 포함되어 있지만, 이는 현재 기능이 아니라 계획된 항목입니다.
재배포 전에 라이선스 확인하기
현재 프로젝트에는 라이선스 파일이 포함되어 있지 않습니다. 코드를 게시하거나 재배포하기 전에 적절한 라이선스를 추가하세요.
결론
miniEvoAgent는 LLM 에이전트 엔지니어링을 시작할 수 있는 작고 테스트 가능한 방법을 제공합니다. evo_repro 패키지를 사용하면 프롬프트 기반 에이전트를 구성하고, OpenAI 스타일 함수 도구를 추가하며, QA 성능을 측정하고, 실패를 바탕으로 프롬프트를 재작성하고, 개발 세트 평가를 통해 개선 사항을 유지할 수 있습니다. 간결한 아키텍처와 결정론적 예제 덕분에 에이전트 실행과 프롬프트 진화가 내부적으로 어떻게 작동하는지 학습하는 데 특히 유용합니다.