◆ 직접 API vs Agent SDK vs CLI vs Managed Agents

direct API · Agent SDK · CLI -p · Managed Agents3.7 본편

표시가 없는 문장은 공식 문서에서 확인한 내용이에요. 다른 표시는 읽는 법

왜 배우나 — 시험이 요구하는 것

시험 목표 3.7 연결 방식 고르기 · D3 연결 19%
Evaluate connection protocols and select the appropriate integration mechanism (MCP, API/CLI, agent-to-agent)

이 개념으로 푸는 판단 (할 수 있어야 하는 것)

3.7② 작은 플랫폼팀이 고객지원 에이전트를 띄운다 — 직접 API · Agent SDK · CLI(-p) · Managed Agents 중 무엇? — 연동 방식 고르기 (도구 루프·인프라를 누가 소유하나)
3.7③ 서로 얽힌 모듈을 고치는 코딩 작업을 에이전트 5개 병렬로 나누자는 제안 — 에이전트끼리 연결이 맞나? — 멀티 에이전트(agent-to-agent)를 쓸지 — 비용·적합성

한눈에

직접 API 는 운영 전부 내가, Agent SDK 는 내 앱에서, CLI claude -p 는 CI/CD 에서 돌리고, Managed Agents 는 Anthropic 이 루프를 돌린다. 먼저 직접 API. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게)

ELI5

밥을 직접 해 먹을지, 밀키트를 살지, 식당에 갈지 고르는 거예요.

직접 하면 마음대로지만 설거지도 내 몫이에요(직접 API).
밀키트는 재료·순서가 다 들어 있고 내 부엌에서 해요(Agent SDK).
식당은 요리사가 다 해 주지만 메뉴 규칙을 따라야 해요(Managed Agents).
식당이 "주문 기록을 안 남기는" 약속은 아직 못 해요.

개념 설명

영상 — 맡기면 편한데, BAA 가 필수라면 (약 42초 · 소리 없음 · 자막). 작은 화면에서는 전체화면(⛶)으로 보세요.

원리

네 가지는 "누가 무엇을 돌리나"로 갈린다

직접 API : 모델 호출만 받는다. 도구 루프(부르고, 결과를 넣고, 다시 부르기)는 내가 짠다. SDK tool runner(베타)가 루프를 대신 돌려 줄 수도 있다.
Agent SDK : Claude Code 의 내장 도구·권한·세션·훅·서브에이전트·MCP 를 라이브러리로 쓴다. 루프는 들어 있다. 프로세스는 내가 운영한다.
CLI -p : 같은 루프를 명령 한 줄로 돌린다. 스크립트·CI/CD·Python·TS 밖 언어에서 하위 프로세스로 쓴다.
Managed Agents : 루프·도구 실행·샌드박스를 Anthropic 이 호스팅한다. 세션·기록·샌드박스 상태가 서버에 남는다(상태 유지 설계).

단순함이 먼저다

공식은 "가장 단순한 해법부터, 필요할 때만 복잡하게" 라고 한다. 많은 패턴이 API 직접 호출 몇 줄이면 된다. 에이전트 자체가 필요 없을 수도 있다.
프레임워크는 추상화 층이 프롬프트와 응답을 가린다. 그래서 디버깅이 어려워진다.

상태 유지의 대가

Managed Agents 는 서버에 세션을 저장한다. 그래서 ZDR·HIPAA BAA 대상이 아니다. 규정 요구가 있으면 여기서 갈린다.
자체 호스팅 샌드박스는 "실행 위치"를 우리 인프라로 옮기는 것이다(규정 준수·데이터 상주용). 이것이 ZDR 적격을 바꾼다는 문장은 없다.

MCP 는 연결 규격이지 보안 결정이 아니다

MCP 규격은 스스로 "프로토콜 수준에서 보안 원칙을 강제할 수 없다. 구현자가 해야 한다"고 적는다.

규칙과 판단

루프를 맡기고 ZDR·BAA 가 필요 없으면 Managed Agents, 필요하면 직접 API·SDK 쪽. 내가 돌리면 루프가 필요 없을 때 직접 API, 앱은 Agent SDK, CI 는 CLI claude -p. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게)

갈림길

루프를 누가 [3.7②]

루프·샌드박스 층을 맡기나?장기 실행·비동기 · cron 예약

예

ZDR·HIPAA BAA 가 필요한가?

아니오

Managed Agents

