프로덕션 에이전트 만들기

에이전트는 도구 스키마와 문맥 관리 같은 개별 조각으로 이뤄집니다. 이 조각들이 여러 번의 대화에 걸쳐 함께 돌아가기 시작하면, 하나씩 따로 시험할 때는 드러나지 않던 실패가 새로 나타나는 경우가 많습니다.

단일 대화에서는 잘 되던 라우팅어떤 도구로 보낼지, 어느 단계로 넘길지 정하는 판단.이 여러 턴을 거치며 누적되어 어긋나고, 문맥(대화에 쌓이는 맥락)이 예상보다 빨리 찹니다. 앞 단계 결과에 기대는 단계가, 이전 도구 호출이 잘못 구성된 탓에 엉뚱한 입력을 받기도 합니다. 그래서 에이전트를 만들 때 가장 먼저 묻는 질문은 "이 문제에 정말 에이전트가 필요한가"입니다.

에이전트는 조율 비용과 문맥 비용이 크고, 단순한 방식보다 실패가 생길 수 있는 부분이 많습니다. 시작에서 패턴을 잘못 고르는 것이 에이전트 개발에서 가장 크게 어긋나는 지점입니다. 워크플로우와 에이전트는 서로 다른 문제를 풉니다. 워크플로우로 충분한데 에이전트를 쓰면 능력은 그대로인 채 동작만 복잡해지고, 에이전트가 필요한데 워크플로우를 쓰면 사용자 입력이 정해진 경로를 벗어나는 순간 깨집니다.

WORKFLOW vs AGENT — 어느 쪽이 맞는 문제인가

이 문제에 에이전트가 필요하다고 정했다면, 패턴도 함께 정해진 셈입니다. 도구를 부르고 문맥을 관리하며 목표에 닿을 때까지 반복하는 루프입니다. 단일 에이전트에서는 이 패턴이 세 배선 경로 모두에서 같습니다. 달라지는 것은 루프의 얼마만큼을 직접 쓰고, 얼마만큼을 라이브러리나 호스팅 서비스에 맡기는지입니다.

여러 에이전트가 계획·실행·평가를 나눠 맡는 다중 에이전트 구조는 루프 자체를 넘어서는 설계가 더 필요한데, 그 패턴은 이 과정 뒤쪽에서 다룹니다. 여기서는 어느 경로에서도 변하지 않는 루프 자체를 먼저 봅니다.

세 경로는 한 가지 변수에서 갈립니다 — 에이전트가 돌아가는 런타임 중 내가 얼마나 소유하는지입니다. 아래는 넘기는 인프라가 많아지는 순서로 정리한 것입니다. 배포·컴플라이언스 조건을 보고 고르는 것이 좋습니다. 시제품을 가장 빨리 만들 수 있다는 이유만으로 경로를 고르지 않도록 주의합니다.

① 직접 만든 루프 (Raw Messages API loop) — 내 코드가 매 반복을 돌립니다.

• 루프를 누가 돌리나 — 내 코드. 요청을 보내고, 도구 호출 블록을 읽고, 도구를 실행하고, 결과를 직접 이어 붙입니다.
• 내가 소유하는 것 — 루프 전체, 도구 실행, 문맥 관리, 재시도, 종료 조건. 주어지는 것은 없습니다.
• 이럴 때 고른다 — 한 단계까지 완전히 통제해야 하거나, 라이브러리가 못 맞추는 제약이 있거나, 추상화를 더하기 전에 루프가 어떻게 돌아가는지 직접 익히고 싶을 때.
• 확인할 점 — 유지보수 비용이 전부 내게 옵니다. SDK가 공짜로 주던 동작(문맥 관리·병렬 도구 처리 등)이 모두 내가 쓰고 시험할 코드가 됩니다.

② Agent SDK — SDK가 내 프로세스 안에서 루프를 돌립니다.

