Harness Engineering 101 1장: 상태 비저장 API, 메시지 배열, 역할, 콘텐츠 블록, 그리고 하니스의 기본 구조를 설명합니다.
Harness Engineering 101, 제1부 — 연결선. 시리즈 목차 · 다음: 뇌
2023년 말, 나는 WSO2의 Synapse 언어에서 소프트웨어 통합을 위한 GitHub Copilot 같은 코딩 어시스턴트인 WSO2 MI Copilot를 만들고 있었다. 이것은 GPT-3.5에서 실행되었다. 에이전트도 캐싱도 없었고, 툴 호출을 쓰는 사람도 거의 없었다. 메시지 배열을 HTTP 엔드포인트로 보내면 형식화된 텍스트가 돌아왔고, 그게 전부였다. 우리의 배열에는 사용자의 전체 프로젝트가 담겼으며, 메시지를 보낼 때마다 다시 전송되었다.
지금도 일어나는 일은 그것이 전부이며, 이 시리즈 전체는 그 사실 위에 세워져 있다. 코드를 수정하고 풀 리퀘스트를 올려 주는 것을 포함해, 여러분이 본 모든 에이전트는 JSON 배열을 만들고, 이를 POST하고, 응답을 읽고, 배열을 갱신한 뒤 다시 POST하는 프로그램이다.
LLM은 뇌이고, 텍스트를 받을 수 있으며 텍스트를 내보낼 수 있을 뿐이다. 세상에서 무언가를 하는 것처럼 보일 때마다, 실제로 그것을 한 것은 다른 프로그램이다. 그 프로그램이 바로 하니스다. 즉, 뇌를 둘러싼 몸이다. 뇌와 몸 사이의 유일한 통로는 JSON 배열이다.
하니스 엔지니어링은 그 배열을 구축하고 유지보수하는 작업이다. 이 장에서는 배열 그 자체를 다룬다.
모든 SDK와 프레임워크를 걷어 내면, 최첨단 모델 호출은 다음과 같이 보인다:
import json, os, urllib.request
def call_llm(messages, system=""): body = { "model": "claude-sonnet-5", "max_tokens": 4096, "system": system, "messages": messages, } req = urllib.request.Request( "https://api.anthropic.com/v1/messages", data=json.dumps(body).encode(), headers={ "content-type": "application/json", "x-api-key": os.environ["ANTHROPIC_API_KEY"], "anthropic-version": "2023-06-01", }, ) with urllib.request.urlopen(req) as resp: return json.loads(resp.read())
전체 인터페이스는 HTTP POST 하나다. 딕셔너리 목록이 들어가고 딕셔너리 하나가 나오며, 소켓이나 세션, 핸드셰이크는 없다.
messages 배열은 대화 기록이다. 각 항목에는 role과 content가 있다:
[ {"role": "user", "content": "What does HTTP 418 mean?"}, {"role": "assistant", "content": "It means the server is a teapot. ..."}, {"role": "user", "content": "Is it ever used seriously?"} ]
배열을 보내면 모델이 이를 이어서 작성하고, 응답은 다음 assistant 메시지다.
API는 상태 비저장이다. 서버는 호출 사이에 아무것도 기억하지 않는다.
모델과 "대화"할 때 제공업체 측에 저장된 대화는 없다. 여러분의 프로그램이 배열을 보관하고, 새 메시지를 하나씩 추가하며, 매 턴마다 _전체 기록_을 다시 보낸다. 모델은 매번 전체 대화 기록을 처음부터 읽고 다음에 올 내용을 예측한다. 이전 메시지를 작성한 일을 기억하지 않는다. 절반의 줄이 assistant라고 표시된 대화 기록을 보고 "내가 그렇게 말한 모양이군"이라고 결론 내린다.
로딩 중
sequenceDiagram participant H as Harness (your program) participant A as API (stateless) H->>A: POST [msg1] A-->>H: reply1 Note over H: append reply1, append msg2 H->>A: POST [msg1, reply1, msg2] A-->>H: reply2 Note over H: append reply2, append msg3 H->>A: POST [msg1, reply1, msg2, reply2, msg3] A-->>H: reply3 Note over A: remembers nothing,<br/>ever
이 점을 이해하고 나면, 이 분야의 많은 것이 더 단순해진다:
유용한 한 가지 결과는 세션이 그저 파일이라는 점이다. 코딩 에이전트가 --resume을 제공하면, 디스크에서 JSON 배열을 불러와 계속 덧붙인다. /clear를 입력하면 구현은 본질적으로 다음과 같다:
messages = []
초기화할 서버 측 세션은 없다. Claude Code는 로컬 디렉터리에 세션을 JSONL 파일로 저장한다. 할 일 앱을 만들어 본 적이 있다면, AI 에이전트를 위한 세션 관리를 만드는 방법도 이미 알고 있는 셈이다.
배열에는 소수의 화자가 있다. 모델은 각 역할을 서로 다르게 취급하도록 훈련되었기 때문에 이 구분이 중요하다(여기서 "훈련"이 무엇을 의미하는지는 2장에서 설명한다):
system: 개발자가 모델에게 주는 지시로, 모델이 누구이며 어떤 규칙을 따르는지 등이 포함된다. 모델은 이를 사용자 텍스트보다 더 높은 비중으로 두도록 훈련된다. Anthropic은 이를 최상위 system 필드에 넣는다. OpenAI는 system 역할의 메시지를 사용하며, 최신 Responses API에서는 이를 developer로 이름 바꾸었다. 세 표기는 모두 같은 의미로, 하니스 작성자를 위한 권한 있는 채널이다.user: 인간의 차례다. 시리즈 뒤쪽에서 하니스 자체가 대화 도중 정보를 주입하기 위해 이 채널을 사용하는 것을 보게 될 것이다.assistant: 모델 자체의 이전 차례다. 여러분은 이들 중 어느 것도 작성하지 않았지만, 전부 저장하고 다시 전송한다. 다시 보내기 전에 수정할 수도 있으며, 모델은 알아차릴 수 없다. 이 사실은 12장에서 디버깅 도구가 되고 13장에서 안전성 문제가 된다.
처음에 content는 문자열이었다. 지금도 그럴 수 있지만, 현대 API에서는 타입이 지정된 블록의 목록이다:
{ "role": "user", "content": [ {"type": "text", "text": "What's wrong with this screenshot?"}, {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "iVBORw0KG..."}} ] }
텍스트, 이미지(JSON 안에 바로 들어가는 base64 바이트), PDF, 툴 호출, 모델의 사고 과정은 모두 블록이다. 모델이 보는 법을 배웠을 때도 배열은 모양을 유지했고 블록에 새 타입이 추가되었다. 2장에서는 뇌가 이미지 블록으로 무엇을 하는지 다루고, 3장에서는 툴 블록을 다룬다. 기억해야 할 핵심은 내년에 어떤 양식이나 기능이 출시되든, 같은 배열의 새 블록 타입으로 들어온다는 점이다.
실무에서는 두 가지 와이어 형식을 만나게 되며, 차이는 외형적인 것이다. 다음은 동일한 교환을 두 형식으로 나타낸 것이다:
Anthropic Messages API:
POST /v1/messages { "model": "claude-sonnet-5", "max_tokens": 1024, "system": "You are a terse assistant.", "messages": [ {"role": "user", "content": "Capital of Sri Lanka?"} ] }
OpenAI Chat Completions:
POST /v1/chat/completions { "model": "gpt-5.2", "messages": [ {"role": "system", "content": "You are a terse assistant."}, {"role": "user", "content": "Capital of Sri Lanka?"} ] }
알아둘 만한 차이는 다음과 같다:
| Anthropic | OpenAI (Chat Completions) | |
|---|---|---|
| 시스템 프롬프트 | 최상위 system 필드 | 첫 번째 메시지, system 역할 |
| 응답 위치 | response.content(블록 목록) | response.choices[0].message |
| 툴 결과 | user 메시지 안의 tool_result 블록 | 별도의 tool 역할 메시지 |
| 턴 규칙 | 역할은 user/assistant로 교대해야 함 | 자유 형식 |
OpenAI의 최신 Responses API는 이를 다시 재구성한다. messages 대신 input, developer 역할, 선택적인 서버 측 대화 저장소를 사용한다. 이 저장소는 상태 비저장에서 유일하게 실질적으로 벗어나는 부분이다. 제공업체가 여러분 대신 배열을 보관하겠다고 제안하는 것이다. Gemini는 자체 표기를 사용한다. 이들 모두는 통째로 전송된 뒤 한 번 이어지는, 역할 태그가 붙은 블록의 순서 있는 목록이다.
이것이 하니스에서 "어느 제공업체인가"가 피상적인 결정인 이유다. 배열이 아키텍처이고 방언은 직렬화 세부 사항이다. Claude Code를 제공업체 중립적으로 재구축한 나의 One Code는 와이어 형식 위의 모든 것이 동일하기 때문에 제공업체를 교체 가능한 부분으로 취급할 수 있다.
이 장의 모든 내용은 1분 안에 읽을 수 있는 프로그램에 들어간다. 다음은 "메모리"가 있는 작동하는 채팅 클라이언트인 harness/v1_chat.py다:
#!/usr/bin/env python3 """Harness v1: a chat loop. The array IS the conversation.""" import json, os, urllib.request
API_KEY = os.environ["ANTHROPIC_API_KEY"] MODEL = "claude-sonnet-5" SYSTEM = "You are a concise assistant."
def call_llm(messages): body = {"model": MODEL, "max_tokens": 4096, "system": SYSTEM, "messages": messages} req = urllib.request.Request( "https://api.anthropic.com/v1/messages", data=json.dumps(body).encode(), headers={"content-type": "application/json", "x-api-key": API_KEY, "anthropic-version": "2023-06-01"}) with urllib.request.urlopen(req) as resp: return json.loads(resp.read())
def main(): messages = [] # the entire "session" while True: user_text = input("\n you> ").strip() if user_text in ("/quit", ""): break if user_text == "/clear": messages = [] # "new conversation" continue messages.append({"role": "user", "content": user_text}) reply = call_llm(messages) # resend EVERYTHING text = "".join(b["text"] for b in reply["content"] if b["type"] == "text") messages.append({"role": "assistant", "content": reply["content"]}) print(f"\n assistant> {text}")
if name == "main": main()
약 30줄의 코드지만, 여러분이 앞으로 만들 모든 하니스의 형태를 이미 갖추고 있다. 배열에 추가하고, 이를 통째로 보내고, 응답을 추가하는 루프다. 실행해서 대화해 본 다음, 매 턴 뒤에 print(len(json.dumps(messages)))를 추가해 배열이 커지는 모습을 지켜보라. 여러분의 미래 API 청구서를 보고 있는 것이다.
숙제: call_llm을 OpenAI의 Chat Completions 형식으로 이식하라. 10분이면 되는 변경이며, 핵심은 바뀌는 것이 얼마나 적은지 알아차리는 데 있다.
곁가지: 스트리밍은 어떤가? 채팅 UI에서 응답이 단어별로 나타나는 것은 같은 POST에
"stream": true를 넣은 것이다. 서버는 응답을 생성하면서 청크 단위로 보낸다. 스트리밍은 표시 방식만 바꾼다. 배열과 상태 비저장성은 그대로이고, 응답이 단지 조각으로 도착할 뿐이다. 이 시리즈는 여기서부터 스트리밍을 무시해도 아무것도 잃지 않는다. 실제로 필요해질 때(와이어 형식, 조각 조립, 응답 도중 끊기는 연결, 긴 요청이 결국 이를 요구하게 되는 이유)는 부록 D에서 그 작동 원리를 다룬다.
따라서 하니스는 "JSON 배열을 유지하는 프로그램"이다. 이는 서기의 일처럼 들리지만, 실제로 하니스는 다음을 결정해야 한다:
이 중 어느 것도 수동적인 배관 작업이 아니다. 몸은 뇌가 무엇을 볼 수 있는지, 언제 중단할지, 어떤 명령을 거부할지를 결정하기 때문이다. 순종적인 팔다리의 집합이라기보다 반사 작용을 가진 몸에 가깝게 행동한다.
이 관점은 이 시리즈가 코딩 에이전트만을 다루지 않는 이유도 설명한다. 코딩 하니스는 뇌에 파일을 수정하고 셸을 실행하는 손을 주고, 로보틱스 하니스는 모터를 주며, 고객 지원 하니스는 티켓 큐를 준다. 몸은 다르지만 신경계(JSON 배열과 이를 둘러싼 루프)는 어디서나 같다. 이 시리즈는 텍스트로 시연하기 가장 쉽기 때문에 코딩 몸을 만들지만, 모든 패턴은 이전 가능하다.
/clear는 messages = []이고, 재개는 파일 읽기다.하니스에 기능을 추가하기 전에, POST 반대편에 있는 것이 무엇인지, 그리고 그것이 훈련된 방식이 왜 그 기묘한 행동 대부분을 설명하는지 살펴봐야 한다.