루프는 Anthropic 이 돌린다. 샌드박스는 Anthropic 클라우드나 자체 호스팅이다

예

직접 API·Agent SDK 쪽

둘 중 어느 쪽인지는 아래 「내가 돌릴 때」 에서 고른다. Managed Agents 는 지금 대상이 아니다. 세션·샌드박스 상태를 서버에 저장하는 설계이기 때문이다

아니오 (내가 돌린다)

↓ 아래 「내가 돌릴 때」 갈림길로 이어짐

다음 물음 — Claude Code 의 도구·루프·컨텍스트 관리가 필요한가?

내가 돌릴 때 [3.7②]

Claude Code 의 도구·루프·컨텍스트 관리가 필요한가?많은 패턴은 몇 줄이면 된다. 먼저 단순하게

아니오

직접 API

도구 루프는 내가 짜거나 SDK 의 tool runner(베타)가 돌린다. 먼저 단순하게 직접 API 부터 쓴다. 많은 패턴이 몇 줄이면 된다

예

어디서 부르나?

내 Python·TypeScript 앱

Agent SDK

내가 운영하는 프로세스에서 돌린다. 프로세스·자격증명·observability(관측 가능성)는 내가 맡는다

스크립트·CI/CD · Python·TS 밖 언어

CLI claude -p

--output-format json 을 붙이고, CI 에서는 --bare 를 붙인다

규칙 원문 갈림 기준 (갈림길로 그린 규칙)

갈림 기준

에이전트 루프·도구 실행·인프라를 **누가 돌리나** 가 기준이다

원하는 것	고름	운영은
내 코드에서 Claude API 를 직접 부른다. 도구 루프는 내가 짜거나 SDK 의 tool runner(베타)가 돌린다	직접 API (Client SDK)	전부 내가 한다
Claude Code 의 도구·루프·컨텍스트 관리를 내 Python·TypeScript 앱에 넣는다. 내가 운영하는 프로세스에서 돌린다	Agent SDK	프로세스·자격증명·observability 는 내가 한다
스크립트·CI/CD · Python·TS 밖 언어에서 같은 루프를 쓴다	CLI `claude -p` (+ `--output-format json`, CI 는 `--bare`)	파이프라인은 내가 한다
루프·샌드박스·도구 실행 층을 안 만든다. 장기 실행·비동기 · cron 예약이 필요하다	Managed Agents	루프는 Anthropic 이 돌린다. 샌드박스는 Anthropic 클라우드나 자체 호스팅이다

먼저 단순하게 직접 API 부터 쓴다. 많은 패턴이 몇 줄이면 된다. 프레임워크는 그 밑에서 도는 코드를 알 때만 쓴다. 에이전트가 아예 필요 없을 수도 있다
Managed Agents 의 자체 호스팅 샌드박스는 규정 준수와 데이터 상주를 위한 것이다. 그만큼 운영 일부가 우리 쪽에 남는다 (추론)
ZDR·HIPAA BAA 가 필요하면 직접 API·Agent SDK 쪽으로 간다. Managed Agents 는 지금 대상이 아니다. 세션·샌드박스 상태를 서버에 저장하는 설계이기 때문이다
MCP 는 도구·데이터 연결을 표준화할 뿐이다. 프로토콜은 보안 원칙을 강제하지 못한다. 동의·인가(authorization)·접근 통제(access control)는 구현자가 맡는다
MCP 서버와 직접 API 호출의 차이 : MCP 서버는 도구 정의와 실행이 이미 만들어져 있다. API 를 직접 부르면 도구 정의를 내가 쓴다 (Skilljar)
CLI -p 주의 : --bare 없이 돌리면 그 폴더의 .claude/settings.json 훅과 .mcp.json 서버가 신뢰 확인창 없이 돈다. 그래서 CI 와 스크립트는 --bare 를 권장한다

더 깊이 : 판단 규칙 · 상황 변수 (설명)

판단 규칙