• 루프를 누가 돌리나 — SDK. 반복과 문맥 관리는 SDK가 맡고, 에이전트가 부르는 도구 실행은 여전히 내 코드가 합니다.
• 내가 소유하는 것 — 도구 실행과 그 둘레의 앱. 루프 구조·문맥 관리·도구 등록은 SDK가 줍니다.
• 이럴 때 고른다 — Claude Code를 떠받치는 루프·문맥 처리·도구 발판을 다시 만들지 않고 그대로 쓰고 싶을 때, 그리고 Python이나 TypeScript로 내 환경에서 에이전트를 돌리고 싶을 때.
• 확인할 점 — CLAUDE.md·스킬 같은 파일 기반 기능이 로드되는지는 settingSources 설정이 정합니다. 기본값에 기대지 말고 항상 명시하는 것이 좋습니다 — 예를 들어 Claude Code CLI와 같게 하려면 ["user","project","local"], 넘긴 것만 쓰는 완전 격리는 []. 현재 기본 동작은 만들 때 Agent SDK 문서로 확인합니다.

③ Claude Managed Agents (공개 베타) — Anthropic이 루프와 샌드박스를 돌립니다.

• 루프를 누가 돌리나 — Anthropic. 내 앱은 사용자 이벤트를 보내고, 결과를 SSEserver-sent events — 서버가 결과를 조각조각 흘려보내는 전송 방식.로 받습니다.
• 내가 소유하는 것 — 앱 계층과 에이전트 정의(모델·시스템 프롬프트·도구·MCP 서버·스킬). 한 번 정의한 뒤 세션마다 ID로 불러 씁니다.
• 이럴 때 고른다 — 실행이 분·시간 단위로 길거나, 관리형 샌드박스도구 실행을 격리해서 돌리는 실행 공간.를 원하거나, 루프·샌드박스·도구 실행 계층을 아예 만들고 싶지 않을 때. AWS의 Claude Platform에서도 쓸 수 있지만 기능 차이가 있으니 배포 환경에서 맞는지 확인합니다.
• 확인할 점 — 세션이 서버에 상태로 저장돼서, 현재 ZDRZero Data Retention — 데이터를 남기지 않는 처리 방식.이나 HIPAA BAA의료 정보 취급에 필요한 계약(Business Associate Agreement). 대상이 아닙니다. 공개 베타라 모든 호출에 managed-agents-2026-04-01 베타 헤더가 필요하고, 릴리스마다 동작이 다듬어질 수 있어 옮겨 갈 계획을 세워 두고 만드는 것이 좋습니다.

세 번째 경로인 Managed Agents는 일부 작업에서는 기본으로 삼을 만합니다. 직접 만든 루프나 Agent SDK에서는 내 코드가 반복을 돌리지만, Managed Agents에서는 Anthropic이 루프와 샌드박스를 대신 돌립니다. 무엇을 더는 소유하지 않게 되고, 대신 무엇을 떠안는지 정리하면 이렇습니다.

STOP OWNING · TAKE ON — 내려놓는 것과 새로 떠안는 것

자주 밟는 순서는 Agent SDK로 로컬에서 시제품을 만든 뒤, 프로덕션에서 Managed Agents로 옮기는 것입니다. 핵심 에이전트 정의는 개념상 그대로 이어지지만 형식이 달라집니다 — Agent SDK는 코드와 파일 설정을 쓰고, Managed Agents는 에이전트를 버전이 매겨진 API 자원으로 정의합니다. 그대로 내보내기(export)가 아니라, 다시 표현하는 단계 하나가 있다고 보면 됩니다.

아래 네 단계는 어느 경로로 만들든 돌아가는 에이전트 루프를 이룹니다. Messages API로 직접 쓸 때는 네 단계를 모두 내가 구현하고, Agent SDK를 쓰면 도구 등록·시스템 프롬프트·루프 반복의 구조는 SDK가 주고 도구 실행은 여전히 내 코드가 맡습니다. 단계는 같고, 얼마만큼을 직접 쓰는지가 다릅니다.

• 도구를 등록한다 — 각 도구는 같은 스키마 구조를 따릅니다. 등록해 두면 Claude가 무엇을 쓸 수 있는지 압니다.
• 시스템 프롬프트를 좁힌다 — 에이전트가 맡은 과제에 맞게 좁게 적습니다. 넓게 적으면 도구 선택이 넓고 덜 일관되게 나옵니다. 어떤 과제인지, 그 과제에 어떤 도구가 있는지 짚어 주면 더 일관된 동작이 나오는 경우가 많습니다.
• 도구 호출 루프를 처리한다 — 루프를 내가 돌리든 SDK가 돌리든, 실행은 내 코드가 맡습니다. Claude가 낸 도구 호출은 모두 내 코드가 실행해 tool_result 블록으로 돌려줍니다.
• 종료 조건을 정한다 — 루프는 멈춤 신호를 받을 때까지 이어집니다. 종료 조건을 분명히 정해 두지 않으면, 과제에 필요한 것보다 더 많은 도구 호출을 계속 요청합니다. '끝'이 언제 끝인지 직접 정해 둡니다.

