행동 주석: readonly와 destructive가 LLM 계획을 안내하는 이유
Source: Dev.to
번역을 진행하려면 실제 번역이 필요한 텍스트(본문)를 제공해 주시겠어요?
본문을 알려주시면 원본 형식과 마크다운을 그대로 유지하면서 한국어로 번역해 드리겠습니다.
소개
이전 기사에서는 스키마가 apcore 생태계의 “우편배달부” 역할을 하여 데이터가 올바른 형식으로 전달되도록 보장한다는 점을 논의했습니다. 하지만 메시지를 전달하는 방법을 아는 것만으로는 자율 에이전트에게 충분하지 않습니다. 에이전트는 전달의 영향을 이해해야 합니다.
에이전트가 **“데이터 불일치 수정”**이라는 과제를 맡았다고 상상해 보세요. 에이전트는 common.user.sync와 executor.user.reset 두 모듈을 발견합니다. 행동적 맥락이 없으면 에이전트는 더 “철저해 보이는” 리셋 모듈을 선택할 수 있지만, 전체 사용자 프로필이 삭제된다는 사실을 인식하지 못합니다.
이 때문에 Behavioral Annotations는 apcore 프로토콜의 핵심 기술 기둥 중 하나입니다. 이번 열세 번째 기사에서는 이러한 단순한 불리언 플래그가 AI 플래너에게 “인지적 정지 신호” 역할을 하는 방식을 살펴봅니다.
행동 주석 개요
- Schemas는 구문을 처리합니다 (예: “문자열인가? 필수인가?”).
- Annotations는 의미를 처리합니다 (예: “안전한가? 영구적인가?”).
이 의미 레이어를 제공함으로써 우리는 “코드‑Calling”에서 “Skill‑Perceiving”으로 이동합니다. AI 에이전트는 더 이상 여러분의 모듈을 블랙 박스로 취급하지 않으며, 그들의 성격을 인식합니다.
표준화된 어노테이션
The apcore protocol defines a set of standardized annotations grouped into Safety, Execution, and Governance:
| Annotation | Meaning |
|---|---|
readonly | 부작용이 없습니다. 탐색 및 무한 재시도에 안전합니다. |
destructive | 데이터가 영구적으로 수정되거나 삭제됩니다. |
idempotent | 동일한 입력으로 여러 번 호출해도 한 번 호출한 것과 동일한 효과가 있습니다. |
pure | 출력이 입력에만 의존하며 외부 상태에 의존하지 않습니다. |
streaming | 모듈이 단일 블록이 아닌 이벤트/청크 스트림을 반환합니다. |
cacheable | 결과를 향후 사용을 위해 저장할 수 있습니다. |
cache_ttl | 결과가 유효한 기간(초)입니다. |
paginated | 결과가 시리즈의 일부이며, 계속하려면 커서/토큰이 필요합니다. |
requires_approval | 인간의 “예”(HITL)를 위해 실행을 일시 중지합니다. |
open_world | 비결정적 외부 시스템(예: 웹, 이메일)과 상호작용합니다. |
internal | 표준 탐색에서 숨겨져 있으며 시스템 간 호출에 사용됩니다. |
extra | 표면별 또는 맞춤형 동작 힌트를 위한 포괄적인 맵입니다. |
LLM이 이러한 플래그를 사용하는 방법 (계획 단계)
정교한 에이전트(예: Claude 3.5 또는 GPT‑4o)가 도구 목록을 받으면 행동 계획을 수립합니다.
- 모듈에
destructive: true가 표시되면 모델 내부의 안전 정렬이 종종 주의 상태를 트리거합니다. - 에이전트는 먼저 “드라이‑런” 플래그를 확인하거나 사용자에게 확인을 요청할 수 있습니다:
“이 문제를 해결할 방법을 찾았지만, 파괴적인 데이터베이스 작업이 필요합니다. 진행하시겠습니까?”
이러한 주석이 없으면 에이전트는 맹목적으로 동작하여 먼저 계획을 실행하고 나중에 결과를 알게 되며, 보통은 너무 늦습니다.
apexe를 이용한 자동 주석
자동 주석의 강력함은 기존 CLI를 래핑하는 도구인 apexe의 주요 특징입니다. 다음과 같이 실행하면:
apexe scan git이 도구는 매개변수를 추출하는 것 이상을 수행합니다; 패턴 매칭을 사용해 명령을 분류합니다:
git status및git log→readonly: truegit push --force및git reset --hard→destructive: true
도움말 텍스트를 단순히 스캔함으로써, apexe는 AI 에이전트가 실수로 프로덕션 브랜치를 파괴하지 않고도 저장소를 탐색할 수 있는 Safe Workspace를 생성합니다.
결론 및 다음 단계
AI를 위한 엔지니어링은 Cognitive Safety를 위한 엔지니어링을 의미합니다. apcore Behavioral Annotations을 사용하면 원시 함수를 “Professional Skills”로 전환하여 AI가 책임감 있게 계획할 수 있는 지혜를 제공하고, 토큰 낭비를 줄이며, 에이전트 재난을 방지합니다.
다음으로 AI의 Short‑Term Memory인 Context Object와 복잡한 모듈 체인 전반에 걸쳐 트레이스와 상태를 관리하는 방법을 살펴보겠습니다.
이 글은 apcore: Building the AI‑Perceivable World 시리즈의 Article #13입니다. Safety는 protocol‑level primitive입니다.
GitHub: