프롬프트 조립
AI Agent용: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/prompt-assembly/index.md에 있습니다. 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.
매 턴마다 Worker는 모델이 보는 시스템 프롬프트를 구성합니다. 이 프롬프트는 PostgreSQL에 저장된 에이전트 컨텍스트에서 턴 시점에 해석되어 Worker에서 렌더링됩니다. 이 페이지는 각 구성 요소가 제어 플레인에서 Worker로 전달되는 경로, 각 구성 요소가 무엇인지, 그리고 조립이 어디에서 일어나는지를 설명합니다. Agent Computer Worker 및 AIGateway 문서를 기반으로 합니다.
시스템 프롬프트는 제어 플레인이 아니라 Worker에서 조립됩니다. 제어 플레인은 영구 Agent 문서, Skills, Agent 설정, 채팅 컨텍스트를 두 경로로 공급합니다. Worker는 이 사실들을 최종 프롬프트로 렌더링합니다.
두 데이터 채널
Worker는 제어 플레인으로부터 두 경로로 컨텍스트를 받으며, 각 경로는 서로 다른 부류의 데이터를 전달합니다:
| 채널 | 전달 내용 | 시점 |
|---|---|---|
turn_start.request_context |
agent-loop 설정(ai_agent.max_iterations, max_output_tokens, inactivity_timeout_ms)과 턴 로컬 사실(시그널과 턴 종류) |
루프가 시작되기 전에 TurnStart 봉투에 포함 |
AgentConversationContextBroker RPC |
영구 Agent 문서(SOUL/MISSION/DESIGN), 활성화된 skills, 대화 원본 채널, 인스턴스 타임존, agent 프로필 |
루프 시작 시 RuntimeFabric을 통한 RPC로 Worker가 가져옴 |
이 분리는 의도적입니다. 턴 로컬 사실은 매 턴마다 바뀌므로 turn_start를 통해 전달되고, 대화 범위 컨텍스트는 한 대화 안에서 턴 사이에 안정적이고 broker가 캐시하므로 Worker가 broker를 통해 가져옵니다. broker의 moduledoc은 명확히 밝힙니다: “이 RPC는 의도적으로 전사 메시지나 턴 로컬 요청 컨텍스트를 반환하지 않습니다. 전사 히스토리는 AIGateway가 소유하며, 턴 로컬 사실은 turn_start로 전달됩니다.”
제어 플레인이 제공하는 것
영구 Agent 문서
AgentConversationContextBroker는 Library.list_agent_documents/1을 통해 Agent의 영구 문서를 읽습니다. 문서는 soul, mission, design으로 반환됩니다. SOUL.md는 커뮤니케이션과 판단을 정의하고, MISSION.md는 책임을 정의하며, DESIGN.md는 시각 작업을 위한 디자인 시스템을 제공합니다.
활성화된 Skills
Library.runtime_skills_for_agent/1은 설명과 메타데이터를 포함한 Agent의 전체 유효 Skill 집합을 Worker에 전달합니다. Worker는 전체 집합을 skill_view에서 사용할 수 있도록 유지합니다. 모델에 표시되는 Skill 카탈로그를 구성할 때는 brain-recall-only: true를 선언한 Skill을 제외하므로, 모든 프롬프트에 나열하지 않고 Brain을 통해 해당 Skill을 발견할 수 있습니다.
대화 원본 채널
SignalsGateway.ConversationChannel은 AIGateway 대화가 선언한 제공자 채널을 투영합니다. 현재 채널 미러에서 그룹 라벨을 읽고 피어 Principal에서 DM 라벨을 읽습니다. lark 어댑터를 하나의 Lark/Feishu 표면으로 보고하며, 어댑터 도메인은 API 서버만 선택합니다. broker는 이 투영을 ConversationInfo.origin_channel로 보내므로, 내부 웨이크업의 ActorEvent 페이로드에 채널 객체가 없어도 대화 원본이 유실되지 않습니다.
Agent 설정(AppConfigure에서)
AgentConfig는 AppConfigure에서 루프 수준 설정을 해석하고 이를 turn_start.request_context.ai_agent에 스냅샷합니다:
ai_agent.max_iterations(기본값 90) — agent 루프의 반복 예산ai_agent.max_output_tokens(기본값 nil = 명시적 상한 없음) — 응답당 토큰 상한ai_agent.inactivity_timeout_ms(기본값 30분) — 턴이 비활성 상태로 허용되는 시간
이 설정은 개별 모델 응답이 아니라 actor 턴에 속하므로 turn_start에 실려 이동합니다.
Worker 측 조립
Worker의 system_prompt.ts가 최종 프롬프트를 구성합니다. 여기의 moduledoc은 설계를 명시합니다: “느리게 변하는 지침이 앞에 오고, 대화 범위 런타임과 skill 컨텍스트가 접미사를 이룹니다.” 블록은 순서대로 다음과 같습니다:
- 핵심 지침 — 턴의 컨텍스트에서 조립된 에이전트의 기본 동작 계약.
- 영구 Agent 문서 — broker 응답에서 렌더링된
SOUL,MISSION,DESIGN. - Skills — 활성화된 스킬 설명으로, 모델이 무엇을 사용할 수 있는지 알려줍니다.
- 채널 및 런타임 컨텍스트 — 대화 원본 채널, 워크스페이스 경로, 사용 가능한 도구 이름.
Worker는 매 턴마다 현재의 PostgreSQL 기반 컨텍스트에서 전체 프롬프트를 다시 렌더링하며, 캐시된 버전을 신뢰하지 않습니다. AIGateway는 감사용으로 이전 요청 지침을 보관하지만, 턴은 현재 상태를 렌더링합니다.
시스템 프롬프트에 포함되지 않는 것
- 전사 히스토리 — AIGateway의 상태 저장 Responses가 소유하며, 시스템 프롬프트는 이를 반복하지 않습니다.
- 턴 로컬 관찰 — 시그널, 수신 메시지, 사용자의 현재 입력. 이들은 시스템 프롬프트가 아니라 현재 사용자 메시지에 남습니다.
이 분리는 시스템 프롬프트를 안정적으로 유지하고(대화가 커질 때가 아니라 페르소나나 스킬이 바뀔 때 변경), 턴당 페이로드를 작게 유지합니다.
이 가이드가 아닌 것
이 가이드는 프롬프트 엔지니어링 튜토리얼이 아닙니다 — system_prompt.ts의 리터럴 문자열은 모델과의 계약이며, 이를 바꾸는 것은 문서 변경이 아니라 동작 변경입니다. 제어 플레인 측의 프롬프트 조립 설명도 아닙니다 — 조립은 Worker에서 일어나며 제어 플레인의 역할은 데이터를 제공하는 것입니다. 그리고 system_prompt.ts를 읽는 것을 대신하는 것도 아닙니다. 이 가이드는 그 파일로 가는 지도입니다.
다음 단계
- 이 프롬프트를 사용하는 agent 루프에 대해서는 에이전트 루프를 읽으세요.
- 조립을 실행하는 Agent Computer Worker에 대해서는 Agent Computer Worker를 읽으세요.
- 스킬 블록에 대해서는 Agent Library를 읽으세요.