Agent Behavior 소개
에이전트가 한 번의 작업에서 수백 번 판단하고 몇 시간을 일하는 상황이 되면, 그 결과를 최종 성공률 하나로 줄여 보기 어려워집니다. 답은 맞았는데 근거를 확인하지 않은 경우, 결과물을 만들었지만 검증 단계를 건너뛴 경우, 실패한 뒤 다른 경로를 시도하지 않고 그대로 끝낸 경우가 모두 같은 지표에 섞여 들어갑니다. 그래서 평가를 설계하려 하면 첫 질문이 "그러면 이 에이전트가 어떻게 행동해야 정상인가"로 돌아오는데, 그 기준은 대개 프롬프트와 스킬, 도구 설명, 예제, 기존 트레이스에 흩어져 있어 검토자가 매번 여러 곳을 읽어 종합해야 합니다.
이번에 소개할 Agent Behavior는 그 기준을 저장소 안의 마크다운 파일 한 개로 먼저 적어 두자는 공개 표준입니다. 파일 이름은 BEHAVIOR.md이고, 에이전트가 맥락을 모으고 판단하고 행동하며 아는 것이 부족할 때 회복하는 방식을 반복되는 행동 단위로 기록합니다. 평가자와 채점 기준, 채점기, 그리고 평가 자체보다 앞서 기준을 확정해 두는 것이 이 표준의 목적이며, 그래서 트레이스를 검토하고 평가를 설계하고 프롬프트를 맞출 때 참조할 단일 출처가 생깁니다.
이 표준은 Basis와 Braintrust의 협업으로 시작됐고, 규격 문서와 구조 검사 명령줄 도구, 그리고 실제로 실행되는 평가 예제 세 개가 한 저장소에 함께 들어 있습니다. 규격의 요구 수준은 RFC 2119의 MUST와 SHOULD, MAY로 표기되어 있어, 도구를 만드는 쪽과 규격을 쓰는 쪽이 각각 무엇을 반드시 지켜야 하는지 구분할 수 있습니다. 본 게시물에서는 BEHAVIOR.md의 형식과 권장 행동 차원, 규격에 담을 것과 빼야 할 것의 기준, 그리고 함께 공개된 검증 도구와 평가 예제를 정리합니다.
Agent Behavior와 스킬, AGENTS.md의 차이
에이전트에게 무언가를 마크다운으로 적어 주는 규약은 이미 여러 개 있습니다. AGENTS.md는 저장소 규칙과 작업 방식을 에이전트에게 알려 주는 문서이고, 스킬은 특정 작업을 더 잘 수행하도록 절차와 지식을 담아 실행 중에 읽히는 파일입니다. Agent Behavior는 파일 형식만 보면 이들과 비슷하지만 읽는 주체와 시점이 다릅니다:
| 항목 | Agent Behavior 행동 규격 | 스킬 |
|---|---|---|
| 파일 위치 | .agents/behaviors/{이름}/BEHAVIOR.md |
.agents/skills/{이름}/SKILL.md |
| 주 독자 | 트레이스를 검토하고 평가를 설계하며 프롬프트를 맞추는 사람과 에이전트 | 다음 작업을 수행하려는 모델 |
| 런타임(Runtime) 프롬프트 주입 | 행동 조건화 에이전트를 의도적으로 만드는 경우가 아니면 하지 않음 | 작업 수행을 돕기 위해 로드 |
| 주로 펼쳐 보는 시점 | 트레이스 검토, 평가 설계와 갱신, 프롬프트와 스킬과 도구 감사, 행동 회귀 디버깅, 기대 행동 문서화 | 작업 실행 중 |
이 구분을 저자들은 "Unlike skills, behaviors are not primarily loaded to help a model complete its next task." 라고 밝히면서, 클라이언트가 모든 행동 규격을 런타임 프롬프트에 주입하지 않아야 한다고 권고하고 있습니다. 같은 저장소 안에서 두 규약이 어떻게 갈리는지는 세금 조사 평가 예제가 잘 보여줍니다. 여기서 평가받는 에이전트는 런타임 스킬만 받고 행동 규격은 한 번도 받지 않으며, 규격은 그 에이전트의 트레이스를 채점하는 쪽에서만 쓰입니다.
Agent Behavior는 누구에게 맞는가
긴 작업을 수행하는 에이전트를 운영하면서 평가 기준을 사람마다 다르게 들고 있는 팀에게 이 표준이 실질적인 도움이 됩니다. 도입 비용이 마크다운 파일 하나이고, 기존 평가 도구를 바꾸지 않아도 되기 때문입니다. 규격이 문체와 구조를 강제하지 않고 프론트매터 두 필드만 요구하므로, 이미 내부 문서로 정리해 둔 기대 행동이 있다면 그 문서를 옮기는 것으로 시작할 수 있습니다.
반대로 명령줄 도구를 사내 도구 체계에 곧바로 붙이려는 팀에게는 아직 이르다고 보는 편이 맞습니다. agentbehavior 패키지는 버전 0.1.0이고 npm 레지스트리에 올라와 있지 않아, 저장소를 복제해 직접 빌드해야 합니다. 검사 범위도 구조에 한정되어 있어 규격의 품질은 사람이나 모델이 판단해야 합니다. 에이전트가 짧은 단발 작업만 하는 환경이라면 얻는 것이 적습니다. 저자들도 모든 지시를 행동 규격으로 옮기지 말라고 하면서, 드물고 위험이 낮은 세부 사항과 도구 문법, 일회성 절차, 구호, 평가 구현 세부는 제외하라고 안내합니다.
Agent Behavior의 BEHAVIOR.md 형식
행동 규격은 .agents/behaviors/ 아래에 자기 디렉토리를 하나 갖고, 그 안에 BEHAVIOR.md가 반드시 있어야 합니다. 디렉토리 이름이 그 규격의 안정적인 식별자이며 프론트매터의 name 필드와 일치해야 합니다. 근거 문서와 예시 트레이스, 배경 자료는 선택 항목인 references/ 디렉토리에 둡니다. 전체 구조는 다음과 같습니다:
.agents/behaviors/
└── cost-sensitive-actions/
├── BEHAVIOR.md # 필수, YAML 프론트매터 + 마크다운 본문
└── references/ # 선택, 근거와 예시, 배경 문서
파일은 YAML 프론트매터와 마크다운 본문으로 구성되고, 프론트매터의 제약은 다음과 같습니다:
| 필드 | 필수 | 제약 |
|---|---|---|
name |
예 | 64자 이하, 소문자와 숫자, 하이픈만. 하이픈으로 시작하거나 끝날 수 없고 부모 디렉토리 이름과 같아야 함 |
description |
예 | 1024자 이하, 비어 있을 수 없음. 이 규격의 적용 범위와 적용 시점을 서술 |
license |
아니오 | 라이선스 이름 또는 함께 넣은 라이선스 파일 참조 |
metadata |
아니오 | 클라이언트별 메타정보를 담는 키와 값 매핑 |
본문은 자유 형식입니다. 헤딩과 라벨, 순서, 서술 구조를 저자가 고를 수 있고 클라이언트는 그 구성을 자유 형식 콘텐츠로 다뤄야 합니다. 다만 본문이 해야 할 일은 정해져 있습니다. 반복되는 행동마다 이름을 분명히 붙이고, 언제 적용되는지와 바람직한 행동, 그리고 바람직하지 않은 행동이나 실패 모드를 적는 것입니다. 한 파일에 같은 에이전트나 같은 제품 표면에 속하는 행동 여러 개를 묶을 수도 있으며, 그때는 각 행동에 헤딩이나 라벨을 주고 독립적인 소유권과 재사용이 필요해지면 규격을 분리합니다.
Agent Behavior가 권장하는 여섯 가지 행동 차원
본문이 자유 형식이라 해도 검토와 평가로 옮기기 쉬운 형태는 따로 있습니다. 저자들은 실질적인 행동마다 아래 여섯 가지 차원을 고려하기를 강하게 권장합니다:
| 차원 | 무엇을 적는가 |
|---|---|
| 의도(Intent) | 이 행동이 왜 중요하고 언제 적용되는가 |
| 증거(Evidence) | 판단하기 전에 무엇을 확인하고 조회하고 보존하고 검증해야 하는가 |
| 판단(Decision) | 무엇을 추론하고 고르고 확신해야 하는가 |
| 실행(Execution) | 판단한 뒤 무엇을 해야 하는가 |
| 복구(Recovery) | 첫 경로가 실패하거나 증거가 불완전하거나 요청이 모호할 때 무엇을 해야 하는가 |
| 실패 모드(Failure modes) | 이 규격이 막으려는 잘못되거나 의도하지 않은 행동은 무엇인가 |
네 차원의 관계는 증거가 판단의 입력이고, 판단이 결론이며, 실행이 눈에 보이는 행동이고, 복구가 첫 경로 실패 시의 처리라는 순서입니다. 이 차원들은 유연한 지침이라 산문 안에 녹여도 되고 사소하거나 중복이면 합치거나 이름을 바꾸거나 생략해도 됩니다. 저장소의 비용 민감 행동 예제가 이 여섯 라벨을 그대로 쓴 형태이며, 실패 모드 항목은 "The agent SHOULD NOT silently choose an expensive path, hide material cost tradeoffs, spend paid resources without appropriate confirmation, or optimize for completion at the expense of the user's budget." 처럼 막으려는 행동을 직접 열거합니다.
Agent Behavior 규격에 담을 것과 빼야 할 것
무엇을 규격으로 만들지의 기준도 함께 제시되어 있습니다. 저자들이 좋은 후보로 꼽는 것은 여러 상호작용과 트레이스에 걸쳐 반복되고, 틀렸을 때 정확성이나 신뢰, 안전, 비용, 사용자 경험에 영향을 주며, 이 에이전트가 어떤 성격인지를 규정하는 설계 선택을 담은 행동입니다. 여기에 두 가지 기준이 더 있습니다. 명시하지 않으면 합리적인 에이전트나 프롬프트 작성자가 서로 다르게 행동할 만큼 기본값이 모호한 경우, 그리고 그 행동을 알아내려면 검토자가 프롬프트와 스킬, 도구 문서, 예제, 트레이스, 평가를 모두 읽어야 하는 경우입니다.
반대로 규격이 아닌 것도 분명히 적혀 있습니다. 드물고 위험이 낮은 세부 사항, 도구 문법, 일회성 절차, 구호, 평가 구현 세부는 중요한 행동적 약속을 표현하는 경우가 아니면 넣지 않습니다. 이 경계가 실제로 필요한 이유는 규격의 목적이 프롬프트를 대체하는 것이 아니라는 데 있습니다. 규격 하나가 사내 에이전트 지침 전체를 옮겨 담기 시작하면 검토자가 트레이스와 대조할 대상이 다시 흐려집니다.
Agent Behavior의 구조 검사와 평가 예제
검증은 두 겹으로 나뉩니다. 구조 유효성은 도구가 검사할 수 있고, 품질은 사람이나 모델의 판단이 필요합니다. 구조 검사는 저장소의 packages/agentbehavior 명령줄 도구가 담당하며, .agents/behaviors/ 아래의 디렉토리인지, BEHAVIOR.md가 있는지, 프론트매터가 YAML 매핑으로 파싱되는지, name과 description이 제약을 만족하는지, metadata가 키와 값 매핑인지를 봅니다. 구조가 유효하지 않은 규격은 클라이언트가 부분적으로 읽지 말고 건너뛰면서 진단만 알려 주기를 권고합니다.
이 도구는 npm에 배포되어 있지 않으므로 저장소를 복제해 직접 빌드합니다. Node 20 이상이 필요합니다:
git clone https://github.com/braintrustdata/agentbehavior
cd agentbehavior
pnpm install
pnpm build
pnpm exec agentbehavior validate .
명령은 세 가지입니다. validate는 구조 유효성을 검사하고, list는 발견한 규격 목록을 보여주고, explain은 규격 하나를 펼쳐 보여줍니다. 세 명령 모두 --json을 받아 기계가 읽는 출력으로 바꿀 수 있습니다:
agentbehavior validate .
agentbehavior list .
agentbehavior explain .agents/behaviors/cost-sensitive-actions
품질 쪽은 실행되는 평가 예제 세 개가 하나의 판정 규약을 보여줍니다. 세 예제는 금융 업무 검증, 고객 문의 분류, 그리고 세금 조사이고, 기록된 트레이스를 규격에 대고 true와 false, na 셋으로 판정합니다. 세금 조사 예제에서 채용한 규약이 특히 참고할 만합니다. 모든 H2 헤딩을 독립적인 메타 행동으로 보고 각각을, 그리고 발동된 각 사례를 따로 채점한 뒤, 모델이 아니라 코드가 그 판정들을 H2 단위와 파일 단위의 세 값으로 접습니다. 모델이 na를 낼 때는 유형화된 이유와 그 행동을 판정할 수 없었던 근거 기록을 함께 남기도록 했고, na는 준수율의 분모에서 빠집니다. 이 예제는 가상의 세법을 쓰며 세무 자문이 아니라 행동 평가를 보여주기 위한 것이라고 밝혀 두었습니다.
다만 예제를 그대로 돌려 보려면 준비물이 하나 더 필요합니다. 세 예제 모두 판정 모델을 Braintrust 게이트웨이로 호출하므로 BRAINTRUST_API_KEY를 요구하고, 로그 전송만 끄는 eval:local 스크립트가 따로 있을 뿐 키 없이 실행하는 경로는 없습니다. Braintrust는 이 표준을 함께 시작한 두 회사 중 한 곳이 운영하는 상용 평가 플랫폼입니다. 규격 형식 자체는 이 플랫폼에 묶여 있지 않아서, BEHAVIOR.md를 쓰고 구조 검사 도구를 돌리는 것까지는 계정 없이 할 수 있습니다.
규격을 처음 쓰는 사람을 위해 writing-agent-behavior 스킬도 함께 들어 있습니다. 에이전트가 규격을 작성하고 실제 트레이스에 맞춰 조정하는 것을 돕는 용도이며, 다른 저장소로 옮겨 쓸 수 있는 형태로 만들어져 있습니다.
Agent Behavior의 라이선스
Agent Behavior는 Apache 라이선스 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 규격 문서와 명령줄 도구, 예제가 모두 같은 저장소에 있으므로 별도의 라이선스 조건은 없습니다.
Agent Behavior 문서 사이트
Agent Behavior 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다. 
이 도구를 직접 설치해 사용해보셨다면, 
파이토치 한국 사용자 모임
회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 