조건	답	근거
루프와 세밀한 통제(control)를 내가 원한다	직접 API	managed-agents "Custom agent loops and fine-grained control" · agent-sdk overview
Claude Code 급 도구·루프를 내 앱 프로세스에 넣는다	Agent SDK	agent-sdk overview
스크립트·CI/CD · 다른 언어에서 같은 루프를 쓴다	CLI `-p` (`--output-format json`, CI 는 `--bare`)	agent-sdk overview · headless
장기 실행·비동기이고, 루프·샌드박스를 안 만들고 싶다	Managed Agents	managed-agents
규정 준수·데이터 상주가 필요하고 관리형 루프를 원한다	Managed Agents 자체 호스팅 샌드박스	managed-agents
ZDR 또는 HIPAA BAA 가 필요하다	Managed Agents 는 뺀다	managed-agents
뭘 할지 모르겠다	가장 단순한 것(API 직접)부터 쓴다	building-effective-agents
"MCP 를 쓰니 보안은 됐다" 고 한다	아니다. 동의·인가(authorization)·접근 통제는 구현자가 한다	MCP spec

상황 변수

변수	값	답 쪽	근거
운영 인력	없다	Managed Agents	managed-agents "Minimal infrastructure"
운영 인력	있고, 루프 통제를 원한다	직접 API 또는 Agent SDK	판단 규칙 1·2
규정	ZDR · HIPAA BAA	직접 API·Agent SDK 쪽	managed-agents
규정	데이터 상주만 필요하다(ZDR 불필요)	Managed Agents 자체 호스팅 샌드박스도 가능하다	managed-agents
작업 길이	한 번 호출로 끝난다(분류·요약)	직접 API (에이전트가 필요 없다)	building-effective-agents
작업 길이	수 분~수 시간이고 도구를 여러 번 쓴다	Agent SDK 또는 Managed Agents	managed-agents
실행 계기	CI 파이프라인·크론 스크립트	CLI `-p --bare` (또는 Managed Agents 예약 배포)	headless · managed-agents
언어	Go·Java 등	직접 API(Client SDK) 또는 CLI 하위 프로세스	agent-sdk overview
인증(authentication)	우리 제품에 claude.ai 로그인을 붙인다	사전 승인 없이는 안 된다. API 키를 쓴다	agent-sdk overview

연습 문제

운영 인력이 2명뿐인 병원이 에이전트 루프·샌드박스는 직접 만들고 싶지 않다안 만들고 싶음며, 환자 메시지를 분류하고 답장 초안을 쓰는 장기 실행 에이전트를 원한다. 계약상 HIPAA BAA 적용이 필수BAA 필수다. 어떤 방식으로 붙여야 하나?

시험 대비

함정

"MCP 표준을 쓰니 보안·규정 검토는 끝났다" 는 함정이다. 프로토콜은 보안을 강제하지 못한다
"추상화 프레임워크부터 깐다" 는 함정이다. API 직접부터 쓴다
"운영 인력 없는 작은 팀이 Agent SDK 로 직접 호스팅한다" 는 함정이다. 프로세스 운영이 우리 몫이 된다. "최소 인프라"는 공식이 Managed Agents 에 붙인 조건이다 (단 ZDR·BAA 가 필요하면 Managed Agents 는 빠진다)
"Managed Agents 면 ZDR 도 해결된다" 는 함정이다. Managed Agents 는 ZDR 대상이 아니다
"Agent SDK 제품에 claude.ai 로그인을 붙여 출시한다" 는 함정이다. 사전 승인 없이는 안 된다. API 키 인증(authentication)을 쓴다
"integration continuum" 은 강의가 만든 이름이다. 공식 용어가 아니다 (목록 메모)
"좁은 연동 경계가 중요하면 직접 API 를 쓴다" 는 함정이다. 공식 기준이 없다. 공식 근거는 단순성이다 업계 일반
"에이전트끼리 연결(agent-to-agent)이 더 고급이다" 는 함정이다. 적합성과 비용 판단은 ◆ 단일 vs 멀티 에이전트 에 있다

신호

"Embed Claude Code’s agent in your own Python or TypeScript application, in a process you operate"

"You write the tool loop yourself, or let the client SDK’s beta tool runner drive it."

"A hosted agent harness that runs the agent loop, with sessions in an Anthropic-managed cloud sandbox or a self-hosted sandbox on your own infrastructure."

"It’s available as a CLI for scripts and CI/CD"

"We suggest that developers start by using LLM APIs directly: many patterns can be implemented in a few lines of code."

"While MCP itself cannot enforce these security principles at the protocol level, implementors SHOULD:"

"Managed Agents is not currently eligible for Zero Data Retention or HIPAA Business Associate Agreement (BAA) coverage."

