Rubrics 소개: 자신의 작업을 평가하고 수정하는 에이전트 구축하기

핵심 요약 (Key Takeaways)

• 에이전트(Agents)는 종종 올바른 방향으로 향하는 출력을 생성하지만

한 번 연결해 두면, 호출(invoke) 시점에 rubric 문자열을 전달하기만 하면 됩니다. (rubric이 없으면 미들웨어는 아무 작업도 수행하지 않습니다.)

1) RubricMiddleware 정의하기

이 미들웨어는 기본 에이전트(base agent) 위에 *채점 루프 (grader loop)*를 추가합니다. 채점기(grader)는 다음과 같이 구성됩니다:

• model: 채점에 사용되는 LLM (종종 메인 에이전트 모델보다 작고 저렴한 모델을 사용합니다)
• system_prompt: 채점기의 역할과 무엇이 "좋은" 결과인지 정의하는 지침
• tools: 채점기가 증거를 수집하기 위해 호출할 수 있는 선택적 도구들 (예: 테스트 실행, 린트(lint), 출력값 검증 등)
• max_iterations: 실행이 중단되기 전까지 수행할 수정(fix) → 재채점(re-grade) 루프의 최대 횟수

from deepagents import RubricMiddleware
rubric_middleware = RubricMiddleware(
    model="anthropic:claude-haiku-4-5",
    ...
)

2) deep agent에 전달하기

사용자의 deep agent 또한 자체적인 "운영 지침 (operating instructions)"을 가지고 있어야 합니다. 에이전트의 system_prompt는 에이전트에게 업무를 수행하는 방법을 알려주는 반면, 루브릭(rubric)은 채점기에게 업무를 판단하는 방법을 알려줍니다.

아래 코드 스니펫에서:

• model: 솔루션을 생성하는 데 사용되는 LLM
• system_prompt: 에이전트를 위한 코딩 컨벤션(coding conventions) + 제약 사항
• middleware: 에이전트가 반복적으로 교정될 수 있도록 rubric_middleware를 부착

from deepagents import create_deep_agent
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    ...
)

3) 인간의 메시지 + 루브릭과 함께 호출하기

호출 시점에 다음을 제공합니다:

• messages: 인간의 요청 (및 선택적으로 이전 대화 내용)
• rubric: 채점기가 충족 여부를 표시해야 하는 줄바꿈으로 구분된 체크리스트

from langchain.messages import HumanMessage
result = agent.invoke(
    {
        ...
    }
)

채점기에게 정확성에 대해 추상적으로 추론하도록 요청하는 대신, 동작을 직접 검증할 수 있는 run_test_suite 도구를 제공합니다. 채점기는 판결을 내리기 전에 도구를 호출하여 확실한 증거를 수집할 수 있으며, 도구가 제공되지 않을 경우 대화 기록(transcript)을 바탕으로 추론하는 방식으로 전환합니다.

실제 사례 확인하기

위의 코드 생성 (code generation) 예시에서, 에이전트의 첫 번째 시도는 올바르게 보였으나 하나의 테스트를 통과하지 못했습니다. 채점기 (grader)는 다음과 같은 결과를 반환했습니다:

"하나의 테스트 실패: test_unhashable. 입력 리스트 내의 리스트와 같은 해시 불가능한 (unhashable) 타입을 만났을 때 함수가 TypeError와 함께 충돌합니다."

에이전트는 구현 내용을 수정하였고, 두 번째 반복 (iteration)에서 모든 테스트를 통과했습니다. 피드백은 단순히 "다시 시도하세요"와 같은 일반적인 내용이 아닙니다. 각 기준 (criterion)마다 고유한 판결이 내려지므로, 에이전트는 정확히 무엇을 수정해야 하는지 알 수 있습니다.

이 트레이스 (trace)에서 전체 예시를 확인하세요.

이것이 중요한 이유

에이전트의 출력은 확률적 (probabilistic)입니다. 즉, 동일한 프롬프트 (prompt)라도 한 번의 실행에서는 성공하고 다음 실행에서는 미달할 수 있습니다. RubricMiddleware는 이러한 변동성을 포착해야 하는 부담을 개발자로부터 시스템으로 전환합니다.

출력을 수동으로 검사하고 실패한 작업을 다시 실행하는 대신, "완료"의 상태가 어떠해야 하는지를 한 번만 정의하면 루프 (loop)가 나머지를 처리합니다. 각 재시도는 정보를 바탕으로 이루어집니다. 채점기가 무엇이 잘못되었는지 정확히 식별하고, 기준별로 타겟팅된 피드백을 생성하기 때문입니다.

결과적으로, 정확성이 중요한 작업에서 더욱 신뢰할 수 있는 에이전트를 구축할 수 있습니다.

더 알아보기

RubricMiddleware는 현재 베타 버전이며 API가 변경될 수 있습니다. 설정 (configuration), 관찰 가능성 (observability), 그리고 루브릭 영속성 (rubric persistence)을 포함한 전체 가이드는 문서를 참조하세요.