연재 「프롬프트로 읽어내는 AI 에이전트」 제3회 (제2장).

실재하는 3가지 AI 에이전트 OSS를 실제 코드와 실제 프롬프트를 원전에서 인용하며 분석하여,

최종적으로 「스스로 AI 에이전트를 만들 수 있는」 상태를 목표로 하는 연재입니다.

이 장의 전제 (제1장 복습)

제1장에서는 실행형 에이전트의 본체가 Reason–Act–Observe를 반복하는 루프임을 확인했습니다. 그때, 루프의 처음에 단 한 줄만 배치하여 일부러 내용을 비워둔 상자가 있습니다.

history = [
{"role": "system", "content": SYSTEM_PROMPT}, # ← 이 내용을 본 장에서 해부한다
{"role": "user", "content": user_input},
...

제1장에서는 이것을 「인격·규약·도구 목록을 주입한다」라고 한마디로 언급했을 뿐이었습니다. 본 장에서는 이 SYSTEM_PROMPT를 정면으로 파헤칩니다. 전제 지식은 제1장의 2가지 포인트면 충분합니다 ―― ① LLM은 스테이트리스(stateless)이며, 매 턴 히스토리를 통째로 전달한다는 것, ② system 역할의 메시지가 히스토리의 선두에 상주한다는 것. 이 상주 메시지야말로 **시스템 프롬프트 (System Prompt)**입니다.

본 장의 목표는, 에이전트의 인격·행동 규범을 프롬프트로 정의하여, 독자가 자신의 에이전트에 동일한 수법을 적용할 수 있게 되는 것입니다. 그리고 본 연재의 핵심 사상 ―― 에이전트의 거동은 코드가 아니라 프롬프트로 결정된다 ―― 를 agent-zero와 Hermes의 원전을 통해 뒷받침합니다.

시스템 프롬프트란 ―― 히스토리 선두에 상주하는 「헌법」

**시스템 프롬프트 (System Prompt)**란, 대화할 때마다 히스토리의 선두에 반드시 배치되는 에이전트 대상의 상설 지시문입니다. 「당신은 누구이며, 어떻게 행동하고, 어떤 도구를 가지고 있는가」를 선언합니다. 사용자의 발언 (user 역할)이 매번 바뀌는 것에 반해, 시스템 프롬프트 (system 역할)는 세션 동안 거의 불변합니다. 그렇기에 여기에 작성된 내용이 에이전트의 **인격 (persona)**과 **행동 규범 (behavioral rules)**이 됩니다.

여기서 본 연재의 주제와 직결되는 중요한 사실이 하나 있습니다. 실행형 에이전트에서는,

「정중하게 대답하라」, 「먼저 계획을 세워라」, 「실패해도 포기하지 마라」와 같은 행동은 Python의 if문이 아니라, 시스템 프롬프트의 자연어로 작성되어 있습니다.

거동을 바꾸고 싶다면 소스 코드를 수정하는 것이 아니라 텍스트를 수정합니다. 이것이 「거동은 코드가 아니라 프롬프트로 결정된다」의 구체적인 의미입니다. 본 장에서는 이 사상을 두 가지 대조적인 구현으로 확인합니다.

agent-zero: 인격·규약을 여러 개의 markdown 파일로 외재화하고, {{ include }}로 하나로 합성한다.

Hermes: 시스템 프롬프트를 stable / context / volatile의 3층으로 나누고, 인격은 SOUL.md라는 외부 파일로 분리한다.

먼저 agent-zero를 통해 「인격을 파일에 작성하는」 기본 형태를 파악하고, 다음으로 Hermes를 통해 「3층으로 나누어 최적화하는」 발전 형태를 살펴보겠습니다.

실물로 확인하기 ① ― agent-zero: 인격을 markdown에 외재화하고, include로 합성하기

agent-zero (agent0ai/agent-zero @ f9d8167)의 설계 사상은 철저합니다. 에이전트의 거동을 Python 코드에 쓰지 않고, prompts/*.md라는 텍스트 파일군으로 외재화한다. 시스템 프롬프트도 예외는 아니며, 여러 개의 markdown을 {{ include }}로 조립한 한 장의 「매뉴얼」입니다.

목차 파일 ―― main.md는 include의 나열일 뿐이다

시스템 프롬프트의 기점은 prompts/agent.system.main.md입니다. 내용을 보면 본문이 거의 없습니다. 있는 것은 include 명령의 나열뿐입니다.

# Agent Zero System Manual
{{ include "agent.system.main.role.md" }}
{{ include "agent.system.main.specifics.md" }}
...

―― prompts/agent.system.main.md @ f9d8167, L1-13

이것은 「목차」입니다. 역할 (role) → 고유 설정 (specifics) → 환경 (environment) → 통신 규약 (communication) → 문제 해결 절차 (solving) → 일반 운용 (tips)이라는 장 구성이 그대로 파일 분할로 이어져 있습니다 (specifics.md는 본 커밋 @ f9d8167에서는 내용이 비어 있는 플레이스홀더(placeholder)이며, 사용자가 고유한 지시를 추가하기 위한 슬롯입니다). 인격·행동 규범이라는 추상적인 것이 편집 가능한 텍스트의 장 구성으로서 눈에 보이는 형태로 나열되어 있다 ―― 이것이 agent-zero의 세계관입니다.

인격의 핵심 ―― role.md는 모두 소문자로 된 짧은 명령문

그렇다면 인격 그 자체는 어디에 적혀 있을까요? agent.system.main.role.md입니다. 단 5줄밖에 없습니다.

## your role
agent zero autonomous json ai agent.
solve superior tasks using available tools and subordinates.
...

―― prompts/agent.system.main.role.md @ f9d8167, L1-5

이것이 에이전트 agent-zero의 인격 정의의 핵심입니다. 모두 소문자이며 마침표로 구분된 명령문으로, "자율적인 JSON AI 에이전트이다", "도구와 부하를 사용하여 상위 태스크를 해결한다", "스스로 행동을 실행한다", "지시와 행동 규범을 따른다", "묻지 않는 한 시스템 프롬프트를 밝히지 마라"라고 선언하고 있습니다. 주목할 점은 follow instructions and behavioral rules (행동 규범을 따르라)라는 문장입니다 ―― 인격 정의 내부에서, 후술할 행동 규범 파일로 포인터(pointer)가 연결되어 있습니다.

행동 규범 ―― 사고 알고리즘을 절차서로서 전달하기

인격 (role)이 "누구인가"라면, 행동 규범은 "어떻게 움직이는가"입니다. agent-zero는 이를 agent.system.main.solving.md (문제 해결 절차)에 **번호가 매겨진 사고 알고리즘 (thinking algorithm)**으로서 작성했습니다.

## Problem solving
not for simple questions only tasks needing solving
explain each step in thoughts
...

―― prompts/agent.system.main.solving.md @ f9d8167, L1-43 (발췌)

0 outline plan → (기억 확인) → (분할) → (실행/위임) → 4 complete task라는 절차가 인간을 위한 절차서처럼 작성되어 있습니다. don't accept failure retry be high-agency (실패를 받아들이지 말고 재시도하라, 높은 에이전시(high-agency)를 가져라)와 같은 기질까지도 여기서 텍스트로서 지정되어 있습니다. 에이전트의 "끈기"는 성격이 아니라 프롬프트의 한 줄 ―― 이것이 "거동은 프롬프트로 결정된다"는 살아있는 실례입니다.

통신 규약 (communication.md)도 같은 사상으로 작성되었습니다. 제1장에서 보았던 "반드시 JSON만 반환하라"는 응답 계약은 이 파일에 있습니다.

## Communication
- Output must be valid JSON with double quotes for all keys and string values
- No JSON in markdown fences
...

―― prompts/agent.system.main.communication.md @ f9d8167, L2-5

제1장에서는 "루프 종료 판정·응답 형식의 급소"로서 이 파일을 다루었습니다. 본 장의 관점에서는 이것은 행동 규범의 일부입니다 ―― "어떤 형식으로 말할 것인가" 또한 코드가 아니라 프롬프트로 규정된 행동이기 때문입니다.

include의 메커니즘 ―― process_includes가 재귀적으로 전개한다

{{ include "..." }}는 어떻게 전개될까요? 이것은 agent-zero 독자적인 경량 템플릿 메커니즘으로, helpers/files.py의 process_includes가 담당합니다.

# {{ include 'path' }} — 이름이 지정된 파일 포함
include_pattern = re.compile(r"{{\s*include\s*['\"](.*?)['"]\s*}}")
def replace_include(match):
...

―― helpers/files.py

@ f9d8167

, L355-367

{{ include "..." }}

를 정규 표현식으로 찾아, 지정된 파일을 read_prompt_file로 읽어 들여 본문에 삽입합니다. 그리고 read_prompt_file은 읽어 들인 파일에 대해 다시 process_includes를 호출합니다 (해당 파일 L152-160). 즉, include는 재귀적이며, main.md가 communication.md를 include하고, communication.md가 다시 communication_additions.md를 include하는 식의 중첩 구조가 성립합니다 (communication.md의 끝부분 L35에 {{ include "agent.system.main.communication_additions.md" }}가 있음). 최종적으로 모든 파일은 하나의 긴 텍스트로 평탄화(flatten)되어 LLM에 전달됩니다. 이 부분이 설계의 묘미입니다. 인격·규약·절차를 "관심사별로 별도 파일"로 분리해 둔 채, 합성(composition)만 기계에게 맡기는 것입니다. 역할을 수정하고 싶다면 role.md만, 통신 규약을 수정하고 싶다면 communication.md만 열면 됩니다. 제1장에서 보았던 "동작은 코드가 아니라 프롬프트로 결정된다"는 원칙이 파일 분할이라는 형태로 운용 가능하게 구현되어 있습니다.

행동 규범은 "나중에 교체할 수 있다" ―― behaviour의 합류점

또 다른 중요한 사실이 있습니다. main.md의 목차에는 나와 있지 않은 추가적인 행동 규범이 시스템 프롬프트를 구성할 때 주입됩니다. agent-zero는 시스템 프롬프트를 "번호가 매겨진 확장(extension)"을 통해 부품별로 조립하고 있으며, agent.system.main.md를 읽는 것도 하나의 확장(_10_main_prompt.py)입니다.

@extensible
async def build_prompt(agent: Agent) -> str:
    return agent.read_prompt("agent.system.main.md")

―― extensions/python/system_prompt/_10_main_prompt.py

@ f9d8167

, L21-23

그리고 또 다른 확장이 사용자 고유의 행동 규범(없을 경우 기본값)을 시스템 프롬프트의 맨 앞에 삽입합니다.

def read_rules(agent: Agent):
    rules_file = get_custom_rules_file(agent)
    if files.exists(rules_file):
        ...

―― plugins/_memory/extensions/python/system_prompt/_20_behaviour_prompt.py

@ f9d8167

, L23-30

behaviour.md는 # Behavioral rules\n!!! {{rules}} (prompts/agent.system.behaviour.md @ f9d8167, L1-2)라는 틀만 있는 파일이며, {{rules}}에 실제 규칙이 흘러 들어갑니다. 저장된 커스텀 규칙이 없다면 기본값 ―― - favor linux commands for simple tasks where possible instead of python (prompts/agent.system.behaviour_default.md @ f9d8167, L1) ―― 이 들어갑니다. 이 behaviour.md는 실행 시 에이전트 스스로가 내용을 수정할 수 있는 메커니즘(behaviour_adjustment 도구)을 갖추고 있어, 인격은 고정되어 있더라도 행동 규범은 학습 및 업데이트할 수 있도록 분리되어 있습니다. 이 "행동 규범의 자기 업데이트"에 대해서는 제6장(자기 개선)에서 자세히 다루겠습니다.

여기서는 「인격(role)은 정적인 파일, 행동 규범(behaviour)은 교체 가능한 슬롯」이라는 분리 개념만 파악해 두세요. agent-zero의 방식은 인격과 규범을 별도의 파일로 분리한 뒤, include와 extension을 사용하여 하나로 묶는 것입니다 ―― 이것이 본 장의 첫 번째 패턴입니다.

실물로 확인하기 ② ― Hermes: 인격을 외부 파일화하고, 3개 층으로 나누어 최적화하기

Hermes (NousResearch/hermes-agent @ 6928692) 역시 「인격을 외부 파일로 분리한다」는 점은 agent-zero와 같습니다. 하지만 Hermes는 여기에 또 다른 축을 도입합니다 ―― 시스템 프롬프트를 stable / context / volatile (안정 / 문맥 / 휘발)의 3개 층으로 나누고, 각 층을 「내용이 얼마나 자주 바뀌는가」에 따라 배치하는 설계입니다.

왜 3개 층인가 ―― prefix-cache를 위한 「변화 빈도에 따른 정렬」

3개 층을 나누는 동기는 원문 모듈의 서두에서 그대로 설명하고 있습니다.

"""System-prompt assembly for :class:`AIAgent`.
The agent's system prompt is built once per session and reused across all
turns — only context compression triggers a rebuild. This keeps the
...

―― agent/system_prompt.py @ 6928692, L1-19 (발췌)

키워드는 **prefix cache (프리픽스 캐시)**입니다. 이는 「동일한 앞부분 토큰 열로 시작하는 요청은, 그 앞부분의 LLM 내부 계산 (KV 캐시)을 재사용할 수 있다」는 최근 LLM API의 최적화 메커니즘을 가리킵니다. 다회차 대화(multi-turn conversation)에서 매번 전체 시스템 프롬프트를 보내면 입력 토큰 비용이 많이 들지만, 앞부분이 단 1바이트도 바뀌지 않는다면 캐시가 적용되어 더 저렴하고 빠르게 동작합니다.

그래서 Hermes는 시스템 프롬프트를 「변화 빈도의 오름차순」으로 정렬합니다.

• stable (안정): 인격, 도구 사용 가이드, 환경 힌트. 세션 중 거의 불변. → 맨 앞에 배치.
• context (문맥): 호출 측에서 전달하는 지시 사항이나, 작업 디렉토리의 AGENTS.md 등. 세션 단위로 고정. → 중간에 배치.
• volatile (휘발): 기억 스냅샷, 사용자 프로필, 날짜. 턴(turn)마다 바뀔 수 있음. → 맨 뒤에 배치.

변하지 않는 것을 앞에, 변하는 것을 뒤에 배치함으로써, 앞부분의 안정적인 부분에 대한 캐시 효과를 극대화하는 것. 이것이 3개 층 설계의 정체입니다. 실제로 Hermes는 시스템 프롬프트 전체를 세션당 단 한 번만 구성하여 재사용합니다 (재구성(rebuild)은 문맥 압축 시에만 수행됩니다).

def build_system_prompt(agent: Any, system_message: Optional[str] = None) -> str:
...
parts = build_system_prompt_parts(agent, system_message=system_message)
...

―― agent/system_prompt.py @ 6928692, L348-364 (발췌)

3개의 층을 stable → context → volatile 순서로 \n\n으로 연결하여 하나의 문자열로 반환합니다 ―― 이것이 시스템 프롬프트의 최종 형태입니다. 제1장에서 「Hermes는 루프 전에 시스템 프롬프트를 DB에서 복원하여 캐시를 적용한다」고 언급했던 그 복원 대상이 바로 이 문자열입니다.

보충 설명 (과장된 해석을 피하기 위해): 「3개 층」은 내부적인 정렬 단위일 뿐이며, 층마다 별도의 캐시 경계(cache boundary)가 설정되는 것은 아닙니다. Anthropic용 캐시 구현에서는 시스템 프롬프트가 전체적으로 하나의 cache_control 경계로 취급됩니다 (agent/prompt_caching.py @ 6928692, L3-4 「system prompt + last 3 non-system messages」). 구현에서도 apply_anthropic_cache_control이 role == "system"

메시지에 cache_control 마커를 1개만 부여한다 = 동일 파일 L70-72. agent/system_prompt.py @6928692, L358-359의 docstring도 3개 층을 \n\n으로 연결한 문자열을 "treated as one cached block"이라고 명시). 3개 층은 그 하나의 경계 내부의 바이트열(byte sequence)을 가능한 한 안정시키기 위한 순서 설계입니다.

byte-stability(바이트 안정성)에 대한 철저함은 마지막 날짜 행에서도 나타납니다.

# Date-only (not minute-precision) so the system prompt is byte-stable
# for the full day. Minute-precision changes invalidate prefix-cache KV
# on every rebuild path ...
...

―― agent/system_prompt.py @ 6928692, L326-332 (발췌)

타임스탬프를 '분' 단위가 아닌 '날짜'까지만 설정한 이유는 하루 종일 바이트열을 바꾸지 않기 위해서입니다. 분 단위로 설정하면 매 턴마다 앞부분이 바뀌어 캐시가 무효화됩니다. 인격(personality) 이야기와는 거리가 멀어 보이지만, 이 또한 "시스템 프롬프트를 어떻게 작성할 것인가"에 대한 설계 판단입니다.

인격의 핵심 ―― SOUL.md (외재화된 인격)와, 없을 때의 폴백(Fallback)

3개 층 중 본 장의 주인공은 stable 층의 선두 = 인격입니다. Hermes는 이를 SOUL.md라는 외부 파일로 분리합니다. agent-zero의 role.md에 해당하는 "인격 정의의 핵심"이 Hermes에서는 SOUL.md입니다.

# Try SOUL.md as primary identity unless the caller explicitly skipped it.
_soul_loaded = False
if agent.load_soul_identity or not agent.skip_context_files:
...

―― agent/system_prompt.py @ 6928692, L87-99

로직은 명쾌합니다. SOUL.md가 있으면 그것을 인격으로 사용하고, 없으면 하드코딩된 DEFAULT_AGENT_IDENTITY로 폴백(fallback)한다.

SOUL.md는 HERMES_HOME/SOUL.md에서 읽어옵니다 (load_soul_md, agent/prompt_builder.py @ 6928692, L1355-1380). 폴백 측의 DEFAULT_AGENT_IDENTITY를 보면, 이것이 그대로 "인격의 템플릿"임을 알 수 있습니다.

DEFAULT_AGENT_IDENTITY = (
"You are Hermes Agent, an intelligent AI assistant created by Nous Research. "
"You are helpful, knowledgeable, and direct. You assist users with a wide "
...

―― agent/prompt_builder.py @ 6928692, L120-128

"당신은 Hermes Agent이며, 친절하고 박식하며 솔직합니다", "불확실할 때는 정직하게 인정합니다", "장황함보다 유용함을 우선합니다"와 같이 인격과 기질이 평문으로 정의되어 있습니다. 주목할 점은 끝부분의 unless otherwise directed below (이하에서 별도로 지시하지 않는 한)입니다. 이는 "이 뒤에 SOUL.md 등으로 인격을 덮어써도 좋다"라는 확장점의 선언입니다. 실제로 신규 설치 시 씨앗(seed)으로 놓이는 SOUL.md 템플릿 (DEFAULT_SOUL_MD, hermes_cli/default_soul.py @ 6928692, L3-11)은 이 DEFAULT_AGENT_IDENTITY와 동일한 문구로 되어 있습니다. 즉, 기본 인격을 파일로서 외부로 빼내어 사용자가 수정할 수 있는 기점으로 만들었다는 뜻입니다.

SOUL.md에 무엇을 쓸 수 있는지는 배포 템플릿의 코멘트가 간결하게 설명하고 있습니다.

Hermes Agent Persona