작은 팀이면 보통 Managed Agents 지만, BAA·ZDR 이 필요하면 직접 API·Agent SDK, 분류만 하면 에이전트 없이 호출 1번, CI 셸 스크립트면 CLI claude -p 라는 그림. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게) — 자세한 조건은 아래 '더 깊이'에 있어요

더 깊이 : 뒤집히는 때 · 오답 재료 (설명)

뒤집히는 때

1. 작은 팀인데 Managed Agents 가 안 되는 때

조건 : 운영 인력이 2명이다. 병원 환자 메시지를 처리한다(HIPAA BAA 필수).
판단 : "최소 인프라"만 보면 Managed Agents 다. 그러나 Managed Agents 는 BAA 대상이 아니다. 그래서 직접 API 나 Agent SDK 로 우리가 호스팅한다. 규정 조건이 운영 편의를 이긴다.
근거 : managed-agents

2. 에이전트가 필요 없는 때

조건 : 들어오는 티켓을 5개 범주로 나누기만 한다.
판단 : 호출 1번과 구조화 출력이면 끝난다. Agent SDK 나 Managed Agents 는 과설계다. 공식 글도 "에이전트 시스템을 아예 안 만드는 것일 수도" 있다고 한다.
근거 : building-effective-agents

3. CLI 가 SDK 보다 나은 때

조건 : PR 마다 GitHub Actions 에서 리뷰를 한 번 한다. 팀은 셸 스크립트만 쓴다.
판단 : 앱을 짤 필요 없이 claude -p --bare --output-format json 을 쓴다. --bare 를 붙이면 러너 머신의 훅·MCP·CLAUDE.md 가 섞이지 않는다.
근거 : headless

4. 자체 호스팅 샌드박스를 ZDR 해법으로 착각하는 때

조건 : "샌드박스를 우리 인프라에 두면 ZDR 도 된다"는 제안이 나온다.
판단 : 공식은 자체 호스팅을 "규정 준수·데이터 상주"용이라고 한다. 그리고 Managed Agents 전체를 ZDR·BAA 대상이 아니라고 적는다. 예외 문장은 없다. 그래서 ZDR 해법으로 보면 안 된다.
등급 : (두 문장) · 미해결(자체 호스팅 적격 여부를 직접 말한 문장 없음)
근거 : managed-agents

오답 재료

오답	왜 끌리나	왜 틀리나	등급	근거
"MCP 표준을 쓰니 보안·규정 검토는 끝"	표준이면 검증된 것 같다	프로토콜은 강제하지 못한다. 구현자가 맡는다		MCP spec
"추상화 프레임워크부터 깐다"	빨리 시작할 수 있다	API 직접부터 쓴다. 추상화가 디버깅을 가린다		building-effective-agents
"Managed Agents 로 가면 ZDR 도 해결"	관리형이면 규정도 해결될 것 같다	ZDR·BAA 대상이 아니다		managed-agents
"운영 인력 없어도 Agent SDK 로 직접 호스팅이 표준"	SDK 가 공식 권장 같다	프로세스 운영이 우리 몫이다		agent-sdk overview "in a process you operate"
"CLI `-p` 는 개발자 터미널 전용"	대화형 도구로만 알고 있다	공식 문서가 스크립트·CI/CD 용이라고 밝힌다		headless
"Agent SDK 제품에 claude.ai 로그인 제공"	사용자가 편하다	사전 승인 없이는 안 된다		agent-sdk overview
"좁은 연동 경계가 표준보다 중요하면 직접 API"	그럴듯한 원칙이다	공식 기준이 없다. 공식 근거는 단순성이다	업계 일반	목록 3.7② 메모

참고

함께 보기

더 깊이 : 출처 · 상태 · 미해결 (참고)

출처

상태

추론 1줄
업계 일반 1줄

미해결

Managed Agents 자체 호스팅 샌드박스의 ZDR·BAA 적격을 직접 말한 문장은 없다. overview 는 Managed Agents 전체를 대상이 아니라고 적는다. api-and-data-retention 문서는 받지 않았다.
목록 3.7② 인용 5개는 모두 원문에서 찾았다. 단 "A hosted agent harness…" 문장은 원문에 링크가 섞여 있다. 그래서 링크를 뺀 형태로 옮겼다.
3.7③(에이전트끼리 연결)의 비용·적합성(토큰 4배·15배 등)은 ◆ 단일 vs 멀티 에이전트 카드가 다룬다. 그래서 여기서는 확인하지 않았다.