LOOP WIRING CHECKLIST — 경로와 상관없이 확인할 5가지

사람 확인 지점은 에이전트 실행을 잠시 멈추고, 이어 가기 전에 사람 검토 단계로 넘깁니다. 어디에 넣을지는 한 가지 질문으로 정해집니다 — 이 단계가 사람 확인 없이 실행되면 최악의 결과가 무엇인가.

HITL INSERTION POINTS — 세 자리와 각각이 막는 위험

에이전트의 라우팅 동작은 두 가지에 좌우됩니다 — 도구를 어떻게 설명했는지, 그리고 몇 개를 등록했는지. 겹치는 설명을 가진 도구가 너무 많으면 라우팅이 불안정해지고, 너무 적으면 에이전트가 없는 경로를 지어내거나 불완전한 결과를 내놓습니다.

프로덕션 에이전트에서는 도구를 너무 많이 등록하는 쪽이 더 흔한 문제입니다. "혹시 몰라서" 쓸 만한 도구를 전부 등록해 두면, 도구 표면이 넓어질수록 Claude의 선택 품질이 떨어집니다. 과제에 필요한 최소 집합으로 시작하고, 능력이 비는 부분이 구체적으로 확인될 때만 도구를 더하는 것이 좋습니다.

다루는 데이터에 특정 제약이 걸려 있으면(예: 변호사·의뢰인 비밀유지, HIPAA, GDPR, FedRAMP, 사내 데이터 거주 정책), 프롬프트·도구·메모리를 설계하기 전에 그 제약이 먼저 정합니다 — 내 코드가 어느 엔드포인트를 부르고, 어떤 자격증명을 지니며, 로그가 어디에 남는지를.

개발자가 배포 표면을 직접 고르지 않는 경우가 많지만, 특정 엔드포인트를 겨냥하고 자격증명을 붙이고 리전을 설정하고 로그를 내보내는 코드는 개발자가 씁니다. 그래서 규제 제약을 시작 시점에 분명히 확인해 두는 것이 좋습니다. 에이전트를 다 배선한 뒤에 클라이언트 설정을 바꾸는 것은 처음에 맞게 잡는 것보다 훨씬 비쌉니다. 아래 다섯 가지는 프로덕션에서 가장 자주 만나는 경우입니다.

FIVE CONSTRAINTS — 코드에서 걸리는 것과 리뷰를 통과하는 구성

이 표는 엔드포인트 선택과 자격증명 구성을 직접 정하는 제약만 다룹니다. SOC 2는 여기 범위 밖입니다 — 어느 엔드포인트를 부르는지가 아니라 시스템을 어떻게 만들고 운영하는지를 다루며, 모듈 4에서 보안 태세·감사 요건과 함께 살펴봅니다. 모듈 4(프로덕션 엔지니어링·평가·보안)는 IAM·프라이버시 설계, 신뢰할 수 없는 입력에서 오는 프롬프트 주입 방어, 런타임 가드레일, 에이전트 강화를 더 깊게 다룹니다.

테스트에서는 처음부터 끝까지 잘 돌아가던 에이전트가, 프로덕션에서는 그렇지 않은 경우가 있습니다. 테스트 환경은 너그럽지만 프로덕션은 그렇지 않기 때문입니다. 도구도 루프도 시스템 프롬프트도 같은데, 사람 확인 단계 하나가 빠져 있었고 테스트에서는 그게 필요한 상황이 한 번도 나오지 않았습니다.

한 개발자가 설정 파일을 읽고 고치고 쓰는 에이전트를 만들었습니다. 시스템 프롬프트는 read_file·write_file·validate_config 세 도구를 줬습니다. 루프는 단순했습니다. 쓰기를 할 때마다 validate_config를 다시 돌리고, 설정이 여전히 검증을 통과하지 못하면 편집을 조정해 다시 쓰기를, 최대 열 번까지 반복한 뒤 멈추게 했습니다. 대상 설정의 사본을 둔 임시 디렉터리에서 시험했고, 보통 두세 번 반복 만에 유효한 설정으로 수렴하며 모든 경우에 제대로 동작했습니다.

고객 환경에 배포하자, 에이전트는 설정 값 하나가 허용 범위를 벗어난 것을 정확히 찾아냈습니다. 고칠 값을 제안하고 write_file을 부르고 validate_config를 다시 돌려 통과를 받았습니다. 루프는 설계 그대로 한 번 반복하고 깔끔하게 끝났습니다. 열 번 상한은 필요한 적이 없어 닿지도 않았습니다. 루프 설계는 맞았는데, 종료 조건이 문제였습니다.

그 값은 고객 애플리케이션이 의존하던 요청 한도(rate limit)였습니다. validate_config는 값이 스키마 허용 범위 안인지만 확인했고, 이제 범위 안이었습니다. validate_config가 확인하지 않았고 애초에 확인하도록 만들어지지도 않은 것은, 다른 시스템이 옛 값에 의존하는지였습니다. 쓰기 몇 분 만에 고객 애플리케이션이 감당하도록 만들어지지 않은 속도로 요청이 제한되면서 장애가 나기 시작했습니다.

루프는 개발자가 시킨 그대로 편집하고 검증하고 통과하면 끝냈습니다. 문제는 루프가 아니라, 종료 조건(validate_config 통과)이 에이전트가 고치던 파일 안으로만 좁혀져 있었다는 데 있었습니다. '이 파일에서 검증을 통과했다'와 '고객 환경에 쓰기를 반영했다' 사이에 확인 단계가 없었던 것입니다. 빠진 것은 첫 write_file이 실제 고객 설정에 닿기 전에 잠시 멈추고, 제안한 변경을 사람에게 보여 검토받는 단계였습니다. 곧 루프에 '변경안 준비됨'과 '쓰기 반영됨' 사이를 가르는 분기가 필요했는데, 테스트에서 그런 경우가 나오지 않아 개발자가 넣지 않았던 것입니다.

원문의 점검 과제는 직접 채워 보는 서술형입니다. 아래는 일부만 구현된 에이전트 코드로, 빈 곳이 두 군데 있습니다. (1) update_record의 설명과 (2) 사람 확인 체크포인트 코드를 각각 채워 보세요. 먼저 스스로 써 본 뒤 모범 답안과 비교하는 것이 좋습니다.

PARTIAL IMPLEMENTATION — 빈 곳 두 군데가 있는 에이전트 루프

tools = [
  {
    "name": "read_record",
    "description": "Use this to read a customer record by customer_id.",
    "input_schema": { "type": "object", "properties": {"customer_id"...}, "required": ["customer_id"] }
  },
  {
    "name": "update_record",
    "description": [BLANK — 이 도구의 설명을 쓰세요],
    "input_schema": { "type": "object", "properties": {"customer_id","field","new_value"...}, "required": [...] }
  }
]

def run_agent_loop(user_request):
    messages = [{"role": "user", "content": user_request}]
    while True:
        response = client.messages.create(model=model, max_tokens=4096, tools=tools, messages=messages)
        if response.stop_reason == "end_turn": return response
        if response.stop_reason == "tool_use":
            messages.append({"role": "assistant", "content": response.content})
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":

                    [BLANK — update_record 실행 전에 사람 확인(HITL) 체크포인트를 넣으세요]

                    result = execute_tool(block.name, block.input)
                    tool_results.append({"type": "tool_result", "tool_use_id": block.id, "content": result})
            messages.append({"role": "user", "content": tool_results})

빈 곳 1 · update_record의 설명

빈 곳 2 · 사람 확인(HITL) 체크포인트 코드

"Use this to update a specific field on a customer record. Only call
this tool after a read_record call has confirmed the current value and
the proposed change has been reviewed. Do not use this for bulk updates
or schema changes."

if block.type == "tool_use":
    if block.name == "update_record":
        print(f"Proposed update, customer_id: {block.input['customer_id']}, "
              f"field: {block.input['field']}, new_value: {block.input['new_value']}")
        approval = input("Approve this update? (yes/no): ").strip().lower()
        if approval != "yes":
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": "Update rejected by operator."
            })
            continue
    result = execute_tool(block.name, block.input)

이어서 객관식으로 점검합니다. 정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.