1편은 curl로 SSE 스트림이 흘러나오는 터미널 화면에서 끝났습니다. 그 화면을 보고 있으니 "이걸 폰에서 보고 싶다"는 생각이 먼저 들었고, 그래서 이번 편에서는 iPhone 앱을 붙입니다.

원래 2편은 운영하면서 겪은 문제들(재시도·타임아웃·비용)을 쓰려고 했는데, 순서를 바꿨습니다. 그런 문제들은 앱을 실제로 매일 쓰기 시작해야 만나는 것들이라, 먼저 쓸 수 있는 물건을 만들고 그다음에 운영 이야기를 하는 게 맞겠다고 판단했습니다.

구성은 위 그림이 전부입니다. 앱은 Thin 클라이언트입니다.

• iPhone 앱은 Bedrock을 직접 부르지 않습니다. 1편 11장에서 만든 FastAPI 서버에 HTTP로 붙고, 답은 SSE로 한 글자씩 받습니다.
• AWS 자격증명은 Mac(나중엔 EC2)에만 있습니다. 폰에는 아무것도 들어가지 않습니다.
• 대화 기억(메시지 배열)은 앱이 들고 있습니다. 1편 7장 "상태는 서버가 아니라 내가 들고 있다"가 그대로 이어집니다.

이렇게 나눠두면 모델을 바꾸거나 도구를 붙이거나 프롬프트를 고칠 때 앱은 손대지 않습니다. 서버만 고치면 됩니다. 제 SeanChat 앱도 올해 초 이후 서버는 수십 번 바뀌었지만 앱의 네트워크 코드는 거의 그대로입니다.

이번 편에서 만드는 것:

Swift는 다 합쳐 약 260줄입니다. 저도 Swift는 이 앱을 만들면서 처음 제대로 썼기 때문에, "iOS 개발자라면 당연히 아는 것"은 가정하지 않고 하나씩 적었습니다.

모든 스크린샷은 2026년 9월, macOS 26.5.1 + Xcode 26.5 + iPhone 17 시뮬레이터(iOS 26.5)에서 실제로 돌린 것입니다. 서버는 1편과 같은 개인 계정(us-east-2, Claude Haiku 4.5)입니다.

📡 SSE 30초 이해 — 앱 쪽에서 보면

1편 11장에서 서버가 이렇게 내보냈습니다.

data: {"type": "text", "text": "당"}

data: {"type": "text", "text": "신의 이름은 Sean"}

data: {"type": "done"}

앱 쪽에서 SSE는 어렵지 않습니다. 정리하면 세 줄입니다.

1. 그냥 HTTP 응답입니다. 다만 서버가 끊지 않고 계속 써 내려갈 뿐입니다. 웹소켓처럼 별도 프로토콜이 아닙니다.
2. 한 이벤트 = data: 로 시작하는 한 줄 + 빈 줄. 그래서 "줄 단위로 읽어서 data:를 떼고 JSON 파싱"이 전부입니다.
3. iOS에는 이걸 위한 API가 이미 있습니다. URLSession.bytes(for:) 가 응답을 바이트 스트림으로 주고, .lines 를 붙이면 줄이 도착하는 대로 for try await 로 받을 수 있습니다.

저는 처음에 "SSE 라이브러리를 찾아야 하나" 하고 검색부터 했는데, 결국 표준 API 두 개(bytes(for:), .lines)로 끝났습니다. 라이브러리 없이 갑니다.

🛠️ 0. 사전 준비

0-1. 1편 환경 그대로

1편의 파이썬 환경(venv + boto3 + fastapi + uvicorn)과 자격증명이 그대로 필요합니다. 1편 11장 step11_server.py가 돌아갔다면 준비된 것입니다.

python -c "import boto3, fastapi, uvicorn; print('ok')"
aws sts get-caller-identity --query Account --output text

🔗 1편에서 쓴 us.anthropic.claude-haiku-4-5-… 가 여전히 호출 가능한지, 새 모델이 열렸는지는 hub.sean-chloe.com/bedrock에서 확인할 수 있습니다 — Bedrock 모델·추론 프로파일 목록을 매일 자동 갱신하는 페이지입니다.

0-2. Xcode

Mac App Store에서 Xcode를 설치합니다. 저는 26.5를 썼지만 Xcode 16 이상이면 이 글의 코드가 그대로 빌드됩니다. (이 글에서 쓰는 @Observable, ContentUnavailableView 가 iOS 17 이상 API라서, 그보다 오래된 Xcode는 안 됩니다.)

처음 실행하면 추가 컴포넌트(iOS 시뮬레이터 런타임)를 받는데 수 GB라 시간이 걸립니다. 저는 이 사이에 1장 서버 작업을 했습니다.

0-3. Apple 개발자 계정은 필요 없습니다

시뮬레이터에서 돌리는 데는 계정이 필요 없습니다. 이 글의 스크린샷은 전부 시뮬레이터입니다. 실제 iPhone에 올릴 때도 Xcode에 본인 Apple ID로 로그인하면 됩니다. 이 앱은 스토어에 올릴 게 아니라 내 폰에서 나만 쓰는 앱이라 그 이상은 필요 없습니다. 5장 끝에서 다시 이야기합니다.

🔧 1. 백엔드 손보기 — step12_server.py

1편 11장의 step11_server.py는 {"prompt": "..."} 한 문장만 받았습니다. 앱을 붙이려면 세 가지를 더해야 했습니다.

1. 멀티턴 — 앱이 대화 전체(messages)를 들고 옵니다. 서버는 그대로 Bedrock에 넘기기만 합니다.
2. 시스템 프롬프트 — 1편 5장. 앱 이름과 말투를 여기서 정합니다.
3. 에러를 SSE 이벤트로 — 모델 호출이 실패하면 HTTP 500이 아니라 {"type": "error"} 이벤트를 흘려보냅니다. 앱이 빈 말풍선 대신 이유를 보여줄 수 있게 하려는 것입니다.

"""2편 — 1편의 step11_server.py에 세 가지만 더한다.
   ① 멀티턴: 앱이 대화 전체(messages)를 들고 온다 (1편 7장 — 상태는 '내'가 들고 있다)
   ② 시스템 프롬프트 (1편 5장)
   ③ 에러를 SSE 이벤트로 흘려보내기 — 앱이 빈 말풍선 대신 이유를 보여줄 수 있게
"""
import json
import boto3
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel

app = FastAPI()
runtime = boto3.client("bedrock-runtime", region_name="us-east-2")
MODEL = "us.anthropic.claude-haiku-4-5-20251001-v1:0"
SYSTEM = [{"text": "너는 SeanChat, 한국어로 답하는 개인 비서다. 간결하게 답한다."}]


class Msg(BaseModel):
    role: str          # "user" | "assistant"
    text: str


class ChatReq(BaseModel):
    messages: list[Msg]   # ← 앱이 대화 전체를 들고 온다


def sse(obj) -> str:                       # SSE 프레이밍: "data: {...}\n\n"
    return f"data: {json.dumps(obj, ensure_ascii=False)}\n\n"


@app.get("/health")                        # 앱의 '연결 테스트' 버튼이 부른다
def health():
    return {"ok": True, "model": MODEL}


@app.post("/chat")
def chat(body: ChatReq):
    msgs = [{"role": m.role, "content": [{"text": m.text}]}
            for m in body.messages if m.text.strip()]      # 빈 문자열은 Bedrock이 거부한다 (1편 에러 #4)

    def gen():
        try:
            resp = runtime.converse_stream(
                modelId=MODEL, system=SYSTEM, messages=msgs,
                inferenceConfig={"maxTokens": 1000})
            for ev in resp["stream"]:
                if "contentBlockDelta" in ev:
                    t = ev["contentBlockDelta"]["delta"].get("text")
                    if t:
                        yield sse({"type": "text", "text": t})
                elif "metadata" in ev:
                    yield sse({"type": "usage", "usage": ev["metadata"]["usage"]})
        except Exception as e:                              # 모델 에러도 이벤트로 — 앱이 이유를 보여준다
            yield sse({"type": "error", "message": f"{type(e).__name__}: {e}"})
        yield sse({"type": "done"})
    return StreamingResponse(gen(), media_type="text/event-stream")

/health는 앱의 "연결 테스트" 버튼이 부를 용도로 넣었습니다. 5장에서 이게 있어서 편했습니다.

띄울 때 --host 0.0.0.0 을 꼭 붙입니다. 기본값 127.0.0.1로 띄우면 같은 Mac의 시뮬레이터는 붙지만, 실제 iPhone은 붙지 못합니다. 저는 처음에 이걸 빼먹고 폰에서 "Could not connect to the server"를 한참 봤습니다.

uvicorn step12_server:app --host 0.0.0.0 --port 8599

앱을 만들기 전에 curl로 새 형식(messages 배열)이 잘 받아지는지 확인했습니다. 1편 7장의 "이름 기억하기"를 그대로 던졌습니다.

curl -N -s http://127.0.0.1:8599/chat -H 'Content-Type: application/json' -d '{
  "messages": [
    {"role": "user",      "text": "내 이름은 Sean이야"},
    {"role": "assistant", "text": "반갑습니다, Sean님."},
    {"role": "user",      "text": "내 이름이 뭐라고?"}
  ]}'

data: {"type": "text", "text": "당"}

data: {"type": "text", "text": "신의 이름은 Sean"}

data: {"type": "text", "text": "입니다."}

data: {"type": "usage", "usage": {"inputTokens": 81, "outputTokens": 17, "totalTokens": 98}}

data: {"type": "done"}

앱이 파싱해야 하는 이벤트는 네 종류(text / usage / error / done)입니다. 이 다섯 줄이 이번 편에서 앱과 서버 사이의 계약 전부입니다.

🔧 2. Xcode 프로젝트 만들기

Xcode를 열고 Create New Project를 누릅니다.

템플릿은 iOS → App입니다. 다른 건 고르지 않습니다.

옵션 화면에서 제가 넣은 값입니다.

저장 위치를 고르면 프로젝트가 열립니다. 왼쪽에 SeanChatApp.swift와 ContentView.swift 두 파일이 자동으로 만들어져 있습니다.

이 상태에서 상단 재생(▶) 버튼을 누르면 시뮬레이터가 뜨고 "Hello, world!"가 나옵니다. 여기까지 확인하고 넘어갑니다. 저는 처음 빌드가 2분 정도 걸렸습니다(시뮬레이터 부팅 포함).

Xcode 16부터 바뀐 것 하나. 왼쪽 파일 목록의 SeanChat 폴더는 디스크 폴더와 자동 동기화됩니다(Xcode 15까지의 "그룹"과 다릅니다). 그래서 Finder나 터미널에서 .swift 파일을 폴더에 넣으면 그냥 프로젝트에 포함됩니다. 이 글의 파일들도 그렇게 넣었습니다. 대신 이것 때문에 Info.plist에서 한 번 걸리는데, 5장에서 이야기합니다.

🔧 3. Swift 파일 4개 — 모델, API, 뷰모델, 화면

SeanChat 폴더 안에 파일을 하나씩 만듭니다. Xcode에서 폴더 우클릭 → New File from Template… → Swift File, 또는 그냥 Finder에서 .swift 파일을 폴더에 넣어도 됩니다(2장 끝 참고).

3-1. Message.swift — 말풍선 하나

import Foundation

/// 말풍선 하나. role은 백엔드(Bedrock)와 같은 단어를 쓴다: user / assistant
struct Message: Identifiable, Equatable {
    enum Role: String, Codable { case user, assistant }
    let id = UUID()
    let role: Role
    var text: String
}

role을 user / assistant 로 둔 이유는 하나입니다. Bedrock이 쓰는 단어와 같게 하면 서버에서 변환할 게 없습니다. 1편 2장의 messages 배열에 들어가던 그 role입니다.

text만 var인 것은 스트리밍 때문입니다. 모델의 말풍선은 빈 문자열로 만들어놓고, 조각이 올 때마다 뒤에 붙입니다.

3-2. ChatAPI.swift — 서버와 이야기하는 유일한 파일

이번 편의 핵심입니다. 62줄인데, 실제로 SSE를 읽는 부분은 열 줄이 안 됩니다.

import Foundation

/// 백엔드(step12_server.py)와 이야기하는 유일한 파일.
///   GET  /health → 연결 테스트
///   POST /chat   → SSE 스트림 ("data: {...}" 한 줄이 이벤트 하나)
struct ChatAPI {
    let baseURL: URL

    struct WireMessage: Encodable { let role: String; let text: String }
    struct Event: Decodable { let type: String; let text: String?; let message: String? }
    struct Health: Decodable { let ok: Bool; let model: String }

    enum ChatError: LocalizedError {
        case http(Int), server(String)
        var errorDescription: String? {
            switch self {
            case .http(let code):  return "서버가 HTTP \(code)를 돌려줬습니다"
            case .server(let msg): return "서버 오류: \(msg)"
            }
        }
    }

    func health() async throws -> Health {
        let (data, _) = try await URLSession.shared.data(from: baseURL.appending(path: "health"))
        return try JSONDecoder().decode(Health.self, from: data)
    }

    /// 대화 전체를 보내고, 모델이 뱉는 글자 조각(delta)을 순서대로 흘려준다
    func stream(_ messages: [Message]) -> AsyncThrowingStream<String, Error> {
        AsyncThrowingStream { continuation in
            let task = Task {
                do {
                    var req = URLRequest(url: baseURL.appending(path: "chat"))
                    req.httpMethod = "POST"
                    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
                    req.timeoutInterval = 120
                    let wire = messages.map { WireMessage(role: $0.role.rawValue, text: $0.text) }
                    req.httpBody = try JSONEncoder().encode(["messages": wire])

                    let (bytes, response) = try await URLSession.shared.bytes(for: req)
                    let status = (response as? HTTPURLResponse)?.statusCode ?? 0
                    guard status == 200 else { throw ChatError.http(status) }

                    for try await line in bytes.lines {              // 줄 단위로 도착하는 대로 읽는다
                        guard line.hasPrefix("data: ") else { continue }
                        let ev = try JSONDecoder().decode(Event.self, from: Data(line.dropFirst(6).utf8))
                        switch ev.type {
                        case "text":  if let t = ev.text { continuation.yield(t) }
                        case "error": throw ChatError.server(ev.message ?? "unknown")
                        case "done":  continuation.finish(); return
                        default:      break                          // usage 등은 지금은 무시
                        }
                    }
                    continuation.finish()
                } catch {
                    continuation.finish(throwing: error)
                }
            }
            continuation.onTermination = { _ in task.cancel() }     // 화면에서 '중지'하면 요청도 끊는다
        }
    }
}

읽는 순서대로 설명하면 이렇습니다.

① 요청 만들기 — URLRequest에 POST, JSON 헤더, 그리고 본문. 본문은 {"messages": [{"role": "user", "text": "..."}, ...]}. 1장 curl로 보낸 것과 같은 모양입니다. Message를 그대로 인코딩하지 않고 WireMessage로 한 번 옮기는 것은 id(UUID)를 서버에 보내지 않기 위해서입니다. timeoutInterval = 120은 기본값 60초를 늘린 것인데, 이 값은 "전체 시간"이 아니라 데이터가 안 오는 상태가 이어지는 시간입니다. 스트리밍 중에는 조각이 계속 오니 문제없고, 첫 글자가 나오기까지 모델이 오래 생각하는 경우(1편 10장 Extended Thinking)를 대비해 여유를 뒀습니다.

② bytes(for:) — 보통 쓰는 data(for:)는 응답이 다 끝나야 돌아옵니다. 스트리밍에는 못 씁니다. bytes(for:)는 헤더가 오는 즉시 돌아오고, 본문은 AsyncSequence로 뒤에 흘러옵니다.

③ .lines — 바이트 시퀀스에 .lines를 붙이면 개행 단위로 잘라 String으로 줍니다. SSE는 줄 단위 프로토콜이니 이게 그대로 파서입니다. "data: "로 시작하지 않는 줄(빈 줄)은 버리고, 나머지는 앞 6글자를 떼고 JSON으로 디코딩합니다.

④ 이벤트 분기 — text면 조각을 내보내고(yield), error면 던지고, done이면 끝냅니다. usage는 지금은 무시합니다(토큰 표시는 다음 편).

⑤ AsyncThrowingStream — 이 함수는 호출한 쪽에 "글자 조각이 흘러나오는 시퀀스"를 돌려줍니다. 호출하는 쪽(뷰모델)은 for try await chunk in api.stream(...) 으로 받기만 하면 됩니다. 네트워크 코드가 이 파일 밖으로 새지 않습니다.

⑥ onTermination — 화면에서 ■(중지)를 눌러 시퀀스를 끊으면 이 클로저가 불리고, 안에서 돌던 Task를 취소합니다. 그러면 bytes.lines 루프가 CancellationError로 빠져나오고 소켓이 닫힙니다. 이걸 안 하면 화면은 멈춰도 요청은 끝까지 살아서 토큰을 계속 태웁니다. 제 SeanChat 초기 버전이 정확히 그랬습니다. 중지를 눌렀는데 서버 로그엔 모델이 계속 답하고 있었습니다.

왜 health()를 따로 두나. 5장의 설정 화면에서 "연결 테스트" 버튼이 이걸 부릅니다. 실기기에서 Mac에 안 붙을 때, 문제가 주소인지·방화벽인지·서버인지를 채팅을 보내보지 않고도 알 수 있어서 넣었습니다.

3-3. ChatViewModel.swift — 상태와 보내기/중지

화면이 보여줄 상태(messages, input, isStreaming, errorText)와 "보내기/중지/지우기" 세 동작이 들어 있습니다.

import SwiftUI
import Observation

/// 화면 상태 + 보내기/중지.
/// 대화 이력(messages)은 앱이 들고 있다 — 서버는 아무것도 기억하지 않는다 (1편 7장)
@Observable @MainActor
final class ChatViewModel {
    var messages: [Message] = []
    var input = ""
    var isStreaming = false
    var errorText: String?
    private var task: Task<Void, Never>?

    static let defaultServer = "http://127.0.0.1:8599"
    var serverURL: String { UserDefaults.standard.string(forKey: "serverURL") ?? Self.defaultServer }

    func send() {
        let text = input.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !text.isEmpty, !isStreaming else { return }
        guard let url = URL(string: serverURL) else { errorText = "서버 주소가 이상합니다: \(serverURL)"; return }

        input = ""
        errorText = nil
        messages.append(Message(role: .user, text: text))
        messages.append(Message(role: .assistant, text: ""))   // 빈 말풍선을 먼저 만들어 두고
        let history = Array(messages.dropLast())                // 그 빈 말풍선은 빼고 서버에 보낸다
        isStreaming = true

        task = Task {
            defer { isStreaming = false }
            do {
                for try await delta in ChatAPI(baseURL: url).stream(history) {
                    messages[messages.count - 1].text += delta    // 조각이 올 때마다 마지막 말풍선에 붙인다
                }
            } catch {
                errorText = error.localizedDescription
                if messages.last?.text.isEmpty == true { messages.removeLast() }  // 한 글자도 못 받았으면 빈 말풍선 제거
            }
        }
    }

    func stop() { task?.cancel() }                 // 지금까지 받은 글자는 그대로 남는다
    func clear() { stop(); messages.removeAll(); errorText = nil }
}

빈 말풍선을 먼저 만드는 순서가 이 파일의 핵심입니다. 보내기를 누르면 ① 내 말풍선을 붙이고 ② 모델 말풍선을 빈 문자열로 하나 더 붙인 뒤 ③ 그 빈 것은 빼고 서버에 보냅니다. 그리고 조각이 올 때마다 messages[messages.count - 1].text += delta 로 마지막 말풍선에 이어 붙입니다. messages가 바뀌면 SwiftUI가 알아서 다시 그리니, "타이핑되는 것처럼 보이는" 효과는 이 한 줄이 전부입니다.

@Observable @MainActor 두 개를 같이 붙였습니다.

• @Observable(iOS 17+) — 프로퍼티가 바뀌면 그걸 읽는 뷰만 다시 그려줍니다. 옛 방식(ObservableObject + @Published)보다 코드가 짧습니다. iOS 17 API라서 프로젝트 설정의 Minimum Deployments를 iOS 17.0으로 두었습니다(기본값은 Xcode 버전에 따라 18 또는 26으로 잡혀 있는데, 낮추는 쪽은 자유입니다).
• @MainActor — 이 클래스의 코드는 전부 메인 스레드에서 돈다고 선언합니다. 네트워크 Task 안에서 messages를 고치는데, UI 상태는 메인 스레드에서만 건드려야 하니 이 한 줄로 컴파일러가 대신 지켜줍니다. 참고로 Xcode 26이 만든 새 프로젝트는 빌드 설정에 Default Actor Isolation = MainActor가 켜져 있어서 안 붙여도 같은 뜻이 됩니다. Xcode 16에는 이 설정이 없어서 빼면 동시성 경고·에러가 나니, 어느 쪽이든 되게 명시해 두었습니다.

stop()은 task?.cancel() 한 줄입니다. 취소 신호는 ChatAPI의 onTermination까지 전달되어 소켓이 닫힙니다(3-2 ⑥). 그때까지 받은 글자는 지우지 않고 그대로 둡니다.

catch 블록에서 한 글자도 못 받았으면 빈 말풍선을 지우는 처리도 넣었습니다. 서버가 꺼져 있을 때 "…" 말풍선만 덩그러니 남는 게 보기 싫어서인데, 5장 에러 스크린샷에서 이 처리가 보입니다.

3-4. ContentView.swift — 채팅 화면

자동 생성된 ContentView.swift의 내용을 전부 지우고 아래로 바꿉니다. 101줄이지만 세 덩어리(말풍선 목록 / 입력창 / 말풍선 하나)입니다.

import SwiftUI

struct ContentView: View {
    @State private var vm = ChatViewModel()
    @State private var showSettings = false

    var body: some View {
        NavigationStack {
            VStack(spacing: 0) {
                messageList
                if let err = vm.errorText {
                    Text(err).font(.footnote).foregroundStyle(.red)
                        .padding(.horizontal).padding(.bottom, 4)
                }
                inputBar
            }
            .navigationTitle("SeanChat")
            .navigationBarTitleDisplayMode(.inline)
            .toolbar {
                ToolbarItem(placement: .topBarLeading) {
                    Button("지우기", systemImage: "trash") { vm.clear() }
                        .disabled(vm.messages.isEmpty)
                }
                ToolbarItem(placement: .topBarTrailing) {
                    Button("설정", systemImage: "gearshape") { showSettings = true }
                }
            }
            .sheet(isPresented: $showSettings) { SettingsView() }
        }
    }

    // MARK: 말풍선 목록
    private var messageList: some View {
        ScrollViewReader { proxy in
            ScrollView {
                LazyVStack(spacing: 12) {
                    if vm.messages.isEmpty {
                        ContentUnavailableView("무엇이든 물어보세요",
                                               systemImage: "bubble.left.and.text.bubble.right",
                                               description: Text("Mac에서 step12_server.py가 켜져 있어야 합니다"))
                            .padding(.top, 80)
                    }
                    ForEach(vm.messages) { BubbleView(message: $0) }
                    Color.clear.frame(height: 1).id("bottom")
                }
                .padding()
            }
            .scrollDismissesKeyboard(.interactively)
            .onChange(of: vm.messages.last?.text) {            // 글자가 늘어날 때마다 바닥으로
                proxy.scrollTo("bottom", anchor: .bottom)
            }
        }
    }

    // MARK: 입력창
    private var inputBar: some View {
        HStack(alignment: .bottom, spacing: 8) {
            TextField("메시지", text: $vm.input, axis: .vertical)
                .lineLimit(1...5)
                .textFieldStyle(.roundedBorder)
            if vm.isStreaming {
                Button { vm.stop() } label: { Image(systemName: "stop.circle.fill").font(.title) }
            } else {
                Button { vm.send() } label: { Image(systemName: "arrow.up.circle.fill").font(.title) }
                    .disabled(vm.input.trimmingCharacters(in: .whitespaces).isEmpty)
            }
        }
        .padding()
        .background(.bar)
    }
}

/// 말풍선 하나 — 내 말은 오른쪽 파란색, 모델 말은 왼쪽 회색
struct BubbleView: View {
    let message: Message
    private var isUser: Bool { message.role == .user }

    /// **굵게**, *기울임*, `코드` 같은 인라인 마크다운만 해석한다 (한 줄 개선)
    private var attributed: AttributedString {
        (try? AttributedString(markdown: message.text,
                               options: .init(interpretedSyntax: .inlineOnlyPreservingWhitespace)))
        ?? AttributedString(message.text)
    }

    var body: some View {
        HStack {
            if isUser { Spacer(minLength: 48) }
            Text(message.text.isEmpty ? AttributedString("…") : attributed)
                .padding(.horizontal, 14).padding(.vertical, 10)
                .background(isUser ? Color.accentColor : Color(.secondarySystemBackground),
                            in: RoundedRectangle(cornerRadius: 18))
                .foregroundStyle(isUser ? .white : .primary)
                .textSelection(.enabled)
            if !isUser { Spacer(minLength: 48) }
        }
    }
}

#Preview {
    ContentView()
}

위에서부터 봅니다.

@State private var vm = ChatViewModel() — @Observable 클래스는 @StateObject가 아니라 @State로 들고 있습니다. 이 화면이 살아 있는 동안 뷰모델도 살아 있습니다.

ScrollViewReader + id("bottom") — 목록 맨 끝에 높이 1짜리 투명 뷰를 두고, messages.last?.text가 바뀔 때마다(=글자가 한 조각 붙을 때마다) 거기로 스크롤합니다. 스트리밍 중에 답이 길어져도 화면이 따라 내려가는 건 이 세 줄 덕입니다. 배열 전체를 감시해도 되지만, 스트리밍 중에 바뀌는 건 항상 마지막 말풍선의 글자라 그것만 봅니다.

ContentUnavailableView — 메시지가 없을 때 보이는 빈 화면입니다(iOS 17+). 안내 문구에 "Mac에서 step12_server.py가 켜져 있어야 합니다"를 넣었습니다. 몇 달 뒤의 제가 서버 안 켜고 앱만 켜서 헤맬 게 뻔해서입니다.

입력창 — TextField(..., axis: .vertical) + lineLimit(1...5)로 여러 줄 입력이 됩니다. 스트리밍 중에는 보내기(↑) 대신 중지(■) 버튼이 나옵니다. 버튼 하나를 상태에 따라 바꾸는 게 아니라 if vm.isStreaming 으로 다른 버튼을 그립니다.

BubbleView — 내 말은 오른쪽 파란색, 모델 말은 왼쪽 회색입니다. Spacer(minLength: 48)를 반대쪽에 두어 말풍선이 화면 폭을 다 먹지 않게 했습니다. 텍스트가 비어 있으면(첫 조각이 오기 전) "…"을 보여줍니다. attributed 프로퍼티는 6장에서 설명합니다 — 처음 만들 땐 Text(message.text) 한 줄이었습니다.

여기까지 하면 빌드가 됩니다. SettingsView가 아직 없어서 에러가 나는데, 임시로 .sheet(...) 줄을 주석 처리하거나 5장의 SettingsView.swift를 먼저 만들어 두면 됩니다. 저는 후자로 했습니다.

🔧 4. 첫 실행 — 시뮬레이터에서

Mac에서 서버를 켜 둔 상태로(1장), Xcode 상단에서 시뮬레이터(iPhone 17)를 고르고 ▶를 누릅니다.

기본 서버 주소가 http://127.0.0.1:8599입니다. 시뮬레이터는 Mac과 네트워크를 공유하므로 이 주소로 바로 붙습니다. 별도 설정 없이 첫 질문을 보냈습니다.

1편 11장의 curl 출력이 그대로 말풍선에 타이핑되는 게 보입니다. 보내기를 누르면 빈 말풍선에 "…"이 먼저 뜨고, 첫 조각 "Amazon"이 도착하는 순간 "…"이 사라지고, 이후 조각이 붙는 대로 말풍선이 자랍니다. 연속 캡처 30장 중 내용이 달라진 4장만 골랐고, 실제로는 2초 안쪽입니다.

두 번째 질문에서 확인하고 싶었던 건 기억이었습니다. 서버는 아무것도 저장하지 않습니다(1장 코드에 상태가 없습니다). 그런데 앱이 매 요청에 대화 전체를 실어 보내니, 모델 입장에서는 이어지는 대화입니다.

"두 문장으로 설명해줘"라고 한 첫 질문의 조건을 두 번째 답이 정확히 짚어냅니다("당신은 두 문장으로 설명하라고 했고 …"). 1편 7장에서 파이썬 리스트로 했던 것을 이번엔 [Message] 배열로 한 것뿐이고, 원리는 같습니다. 그리고 1편에서 이야기한 비용 구조도 같습니다 — 대화가 길어질수록 매 요청의 입력 토큰이 늘어납니다. 이 앱은 아직 아무 대책이 없고, 다음 편의 주제입니다.

🔧 5. 설정 화면과 실기기 — 서버 주소를 바꿀 수 있게

시뮬레이터는 127.0.0.1로 되지만, 실제 iPhone에서 127.0.0.1은 폰 자기 자신입니다. Mac의 LAN 주소(예: 192.168.0.10)를 넣을 수 있는 화면이 필요합니다.

5-1. SettingsView.swift

import SwiftUI

/// 서버 주소 입력 + 연결 테스트. 주소는 @AppStorage로 저장돼 앱을 다시 켜도 남는다
struct SettingsView: View {
    @AppStorage("serverURL") private var serverURL = ChatViewModel.defaultServer
    @State private var status = ""
    @Environment(\.dismiss) private var dismiss

    var body: some View {
        NavigationStack {
            Form {
                Section("백엔드 서버") {
                    TextField("http://192.168.0.10:8599", text: $serverURL)
                        .keyboardType(.URL)
                        .textInputAutocapitalization(.never)
                        .autocorrectionDisabled()
                    Button("연결 테스트") { Task { await test() } }
                    if !status.isEmpty { Text(status).font(.footnote) }
                }
                Section {
                    Text("시뮬레이터 → http://127.0.0.1:8599\n실제 iPhone → http://<Mac의 IP>:8599 (같은 Wi-Fi)")
                        .font(.footnote).foregroundStyle(.secondary)
                }
            }
            .navigationTitle("설정")
            .toolbar { Button("완료") { dismiss() } }
        }
    }

    private func test() async {
        guard let url = URL(string: serverURL) else { status = "❌ 주소 형식이 이상합니다"; return }
        do {
            let h = try await ChatAPI(baseURL: url).health()
            status = h.ok ? "✅ 연결 성공 — \(h.model)" : "❌ 서버 응답 이상"
        } catch {
            status = "❌ \(error.localizedDescription)"
        }
    }
}

#Preview {
    SettingsView()
}

@AppStorage("serverURL")가 이 파일의 전부입니다. UserDefaults에 자동으로 저장되고, 앱을 지우지 않는 한 남습니다. ChatViewModel은 같은 키를 UserDefaults.standard.string(forKey: "serverURL")로 읽으니 두 파일이 같은 값을 봅니다.

"연결 테스트" 버튼은 3장의 health()를 부릅니다. 성공하면 서버가 쓰는 모델 ID를 보여주도록 했습니다. 어느 모델에 붙어 있는지 앱에서 바로 보이는 게 의외로 유용했습니다.

서버를 꺼 두고 질문을 보내면 이렇게 됩니다. 3-3에서 넣은 "한 글자도 못 받았으면 빈 말풍선 제거"가 동작해서, 내 말풍선만 남고 아래에 빨간 한 줄이 뜹니다.

5-2. Mac 주소 찾기

실기기에서 붙을 Mac의 LAN 주소는 터미널에서 이렇게 봅니다(Wi-Fi가 en0일 때).

ipconfig getifaddr en0

192.168.123.120

폰과 Mac이 같은 Wi-Fi에 있어야 하고, 서버는 1장처럼 --host 0.0.0.0으로 떠 있어야 합니다. macOS 방화벽이 켜져 있으면 처음 접속 때 "python이 들어오는 연결을 허용할까요" 팝업이 뜨는데 허용합니다.

5-3. Info.plist — 로컬 네트워크 권한

iOS 14부터, 앱이 같은 Wi-Fi의 다른 기기(여기서는 Mac)에 붙으려 하면 시스템이 로컬 네트워크 권한을 묻습니다. 그 팝업에 들어갈 설명 문구를 Info.plist에 넣어야 합니다.

Xcode에서는 프로젝트 → 타깃 SeanChat → Info 탭 → 표 위에서 우클릭 → Add Row → Privacy - Local Network Usage Description을 고르고 문구를 넣으면 됩니다. 결과 파일은 이렇습니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSLocalNetworkUsageDescription</key>
    <string>Mac에서 실행 중인 SeanChat 백엔드(포트 8599)에 연결하기 위해 로컬 네트워크 접근이 필요합니다.</string>
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsLocalNetworking</key>
        <true/>
    </dict>
</dict>
</plist>

NSAppTransportSecurity › NSAllowsLocalNetworking도 같이 넣었습니다. iOS는 기본적으로 http://(TLS 없음) 연결을 막는데(ATS), 이 키는 IP 주소·.local·호스트명만 있는 주소에 한해 그 제한을 풉니다. Apple 문서에 따르면 iOS 16까지는 IP 주소 접속이 기본 허용이었지만 iOS 17부터는 이 키가 있어야 합니다. 4장의 시뮬레이터 스크린샷은 실제로 이 키 없이 127.0.0.1로 찍은 것이라 루프백은 예외인 듯한데, 실기기에서 192.168.x.x로 붙을 때는 넣어야 안전합니다. (공인 도메인에 http://로 붙는 건 이 키로는 안 풀립니다. 그땐 HTTPS를 붙이는 게 답이고, 3편에서 EC2 + ALB로 그렇게 합니다.)

⚠️ 여기서 한 번 걸렸습니다 — Multiple commands produce '…/SeanChat.app/Info.plist' 저는 위 XML을 손으로 써서 SeanChat 폴더에 넣고, 빌드 설정 INFOPLIST_FILE을 그 파일로 지정했습니다. 그러자 위 에러로 빌드가 깨졌습니다. 2장 끝에서 말한 폴더 자동 동기화 때문입니다 — 폴더 안의 Info.plist가 "리소스"로도 복사되고 "Info.plist"로도 처리되어 같은 산출물을 두 번 만들려 한 것입니다. Xcode의 Info 탭에서 키를 추가하는 정석 경로로 가면 Xcode가 파일 등록을 스스로 처리해서 보통 이 문제를 만나지 않습니다. 손으로 만들었다면: 왼쪽에서 Info.plist를 선택 → 오른쪽 File Inspector → Target Membership에서 SeanChat 체크를 끕니다. 그러면 리소스 복사에서 빠지고 INFOPLIST_FILE로만 쓰입니다. 저는 그렇게 해서 빌드가 다시 됐습니다.

5-4. 실기기에 올리기

iPhone을 USB로 연결하고(처음엔 폰에서 "이 컴퓨터를 신뢰" 확인), Xcode 상단 기기 목록에서 내 iPhone을 고르고 ▶를 누릅니다.

• Signing: 프로젝트 → 타깃 → Signing & Capabilities에서 Team을 본인 Apple ID로 고릅니다. 스토어에 올릴 앱이 아니라 내 폰에서만 쓸 거라 이걸로 충분합니다.
• 폰 쪽 설정: 첫 실행 때 "신뢰하지 않는 개발자" 경고가 뜨면 설정 → 일반 → VPN 및 기기 관리에서 본인 계정을 신뢰합니다.
• 앱 안에서: 설정(⚙) → 서버 주소를 http://192.168.123.120:8599처럼 Mac 주소로 바꾸고 → 연결 테스트. iOS가 로컬 네트워크 권한 팝업을 띄우면 허용합니다.

여기까지 되면 소파에 앉아 폰으로 Mac의 Bedrock 서버에 질문을 던질 수 있습니다. 제 SeanChat도 정확히 이 단계에서 "쓸 만하다"는 느낌이 처음 들었습니다.

🔧 6. 한 줄 개선 — **굵게**가 그대로 보이는 문제

몇 번 쓰다 보니 바로 눈에 걸리는 게 있었습니다. 모델이 목록을 만들 때 **제목** 식으로 마크다운을 섞어 쓰는데, 앱은 그 별표를 그대로 보여줍니다.

SwiftUI의 Text는 문자열 리터럴에 한해 마크다운을 해석해 주지만, 변수로 넘긴 String은 해석하지 않습니다. 변수를 쓰려면 AttributedString(markdown:)으로 한 번 감싸야 합니다. BubbleView에 이 프로퍼티를 넣고 Text(attributed)로 바꾼 게 3-4 코드의 attributed입니다.

    /// **굵게**, *기울임*, `코드` 같은 인라인 마크다운만 해석한다 (한 줄 개선)
    private var attributed: AttributedString {
        (try? AttributedString(markdown: message.text,
                               options: .init(interpretedSyntax: .inlineOnlyPreservingWhitespace)))
        ?? AttributedString(message.text)
    }

옵션의 inlineOnlyPreservingWhitespace가 중요합니다. 기본 옵션(.full)으로 하면 마크다운 파서가 줄바꿈을 접어 버려서, 모델이 정성껏 나눠 준 목록이 한 덩어리로 붙습니다. 인라인 문법(굵게·기울임·코드)만 해석하고 줄바꿈은 그대로 두라는 옵션입니다.

스크린샷 오른쪽을 보면 첫 줄 # iOS 앱 개발 초보자의 흔한 실수 3가지의 헤딩(#)은 여전히 그대로입니다. 인라인만 해석하니 당연합니다. 코드 블록·표·헤딩까지 제대로 그리려면 마크다운 렌더러가 필요하고, 그건 이 한 줄로는 안 됩니다. 제 SeanChat 앱은 결국 렌더러를 따로 만들었는데(코드 블록 복사 버튼, 표 가로 스크롤 등) 이번 편 범위는 넘어서서 여기서 멈춥니다. 대신 서버의 시스템 프롬프트에 "마크다운 헤딩은 쓰지 말고 굵게로 대신해라"를 넣는 것도 방법입니다 — 앱을 고치는 것보다 서버 프롬프트 한 줄이 빠릅니다. 이게 1장에서 말한 "Thin 클라이언트"의 장점입니다.

⚠️ 이번 편에서 만난 에러 모음

Could not connect to the server (실기기)

세 가지 중 하나입니다. 위에서부터 확인합니다.

1. 서버를 --host 0.0.0.0 없이 띄웠다 → 1장. lsof -iTCP:8599 -sTCP:LISTEN에서 *:8599가 아니라 127.0.0.1:8599로 보이면 이겁니다.
2. 폰과 Mac이 다른 네트워크다(폰이 LTE, Mac이 Wi-Fi 등).
3. macOS 방화벽이 python을 막고 있다 → 시스템 설정 → 네트워크 → 방화벽 → 옵션에서 python 허용.

설정 → 연결 테스트 버튼이 /health만 부르기 때문에, 채팅을 보내기 전에 이걸로 먼저 확인하면 원인을 빨리 좁힐 수 있습니다.

The Internet connection appears to be offline (실기기, Wi-Fi는 켜져 있는데)

1번을 고쳐서 Mac 쪽에서는 curl http://192.168.x.x:8599/health가 200을 주는데도 폰에서만 이 메시지가 나왔습니다. 인터넷이 끊긴 게 아니라, iOS가 로컬 네트워크 접근을 막았을 때 URLSession이 이렇게(-1009) 포장해서 내보냅니다. 설정 → 개인정보 보호 및 보안 → 로컬 네트워크에서 앱 토글을 켜면 됩니다. 그런데 그 목록에 앱이 없다면 iOS가 권한을 물어본 적조차 없다는 뜻인데, 제 경우 Info.plist에 NSLocalNetworkUsageDescription이 빠진 빌드에서 그랬습니다. 5-3의 키를 넣고 다시 설치하면 첫 접속 때 팝업이 뜹니다.

Multiple commands produce '…/Info.plist'

5-3 참고. 손으로 만든 Info.plist가 리소스로도 복사되고 있어서입니다. File Inspector → Target Membership 체크 해제.

말풍선이 "…"에서 멈추고 아무것도 안 나온다

서버 로그를 봅니다. POST /chat 200이 찍혔는데 앱에 글자가 안 오면 대부분 Bedrock 쪽 에러입니다(모델 액세스 미승인, 자격증명 만료, 1편 에러 모음 참고). 1장 서버는 이걸 {"type": "error"} 이벤트로 흘려보내고, 앱은 빨간 한 줄로 보여주게 되어 있습니다. 그게 안 보인다면 서버가 1편 step11_server.py 그대로(에러 처리 없음)인지 확인합니다.

시뮬레이터에서 한글이 안 쳐진다

Mac 키보드로 시뮬레이터에 한글을 치려면 시뮬레이터 메뉴 I/O → Keyboard → Connect Hardware Keyboard가 켜져 있어야 합니다. 꺼져 있으면 화면 키보드로만 입력됩니다. 반대로 켜져 있으면 화면 키보드가 안 뜨는데, 이건 정상입니다.

중지(■)를 눌렀는데 서버 로그에선 모델이 계속 답한다

AsyncThrowingStream의 onTermination에서 task.cancel()을 안 했을 때 생깁니다(3-2 ⑥). 앱 화면만 멈추고 소켓은 살아 있어서 토큰이 계속 소모됩니다. 서버 로그로만 보이는 문제라 눈치채기 어렵습니다.

빌드는 되는데 @Observable을 못 찾는다

Minimum Deployments가 iOS 16 이하로 잡혀 있을 때입니다. 프로젝트 → 타깃 → General → Minimum Deployments를 17.0 이상으로.

📝 정리

이번 편에서 한 것:

기억에 남는 것 세 가지:

1. SSE는 앱 쪽에서 bytes(for:) + .lines 두 개로 끝난다. 라이브러리가 필요 없었습니다.
2. 대화 기억은 앱이 들고 있다. 서버는 상태가 없고, 그래서 서버를 아무 때나 죽이고 다시 띄워도 앱은 모릅니다. 1편 7장의 파이썬 리스트가 [Message]가 된 것뿐입니다.
3. 앱은 얇게, 판단은 서버에. 마크다운 헤딩 문제도 앱을 고치는 대신 서버 프롬프트 한 줄로 풀 수 있었습니다. 이 구조 덕에 앱 심사·재설치 없이 서버만 계속 고쳐 나갈 수 있습니다.

지금 앱은 대화 하나가 전부입니다. 앱을 죽이면 대화가 사라지고, 대화가 길어질수록 매 요청의 입력 토큰이 늘어나고, 서버는 Mac이 잠들면 같이 잠듭니다. 이 세 가지가 다음 편들의 주제입니다.

이 글의 코드는 그대로 복사해서 빌드되도록 파일 단위로 실었습니다. 막히는 부분이 있으면 댓글로 남겨 주세요. 저도 Swift는 이 앱으로 배운 입장이라, 더 나은 방법이 있으면 배우고 싶습니다.

이 글에서는 Amazon Bedrock을 이용해 개인용 AI 어시스턴트를 처음부터 만들어봅니다. LangChain 같은 프레임워크 없이 boto3로 직접 호출하면서, Bedrock의 기초 기능을 하나씩 눌러봅니다.

저는 올해 초부터 SeanChat이라는 개인 어시스턴트를 만들어 쓰고 있습니다. 터미널(CLI)과 iPhone 앱이 같은 백엔드에 붙고, 백엔드는 Bedrock의 Claude 모델을 호출합니다. 파일 읽기·셸 명령·웹 검색 같은 도구도 붙어 있어서, 요즘은 일할 때 거의 항상 켜놓고 있습니다.

처음엔 저도 "Bedrock 호출하는 게 뭐 어렵겠어"라고 생각했는데, 모델 ID를 그대로 넣었더니 거부당하는 것부터 시작해서 생각보다 많이 헤맸습니다. 그때 하나씩 실험하면서 정리한 것을 그대로 옮긴 글입니다.

이 시리즈는 이렇게 이어질 예정입니다.

이 글의 모든 실행 결과는 제 개인 계정(us-east-2)에서 2026년 9월에 실제로 돌린 출력을 그대로 붙인 것입니다. 한 단계에 파이썬 파일 하나씩, 전부 합쳐도 200줄이 안 됩니다.

📦 Bedrock 30초 이해 — 용어부터

코드를 치기 전에 용어 몇 개만 잡고 가겠습니다. 이걸 모르면 에러 메시지를 읽을 수 없습니다.

Bedrock의 API는 크게 두 층입니다. 이것도 처음에 헷갈렸던 부분입니다.

bedrock          ← 컨트롤 플레인: 모델 목록 조회, 액세스 관리 (aws bedrock list-foundation-models)
bedrock-runtime  ← 데이터 플레인: 실제로 모델에게 질문 (converse, converse_stream)

boto3에서 boto3.client("bedrock")과 boto3.client("bedrock-runtime")은 다른 클라이언트입니다. bedrock 클라이언트로 converse를 부르면 그런 메서드 없다고 합니다.

🛠️ 0. 사전 준비

0-1. 리전 선택과 모델 액세스

Bedrock은 리전마다 쓸 수 있는 모델이 다릅니다. 저는 us-east-2(오하이오)를 씁니다. 서울(ap-northeast-2)도 되지만, 신모델이 미국 리전에 먼저 풀리는 경우가 많아서 개인 프로젝트는 미국 리전을 추천합니다.

콘솔에서 먼저 모델 액세스를 켭니다.

Bedrock 콘솔 → 좌측 메뉴 맨 아래 Model access → Modify model access
→ 쓸 모델(Anthropic Claude ...) 체크 → Submit

처음 쓰는 계정이면 몇 분 안에 Access granted로 바뀝니다. 이걸 안 켜고 호출하면 AccessDeniedException이 뜨는데, IAM 권한 문제와 메시지가 같아서 처음엔 구분이 안 됩니다. 구분법은 이 글 마지막 "에러 모음"에 정리했습니다.

0-2. 자격증명 — 두 가지 방법

저는 처음엔 SSO 프로필로 하다가, 백엔드를 EC2에 올리면서 두 번째로 바꿨습니다. SSO 토큰은 몇 시간마다 만료돼서 상시 구동 서버에는 맞지 않습니다.

Bedrock은 서비스 전용 자격증명(service-specific credential) 을 지원합니다. AWS_BEARER_TOKEN_BEDROCK 환경변수 하나만 있으면 boto3가 알아서 씁니다.

# 발급 (만료일이 있습니다 — 상시 구동 서버라면 만료일을 캘린더에 걸어두세요)
aws iam create-service-specific-credential \
  --user-name <Bedrock 전용 IAM 사용자> \
  --service-name bedrock.amazonaws.com

# 사용
echo 'export AWS_BEARER_TOKEN_BEDROCK=<발급된 키>' > ~/.bedrock.env
chmod 600 ~/.bedrock.env && source ~/.bedrock.env

그 IAM 사용자에게 붙일 정책은 이 정도로 충분합니다(최소 권한).

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock:InvokeModel",
      "bedrock:InvokeModelWithResponseStream",
      "bedrock:Converse",
      "bedrock:ConverseStream",
      "bedrock:ListFoundationModels",
      "bedrock:ListInferenceProfiles",
      "bedrock:GetFoundationModelAvailability"
    ],
    "Resource": "*"
  }]
}

자격증명이 제대로 잡혔는지 확인하는 가장 빠른 방법은 그냥 한 번 호출해보는 겁니다. 안 잡혀 있으면 이렇게 나옵니다(실제 출력).

NoCredentialsError: Unable to locate credentials

권한이 모자라면 이렇게 나옵니다. 메시지 안에 어떤 액션이 거부됐는지 그대로 적혀 있으니 당황하지 말고 is not authorized to perform: 뒤를 읽으면 됩니다.

AccessDeniedException: User: arn:aws:iam::123456789012:user/bedrock-user is not authorized
to perform: bedrock:CountTokens on resource: arn:aws:bedrock:us-east-2::foundation-model/anthropic.claude-haiku-4-5-20251001-v1:0
because no identity-based policy allows the bedrock:CountTokens action

위 에러는 이 글을 쓰다가 실제로 만난 겁니다. 4장에서 써보려던 count_tokens가 위 정책에 없어서 났습니다. 해결은 메시지에 적힌 그대로 — 정책 Action에 bedrock:CountTokens를 추가하는 것입니다. Bedrock 에러는 메시지가 친절한 편이라 끝까지 읽는 습관만 있으면 절반은 해결됩니다.

0-3. 파이썬 환경

mkdir bedrock-lab && cd bedrock-lab
python3 -m venv .venv && source .venv/bin/activate
pip install boto3 fastapi "uvicorn[standard]"

boto3는 최신으로 두세요. Bedrock은 기능이 자주 추가돼서 오래된 boto3에는 파라미터 자체가 없는 경우가 있습니다.

🔧 1. 어떤 모델을 부를 수 있나 — 모델 ID 호출 거부?

제일 먼저 한 일은 "이 리전에 무슨 모델이 있나" 조회였습니다.

aws bedrock list-foundation-models --region us-east-2 \
  --query "modelSummaries[?contains(modelId,'claude')].modelId" --output table

-----------------------------------------------
|            ListFoundationModels             |
+---------------------------------------------+
|  anthropic.claude-sonnet-4-20250514-v1:0    |
|  anthropic.claude-haiku-4-5-20251001-v1:0   |
|  anthropic.claude-sonnet-4-5-20250929-v1:0  |
|  anthropic.claude-opus-4-5-20251101-v1:0    |
|  anthropic.claude-sonnet-4-6                |
|  anthropic.claude-opus-4-6-v1               |
|  ...                                        |
+---------------------------------------------+

여기 나온 anthropic.claude-haiku-4-5-20251001-v1:0을 그대로 코드에 넣었습니다. 그리고 첫 에러를 만났습니다.

ValidationException: Invocation of model ID anthropic.claude-haiku-4-5-20251001-v1:0
with on-demand throughput isn't supported. Retry your request with the ID or ARN of
an inference profile that contains this model.

"모델 목록에 있는데 왜 못 부르지?"가 첫 반응이었습니다. 읽어보면 답이 적혀 있습니다 — inference profile의 ID를 쓰라는 겁니다.

최신 모델들은 특정 리전 한 곳에서만 처리하는 on-demand 호출을 막고, 크로스 리전 추론 프로파일로만 열어둔 경우가 많습니다. 목록을 따로 조회합니다.

aws bedrock list-inference-profiles --region us-east-2 \
  --query "inferenceProfileSummaries[?contains(inferenceProfileId,'claude')].[inferenceProfileId,status]" \
  --output table

----------------------------------------------------------------
|                     ListInferenceProfiles                    |
+----------------------------------------------------+---------+
|  us.anthropic.claude-haiku-4-5-20251001-v1:0       |  ACTIVE |
|  global.anthropic.claude-haiku-4-5-20251001-v1:0   |  ACTIVE |
|  us.anthropic.claude-sonnet-4-5-20250929-v1:0      |  ACTIVE |
|  global.anthropic.claude-sonnet-4-5-20250929-v1:0  |  ACTIVE |
|  us.anthropic.claude-sonnet-4-6                    |  ACTIVE |
|  ...                                               |         |
+----------------------------------------------------+---------+

같은 모델에 접두어가 붙은 ID가 두 종류씩 있습니다.

이 글에서는 전부 us.anthropic.claude-haiku-4-5-20251001-v1:0 을 씁니다. Haiku는 Claude 중 가장 빠르고 저렴해서 실험용으로 딱 맞습니다.

💡 모델 ID는 코드에 흩뿌리지 말고 한 곳에 별칭으로 모으세요. 저는 {"haiku": "us.anthropic.claude-haiku-4-5-...", "sonnet": "us.anthropic.claude-sonnet-4-5-..."} 딕셔너리 하나에 두고 설정에서 별칭만 바꿉니다. 위 목록만 봐도 알 수 있듯이 모델은 몇 달마다 갱신됩니다.

🔗 위 두 명령(list-foundation-models·list-inference-profiles)의 결과를 매일 자동으로 갱신해 한 페이지에 정리해 두었습니다 → hub.sean-chloe.com/bedrock — 서울 리전에서 지금 호출 가능한 모델, on-demand/CRIS 구분, 버지니아엔 있는데 서울엔 없는 모델 목록, 변경 이력 RSS. 글 작성 시점 이후 새로 열린 모델은 여기서 확인하세요.

🔧 2. 첫 호출 — Converse API, 그리고 응답 해부

Bedrock에는 모델을 부르는 방법이 두 가지 있습니다.

Converse를 쓰세요. 나중에 모델을 Haiku에서 Sonnet으로, 또 Nova로 바꿔도 코드를 안 고칩니다.

step2_converse.py — 첫 호출입니다. 응답을 통째로 찍어서 구조를 봅니다.

"""응답 전체를 그대로 찍어보기 — 구조를 눈으로 익히는 게 먼저다"""
import boto3, json

runtime = boto3.client("bedrock-runtime", region_name="us-east-2")   # ← bedrock 아님, bedrock-runtime

resp = runtime.converse(
    modelId="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    messages=[{"role": "user", "content": [{"text": "안녕! 한 문장으로 인사해줘."}]}],
    inferenceConfig={"maxTokens": 100},
)
resp.pop("ResponseMetadata", None)              # HTTP 메타는 지우고 본문만
print(json.dumps(resp, ensure_ascii=False, indent=2))

$ python step2_converse.py
{
  "output": {
    "message": {
      "role": "assistant",
      "content": [
        {
          "text": "안녕하세요, 반갑습니다! 😊"
        }
      ]
    }
  },
  "stopReason": "end_turn",
  "usage": {
    "inputTokens": 26,
    "outputTokens": 22,
    "totalTokens": 48,
    "cacheReadInputTokens": 0,
    "cacheWriteInputTokens": 0
  },
  "metrics": {
    "latencyMs": 650
  }
}

처음 성공했을 때 이 JSON을 한참 들여다봤는데, 결국 이 글 전체가 이 구조의 응용입니다. 요청과 응답 각각 한 번씩만 정확히 익히면 됩니다.

요청 구조

messages=[
  {"role": "user",                     # user 또는 assistant, 반드시 번갈아
   "content": [                        # ← 배열! 문자열이 아님
     {"text": "안녕! ..."}             # 텍스트 블록. 이미지·문서 블록도 여기 들어감
   ]}
]

content가 문자열이 아니라 블록 배열인 게 처음엔 번거롭게 느껴지지만, 나중에 이미지·문서·도구 결과를 같은 자리에 넣게 되면 이유를 알게 됩니다.

응답 구조

⚠️ content[0]["text"]로 꺼내면 언젠가 터집니다. content는 배열이고 첫 블록이 텍스트라는 보장이 없습니다. 도구를 붙이면 첫 블록이 toolUse인 경우가 흔해서 KeyError: 'text'가 납니다. 처음부터 이렇게 순회하는 습관을 들이세요.

text = "".join(b.get("text", "") for b in resp["output"]["message"]["content"])

응답의 output.message가 요청의 messages[i]와 완전히 같은 형식이라는 점도 눌러두세요. 그래서 7장에서 "응답을 그대로 append"하는 게 가능합니다.

🔧 3. 파라미터 하나씩 체감하기 — inferenceConfig

inferenceConfig에 들어가는 값이 넷 있습니다. 문서로 읽으면 뻔한데 직접 돌려보면 감이 옵니다.

step3_params.py — 세 가지를 실제로 눌러봤습니다.

def ask(label, q, **cfg):
    resp = runtime.converse(modelId=MODEL, inferenceConfig=cfg,
                            messages=[{"role": "user", "content": [{"text": q}]}])
    txt = "".join(b.get("text", "") for b in resp["output"]["message"]["content"])
    print(f"[{label}] stopReason={resp['stopReason']}  out={resp['usage']['outputTokens']}토큰")
    print(f"   → {txt!r}\n")

ask("maxTokens=20", "클라우드 컴퓨팅을 자세히 설명해줘.", maxTokens=20)
ask("stopSequences", "1, 2, 3, 4, 5까지 세어줘.", maxTokens=100, stopSequences=["3"])

for t in (0.0, 1.0):                                   # 같은 질문을 3번씩
    outs = []
    for _ in range(3):
        resp = runtime.converse(modelId=MODEL, inferenceConfig={"maxTokens": 40, "temperature": t},
            messages=[{"role": "user", "content": [{"text": "귀여운 강아지 이름 하나만 지어줘. 이름만."}]}])
        outs.append("".join(b.get("text", "") for b in resp["output"]["message"]["content"]).strip())
    print(f"temperature={t} → {outs}")

$ python step3_params.py
[maxTokens=20] stopReason=max_tokens  out=20토큰
   → '# 클라우드 컴퓨팅 상세 설명'

[stopSequences] stopReason=stop_sequence  out=8토큰
   → '1, 2, '

temperature=0.0 → ['뭉치', '뭉치', '뭉치']
temperature=1.0 → ['뽀삐', '뽀삐', '뭉치']

세 줄에서 배운 것을 정리하면 이렇습니다.

① maxTokens는 "잘라내기"다. 자세히 설명해달라고 했는데 20토큰에서 제목만 쓰고 끊겼습니다. 중요한 건 stopReason이 max_tokens 로 온다는 점입니다. 답변이 뚝 끊긴 채로 왔는데 원인을 못 찾고 있다면, 십중팔구 이 값을 확인 안 한 겁니다. stopReason == "max_tokens"이면 화면에 "출력 상한에 걸려 잘렸습니다" 표시를 붙여두는 것을 권합니다.

② stopSequences는 즉시 멈춤. "3"을 만나자마자 멈춰서 '1, 2, '까지만 왔고, stopReason은 stop_sequence 입니다. 정해진 형식으로만 답을 받을 때(예: ###END### 마커) 씁니다.

③ temperature는 "같은 질문에 같은 답이 나오게 할 것인가". 0으로 놓으면 세 번 다 뭉치, 1.0으로 놓으면 갈립니다. 테스트 코드·분류·정형 추출은 0 근처, 아이디어·글쓰기는 높게. 저는 범용 어시스턴트라 기본값을 0.7로 두고 있습니다.

💡 stopReason을 무시하면 안 되는 이유가 여기서 나옵니다. 같은 "정상 응답(200 OK)"이라도 end_turn(다 말함)과 max_tokens(잘림)는 완전히 다른 상황입니다. HTTP 상태코드가 아니라 stopReason이 진짜 결과 코드입니다.

🔧 4. 토큰이란 무엇인가 — 요금의 단위

Bedrock 요금은 토큰 단위로 계산됩니다. 그런데 토큰은 글자도 단어도 아닙니다. 이게 얼마나 다른지 직접 재봤습니다.

토큰을 세는 정식 방법은 count_tokens API인데(0장에서 권한 에러가 났던 그것), 권한을 추가하기 전이라 우회했습니다 — maxTokens=1로 호출해서 usage.inputTokens만 읽는 방법입니다. 출력 토큰 1개 값만 내면 입력 토큰 수를 정확히 알 수 있습니다.

step4_tokens.py

def input_tokens(text):
    resp = runtime.converse(modelId=MODEL, inferenceConfig={"maxTokens": 1},
                            messages=[{"role": "user", "content": [{"text": text}]}])
    return resp["usage"]["inputTokens"]

BASE = input_tokens("a") - 1        # 한 글자 요청의 토큰 − 1 = 메시지 래핑 오버헤드
print(f"기본 오버헤드: {BASE} 토큰\n")

for label, text in [
    ("영어 10단어", "The quick brown fox jumps over the lazy dog today"),
    ("한글 같은 뜻", "빠른 갈색 여우가 오늘 게으른 개를 뛰어넘는다"),
    ("숫자·기호",   '2026-09-20T22:07:59+09:00 {"a":1}'),
]:
    n = input_tokens(text) - BASE
    print(f"{label:<12}{len(text):>6}자 {n:>6}토큰  {len(text)/n:>5.2f}자/토큰")

$ python step4_tokens.py
기본 오버헤드: 7 토큰

영어 10단어      49자     11토큰   4.45자/토큰
한글 같은 뜻     25자     32토큰   0.78자/토큰
숫자·기호        33자     23토큰   1.43자/토큰

이 결과를 처음 보고 좀 놀랐습니다.

한국어로 쓰는 어시스턴트는 영어보다 입력 요금이 ~3배 나간다는 뜻입니다. 시스템 프롬프트를 한국어로 길게 쓰고 있다면 한 번 세어볼 가치가 있습니다. 매 요청마다 들어가는 시스템 프롬프트의 규칙 부분만 영어로 써도 입력 토큰이 눈에 띄게 줄어듭니다(모델은 영어 지시를 한국어 답변에 잘 적용합니다).

요금 계산은 이렇게

비용 = 입력토큰 × 입력단가 + 출력토큰 × 출력단가      (단가는 "백만 토큰당 $")

예를 들어 2장의 첫 호출(입력 26 + 출력 22 토큰)은 어떤 단가를 넣어도 $0.0001 미만입니다. 개인 어시스턴트는 호출 한 번이 아니라 대화가 길어지며 입력 토큰이 누적되는 것이 비용의 본체인데, 그 얘기는 7장에서 숫자로 봅니다.

💡 usage는 모든 응답에 들어 있습니다. 첫날부터 이 값을 로그에 남기세요. 저는 SQLite에 호출 단위로 inputTokens/outputTokens/model을 쌓아두는데, 나중에 "이번 달 왜 이렇게 나왔지"를 추적할 때 이것 말고는 방법이 없습니다.

🔧 5. 시스템 프롬프트 — 모델에게 역할 주기

지금까지는 질문만 던졌습니다. 어시스턴트답게 만들려면 역할과 규칙을 먼저 줘야 합니다. 그게 system 파라미터입니다. messages와 분리돼 있고, 대화 내내 유지됩니다.

step5_system.py

resp = runtime.converse(
    modelId=MODEL,
    system=[{"text": "너는 한국어로 짧고 정확하게 답하는 조수다."}],     # ← 역할·규칙
    messages=[{"role": "user", "content": [{"text": "Bedrock Converse API를 한 문장으로 설명해줘."}]}],
    inferenceConfig={"maxTokens": 300, "temperature": 0.2},
)
print("답변:", "".join(b.get("text", "") for b in resp["output"]["message"]["content"]))
print("토큰:", resp["usage"])
print("지연(ms):", resp["metrics"]["latencyMs"])

$ python step5_system.py
답변: Bedrock Converse API는 AWS에서 제공하는 통일된 인터페이스로, 다양한 기초 모델과의 멀티턴 대화를 간편하게 처리할 수 있는 API입니다.
토큰: {'inputTokens': 54, 'outputTokens': 74, 'totalTokens': 128, 'cacheReadInputTokens': 0, 'cacheWriteInputTokens': 0}
지연(ms): 1071

시스템 프롬프트에 대해 처음에 알았으면 좋았을 것들입니다.

💡 시스템 프롬프트는 "누구인지 → 무엇을 하는지 → 하지 말 것 → 출력 형식" 순서가 잘 먹혔습니다. 그리고 프롬프트는 코드보다 훨씬 자주 바뀝니다. 코드 여기저기에 문자열로 흩뿌리지 말고 한 곳(상수 하나 또는 파일 하나)에 모아두세요. SeanChat도 시스템 프롬프트가 설정 모듈 한 곳에 있습니다.

🔧 6. 스트리밍 — 이벤트 구조를 눈으로 보기

converse는 답변이 다 만들어질 때까지 기다렸다가 한 번에 옵니다. 긴 답변이면 5~10초 동안 화면이 멈춰 있습니다. 챗봇 느낌이 나려면 글자가 흘러나와야 하고, 그게 converse_stream 입니다.

처음엔 "글자가 하나씩 오겠지"라고 생각했는데, 실제로 어떤 이벤트가 오는지 그대로 찍어보니 달랐습니다.

step6_stream.py

resp = runtime.converse_stream(
    modelId=MODEL,
    messages=[{"role": "user", "content": [{"text": "1부터 5까지 세어줘. 숫자만."}]}],
    inferenceConfig={"maxTokens": 200},
)

for ev in resp["stream"]:                  # ← 응답이 아니라 이벤트 제너레이터
    kind = next(iter(ev))                  # 이벤트 이름이 곧 딕셔너리 키다
    if kind == "contentBlockDelta":
        print(f"  [delta] {ev[kind]['delta'].get('text', '')!r}")
    else:
        print(f"[{kind}] {json.dumps(ev[kind], ensure_ascii=False)[:120]}")

$ python step6_stream.py
[messageStart] {"role": "assistant"}
  [delta] '1'
  [delta] '\n2\n3\n4\n5'
[contentBlockStop] {"contentBlockIndex": 0}
[messageStop] {"stopReason": "end_turn"}
[metadata] {"usage": {"inputTokens": 27, "outputTokens": 13, "totalTokens": 40}, "metrics": {"latencyMs": 664}}

delta가 '1' 다음에 '\n2\n3\n4\n5'로 온 게 보이시죠. 청크 크기는 보장되지 않습니다. 한 글자일 때도 있고 문단째로 올 때도 있습니다.

이게 왜 중요하냐면, 마크다운을 실시간으로 렌더링하려고 하면 청크 경계에서 문법이 잘립니다. **굵게 까지 온 상태에서 렌더하면 별표가 그대로 보이고, 다음 청크에 **가 와서 닫힙니다. 저는 iOS 앱에서 이걸로 한 번 크게 당해서, 결국 청크를 모아 블록(문단·코드블록) 단위로 파싱하는 쪽으로 정리했습니다.

💡 converse의 응답 하나가 converse_stream에서는 이벤트 5~6종으로 흩어진 것뿐입니다. 스트림 이벤트를 다시 모으면 converse의 응답과 같은 메시지가 됩니다. 그래서 저는 스트림을 소비하면서 동시에 완성된 assistant 메시지를 조립해두고, 그걸 7장의 대화 기록에 넣습니다.

🔧 7. 대화 기억 — 상태는 서버가 Local에 저장

여기서 저는 처음으로 "아, 이건 채팅 서비스가 아니라 함수구나"를 느꼈습니다.

Bedrock은 대화를 기억해주지 않습니다. 세션 개념이 없습니다. 매 요청에 지금까지의 대화 전체를 다시 보내야 합니다.

step7_chat.py

messages = []                                    # ← 이게 대화 기억의 전부다

def ask(text):
    messages.append({"role": "user", "content": [{"text": text}]})
    r = runtime.converse(modelId=MODEL, system=SYSTEM, messages=messages,   # 전체를 보낸다
                         inferenceConfig={"maxTokens": 300})
    reply = r["output"]["message"]
    messages.append(reply)                       # ← 응답도 반드시 append (형식이 같아서 그대로 넣는다)
    print(f"👤 {text}\n🤖 {''.join(b.get('text','') for b in reply['content'])}"
          f"   (in={r['usage']['inputTokens']} out={r['usage']['outputTokens']})\n")

ask("내 이름은 Sean이고 AWS에서 일해.")
ask("내 이름이 뭐라고 했지?")                     # append 안 하면 이 답을 못 한다
print("messages 길이:", len(messages))

$ python step7_chat.py
👤 내 이름은 Sean이고 AWS에서 일해.
🤖 Sean님, AWS에서 근무하신다니 반갑습니다! 무엇을 도와드릴까요?   (in=55 out=38)

👤 내 이름이 뭐라고 했지?
🤖 당신의 이름은 Sean이라고 말씀하셨습니다.   (in=112 out=27)

messages 길이: 4

messages.append(reply) 한 줄을 빼고 돌려보면 두 번째 답이 "이름을 말씀하지 않으셨습니다"로 바뀝니다. 직접 한 번 지워보시길 권합니다. 이걸 눈으로 보면 "대화 기억"의 실체가 뭔지 확실해집니다.

여기서 비용 구조가 보입니다

in=55 → in=112. 두 번째 질문은 아홉 글자인데 입력 토큰이 두 배가 됐습니다. 이전 대화(질문 + 답변)를 통째로 다시 보냈기 때문입니다.

1턴: [Q1]                          → 입력 = Q1
2턴: [Q1, A1, Q2]                  → 입력 = Q1 + A1 + Q2
3턴: [Q1, A1, Q2, A2, Q3]          → 입력 = 지금까지 전부
...
N턴 누적 입력 토큰 ∝ N²

100턴짜리 대화 하나가 짧은 대화 100개보다 수십 배 비쌉니다. 4장에서 "호출 한 번은 $0.0001도 안 된다"고 했는데, 비용은 여기서 나옵니다.

이 문제를 푸는 도구가 두 가지고, 하나는 이 글에서, 하나는 5편에서 다룹니다.

지금은 messages 배열이 곧 대화이고, 그걸 내가 들고 있어야 한다는 것만 확실히 하면 됩니다. SeanChat에서는 이 배열을 SQLite에 세션 단위로 저장해두고, CLI와 iPhone이 같은 세션을 이어서 봅니다.

🔧 8. 도구 호출 — "에이전트"의 실체는 while Loop

여기가 이 글에서 제일 재미있는 부분입니다.

AI 어시스턴트가 파일을 읽고, 시각을 알려주고, 명령을 실행하는 건 모델이 하는 일이 아닙니다. 모델은 "이 도구를 이 인자로 불러줘"라고 말만 하고, 실행은 내 코드가 합니다. 처음 이걸 이해했을 때 "에이전트"라는 단어의 신비함이 좀 걷혔습니다.

왕복 구조입니다.

[1] 내 코드 → 모델 : messages + toolConfig(도구 설명서)
[2] 모델 → 내 코드 : stopReason="tool_use", content=[{toolUse: {name, input, toolUseId}}]
[3] 내 코드        : 실제 함수 실행 (파일 읽기·API 호출·셸… 뭐든)
[4] 내 코드 → 모델 : toolResult (toolUseId로 짝을 맞춰서)
[5] 모델 → 내 코드 : stopReason="end_turn" → 최종 답변
                     (또는 다시 tool_use → [3]으로. 그래서 while 루프다)

step8_tool.py — 도구 2개(현재 시각, 파일 읽기)를 붙인 완전한 루프입니다.

먼저 도구 설명서입니다. 모델은 이 JSON Schema만 보고 언제·어떻게 부를지 결정합니다. description이 곧 프롬프트라서 정성껏 써야 합니다.

TOOL_CONFIG = {"tools": [
    {"toolSpec": {
        "name": "get_current_time",
        "description": "현재 시각을 ISO8601로 반환한다.",
        "inputSchema": {"json": {"type": "object", "properties": {}, "required": []}}}},
    {"toolSpec": {
        "name": "read_file",
        "description": "텍스트 파일 내용을 읽어 반환한다.",
        "inputSchema": {"json": {
            "type": "object",
            "properties": {"path": {"type": "string", "description": "파일 경로"}},
            "required": ["path"]}}}},
]}

def run_tool(name, args):                         # 실제 실행은 내 코드가 한다
    if name == "get_current_time":
        return datetime.datetime.now().astimezone().isoformat(timespec="seconds")
    if name == "read_file":
        return pathlib.Path(args["path"]).read_text()[:500]
    return f"unknown tool: {name}"

그리고 루프입니다.

messages = [{"role": "user", "content": [{"text": "지금 몇 시야? 그리고 ./hello.txt 내용도 읽어줘."}]}]

for round_no in range(1, 6):                      # 무한루프 방지 상한은 필수
    r = runtime.converse(modelId=MODEL, messages=messages,
                         toolConfig=TOOL_CONFIG, inferenceConfig={"maxTokens": 500})
    msg = r["output"]["message"]
    messages.append(msg)                          # ① 모델 응답(toolUse 포함)을 그대로 append
    print(f"── round {round_no}  stopReason={r['stopReason']}")

    if r["stopReason"] != "tool_use":             # 도구 요청이 아니면 최종 답변
        print(f"\n🤖 최종답변: {''.join(b.get('text','') for b in msg['content'])}")
        break

    results = []
    for block in msg["content"]:
        if "toolUse" not in block:
            continue
        tu = block["toolUse"]
        out = run_tool(tu["name"], tu.get("input", {}))
        print(f"   🔧 {tu['name']}({json.dumps(tu.get('input', {}), ensure_ascii=False)}) → {out}")
        results.append({"toolResult": {           # ② 결과는 toolUseId로 짝 맞춰서
            "toolUseId": tu["toolUseId"],
            "content": [{"text": out}]}})
    messages.append({"role": "user", "content": results})    # ③ user 역할로 되돌린다

실행하면, 한 라운드에서 도구 2개를 동시에 부르고 다음 라운드에서 답을 냈습니다.

$ python step8_tool.py
── round 1  stopReason=tool_use
   🔧 get_current_time({}) → 2026-09-20T22:59:49+09:00
   🔧 read_file({"path": "./hello.txt"}) → 안녕하세요! 이 파일은 Bedrock 도구 호출 테스트용입니다.

── round 2  stopReason=end_turn

🤖 최종답변: 현재 시간과 파일 내용을 알려드리겠습니다.

**현재 시각:** 2026년 9월 20일 22시 59분 49초 (한국 시간, UTC+9)

**./hello.txt 파일 내용:**
안녕하세요! 이 파일은 Bedrock 도구 호출 테스트용입니다.

이 30줄이 SeanChat 백엔드의 뼈대입니다. 도구가 2개에서 수십 개로 늘고, run_tool이 MCP 서버 호출로 바뀌었을 뿐 루프는 같습니다.

처음에 헷갈렸던 규칙 5개

1. toolUseId 짝을 정확히 맞춘다. 하나라도 빠지면 ValidationException입니다.
2. 모델 응답 메시지를 그대로 append한다. toolUse 블록을 빼거나 텍스트만 추려 넣으면 다음 호출에서 "짝이 안 맞는다"고 거부됩니다.
3. toolResult는 role: "user" 로 보냅니다. "도구 결과인데 왜 user?"가 첫 반응이었는데, 모델 입장에선 "바깥 세계에서 온 입력"이라 user 턴입니다. 규격입니다.
4. 한 라운드에 도구가 여러 개 올 수 있습니다(위 출력처럼). 결과를 한 메시지에 모아 보냅니다. 하나씩 따로 보내면 2번 규칙에 걸립니다.
5. 라운드 상한을 반드시 둡니다. 모델이 같은 도구를 계속 부르는 루프에 빠지면 요금이 그대로 나갑니다. 위에서 range(1, 6)으로 5회 상한을 둔 이유입니다.

⚠️ 놓치기 쉬운 부분 — 빈 도구 배열

권한이나 설정에 따라 도구 목록을 동적으로 필터링하다 보면 빈 배열이 될 때가 있습니다. 이건 거부됩니다.

ParamValidationError: Invalid length for parameter toolConfig.tools,
value: 0, valid min length: 1

→ 목록이 비면 toolConfig 키를 아예 빼야 합니다. {"tools": []}로 보내면 안 됩니다. 저는 kwargs = {...}; if tools: kwargs["toolConfig"] = {...} 형태로 조건부로 넣습니다.

🔧 9. 프롬프트 캐싱 — 비용 절감은 한 줄

7장에서 본 것처럼 시스템 프롬프트와 도구 설명서는 매 요청 똑같이 들어갑니다. 똑같은 걸 매번 정가로 사는 대신 캐시할 수 있습니다. system 배열 끝에 cachePoint 블록 하나만 넣으면 됩니다.

step9_cache.py

# 캐시는 최소 토큰 수를 넘어야 동작한다(아래에서 실측). 긴 시스템 프롬프트를 흉내낸다.
BIG_SYSTEM = ("너는 사내 인프라 규칙을 따르는 어시스턴트다.\n"
              + "\n".join(f"규칙 {i}: 리전은 us-east-2를 사용하고, 태그 Owner/Env/CostCenter를 "
                          f"반드시 붙이며, 퍼블릭 S3 버킷은 금지한다." for i in range(1, 121)))

def call(q, cache: bool):
    system = [{"text": BIG_SYSTEM}]
    if cache:
        system.append({"cachePoint": {"type": "default"}})   # ← 이 한 줄이 전부
    r = runtime.converse(modelId=MODEL, system=system,
                         messages=[{"role": "user", "content": [{"text": q}]}],
                         inferenceConfig={"maxTokens": 100})
    u = r["usage"]
    print(f"cache={'ON ' if cache else 'OFF'} | input={u['inputTokens']:>5} "
          f"write={u['cacheWriteInputTokens']:>5} read={u['cacheReadInputTokens']:>5} "
          f"| {r['metrics']['latencyMs']:>5}ms")

call("리전 규칙이 뭐야? 한 문장.", cache=False)
call("리전 규칙이 뭐야? 한 문장.", cache=True)    # 1회차 = 캐시 기록
call("태그 규칙이 뭐야? 한 문장.", cache=True)    # 2회차 = 캐시 읽기

$ python step9_cache.py
cache=OFF | input= 8214 write=    0 read=    0 |   811ms
cache=ON  | input=   26 write= 8188 read=    0 |   774ms
cache=ON  | input=   26 write=    0 read= 8188 |   772ms

세 번째 줄이 핵심입니다. 반복되는 입력 토큰이 90% 싸집니다. input이 8,214에서 26으로 떨어진 게 보이시죠. 정가로 사는 건 질문 26토큰뿐입니다.

시스템 프롬프트 + 도구 스펙이 수만 토큰인 에이전트에서는 이 한 줄이 월 요금의 절반을 좌우합니다. 2장의 응답 구조에 cacheReadInputTokens / cacheWriteInputTokens가 항상 붙어 있던 이유가 이겁니다.

최소 토큰 — "왜 캐시가 안 걸리지?"

처음 캐시를 켰을 때 write=0 read=0만 나와서 한참 헤맸습니다. 캐시에는 최소 토큰 수가 있습니다. 프롬프트 길이를 바꿔가며 어디서부터 걸리는지 재봤습니다.

$ python step9b_cache_min.py
규칙  10줄 | 총입력   670 | write=    0 read=    0 | 캐시 안 됨 ❌
규칙  30줄 | 총입력  1990 | write=    0 read=    0 | 캐시 안 됨 ❌
규칙  60줄 | 총입력  3970 | write=    0 read=    0 | 캐시 안 됨 ❌
규칙 120줄 | 총입력  7930 | write= 7921 read=    0 | 캐시 됨 ✅

Haiku 4.5는 4천 토큰 조금 아래까지는 캐시가 안 걸렸습니다. 모델마다 이 하한이 다릅니다(1,024~4,096 사이). "캐시 포인트를 넣었는데 write가 0"이면 에러가 아니라 프롬프트가 짧아서 그냥 무시된 것입니다. 에러가 안 나서 더 헷갈립니다.

캐싱을 쓸 때 알아야 할 것

• TTL 5분이고, 읽힐 때마다 갱신됩니다. 5분 넘게 쉬면 다시 기록(1.25x)부터 시작합니다. 대화가 이어지는 동안은 계속 살아 있습니다.
• 캐시 포인트는 요청당 최대 4개입니다. system 끝 / 도구 스펙 끝 / 대화 중간 / 마지막 메시지 앞 정도로 배치합니다.
• ⚠️ 캐시는 "앞에서부터 똑같은 부분"만 적중합니다. 앞쪽이 한 글자만 달라져도 뒤가 전부 미스입니다. 그래서 5장에서 "동적인 값은 끝에"라고 한 겁니다. 시스템 프롬프트 맨 앞에 현재 시각을 찍으면 매 요청 캐시가 통째로 무효화됩니다. (아주 흔한 실수입니다. 시각처럼 매번 바뀌는 값은 프롬프트 맨 뒤, 캐시 포인트 뒤에 두세요.)
• ⚠️ 캐싱 미지원 모델에 cachePoint를 넣으면 ValidationException이 아니라 AccessDeniedException 으로 오는 경우가 있습니다. 권한 문제로 착각하기 쉽습니다.

🔧 10. 추론 과정 보기 — Extended Thinking

Claude는 답하기 전에 "생각하는 과정"을 받아볼 수 있습니다. 복잡한 계산·계획에 정확도가 올라갑니다. Converse에서는 additionalModelRequestFields로 켭니다 — 모델 전용 옵션은 여기로 들어갑니다.

step10_thinking.py

resp = runtime.converse_stream(
    modelId="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    messages=[{"role": "user", "content": [{"text": "17 * 23을 계산하고 검산까지 해줘."}]}],
    inferenceConfig={"maxTokens": 3000},          # ← thinking budget보다 커야 한다
    additionalModelRequestFields={"thinking": {"type": "enabled", "budget_tokens": 1024}},
)
mode = None
for ev in resp["stream"]:
    d = ev.get("contentBlockDelta", {}).get("delta", {})
    if "reasoningContent" in d:                               # 🧠 추론 블록
        if mode != "think":
            print("\n🧠 [추론]", end=" "); mode = "think"
        print(d["reasoningContent"].get("text", ""), end="")
    elif "text" in d:                                         # 💬 답변 블록
        if mode != "text":
            print("\n\n💬 [답변]", end=" "); mode = "text"
        print(d["text"], end="")

$ python step10_thinking.py

🧠 [추론] 17 * 23을 계산하겠습니다.

17 * 23
= 17 * 20 + 17 * 3
= 340 + 51
= 391

검산을 위해 다른 방법으로도 계산해보겠습니다.

방법 2:
23 * 17
= 23 * 10 + 23 * 7
= 230 + 161
= 391

또는 나눗셈으로 검산:
391 ÷ 17 = 23 ✓
391 ÷ 23 = 17 ✓

💬 [답변] # 17 × 23 계산

## 계산 과정
    23
  × 17
  ----
   161  (23 × 7)
  230   (23 × 10)
  ----
   391
...
**답: 391**

content에 text 말고 reasoningContent 라는 새 블록 종류가 생겼습니다. 2장에서 "content는 블록 배열"이라고 강조한 이유가 하나 더 늘었습니다.

처음 켰을 때 연달아 두 번 거부당했습니다. 실제 에러 메시지입니다.

ValidationException: `temperature` may only be set to 1 when thinking is enabled.
ValidationException: `max_tokens` must be greater than `thinking.budget_tokens`.

두 번째를 아슬아슬하게 맞추면 추론이 출력 예산을 다 먹고 답변이 0자로 잘립니다. stopReason=max_tokens인데 텍스트가 비어 있으면 이 경우입니다. 3장에서 stopReason을 보라고 한 이유가 또 나옵니다.

🔧 11. FastAPI + SSE로 감싸기 — 백엔드의 씨앗

지금까지는 스크립트였습니다. 이걸 HTTP로 감싸면 터미널이든 모바일 앱이든 붙일 수 있습니다. 스트리밍 전송은 SSE(Server-Sent Events) 를 씁니다. data: {...}\n\n 형식으로 이벤트를 흘려보내는 단순한 HTTP 규격입니다.

step11_server.py (핵심만)

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel

app = FastAPI()
class Ask(BaseModel):
    text: str

def sse(obj) -> str:                       # SSE 프레이밍: "data: {...}\n\n"
    return f"data: {json.dumps(obj, ensure_ascii=False)}\n\n"

@app.post("/chat")
def chat(body: Ask):
    def gen():
        resp = runtime.converse_stream(
            modelId=MODEL,
            messages=[{"role": "user", "content": [{"text": body.text}]}],
            inferenceConfig={"maxTokens": 500})
        for ev in resp["stream"]:                        # 6장의 이벤트를 그대로 중계
            if "contentBlockDelta" in ev:
                t = ev["contentBlockDelta"]["delta"].get("text")
                if t:
                    yield sse({"type": "text", "text": t})
            elif "metadata" in ev:
                yield sse({"type": "usage", "usage": ev["metadata"]["usage"]})
        yield sse({"type": "done"})
    return StreamingResponse(gen(), media_type="text/event-stream")

uvicorn step11_server:app --port 8599
curl -sN -X POST http://127.0.0.1:8599/chat \
  -H 'Content-Type: application/json' -d '{"text":"SSE가 뭔지 두 문장으로 설명해줘."}'

data: {"type": "text", "text": "#"}

data: {"type": "text", "text": " SSE ("}

data: {"type": "text", "text": "Server-Sent Events)"}

data: {"type": "text", "text": "\n\nSSE는 서"}

data: {"type": "text", "text": "버에"}

data: {"type": "text", "text": "서 클"}

data: {"type": "text", "text": "라이언트로"}

data: {"type": "text", "text": " 실시간 데이터"}
...
data: {"type": "text", "text": "."}

data: {"type": "usage", "usage": {"inputTokens": 29, "outputTokens": 145, "totalTokens": 174}}

data: {"type": "done"}

curl -N(버퍼링 끄기)으로 글자가 실시간으로 떨어지는 걸 처음 봤을 때 "이제 앱이 되겠다" 싶었습니다. data: 한 줄이 이벤트 하나이고, 빈 줄이 이벤트의 끝입니다. 조각이 "서", "버에", "서 클"처럼 어절 중간에서 잘리는 것도 그대로 보입니다 — 6장에서 말한 "청크 크기는 보장되지 않는다"가 HTTP 위에서도 그대로입니다.

왜 WebSocket이 아니고 SSE인가?

챗봇은 "질문 한 번, 응답 스트림 한 번"이라 단방향으로 충분합니다. 그리고 HTTP라서 curl로 디버깅되는 게 실무에서 생각보다 큰 장점이었습니다.

여기까지가 개인 챗봇 백엔드의 최소 형태입니다. 실제로 SeanChat은 이 구조를 그대로 키워서 CLI와 iOS 앱이 같은 백엔드에 붙는 형태로 쓰고 있습니다. 다만 이 코드를 그대로 EC2에 올리면 몇 가지 문제가 생기는데(60초 넘는 추론에서 ALB가 끊음, 스트림 중 끊기면 재시도 안 됨 등), 그건 3편에서 다룹니다.

⚠️ 첫날 만나는 에러 모음

이 글을 쓰면서 실제로 만난 에러를 한 곳에 모았습니다. 전부 실제 메시지입니다. Bedrock 에러는 크게 세 부류로 나뉘고, 예외 클래스 이름만 봐도 어디를 봐야 하는지 정해집니다.

4번은 처음엔 목록에 없었는데, 4장의 토큰 실험에서 빈 문자열의 토큰 수를 재보려다 만났습니다. 실제 서비스에서는 사용자가 빈 메시지를 보내는 일이 흔해서, 서버 입구에서 걸러두는 게 좋습니다.

AccessDeniedException이 났을 때 — 어디가 문제인지 구분하기

AccessDeniedException은 ①IAM 권한 없음 ②모델 액세스(구독) 안 켬 ③그 모델이 그 기능을 미지원 — 세 경우에 똑같이 뜹니다. 2번 에러처럼 메시지에 액션이 적혀 있으면 ①이고, 그렇지 않으면 컨트롤 플레인에 물어보면 구분됩니다(조회는 무료).

aws bedrock get-foundation-model-availability \
  --model-id anthropic.claude-haiku-4-5-20251001-v1:0 --region us-east-2

{
    "modelId": "anthropic.claude-haiku-4-5-20251001-v1",
    "agreementAvailability": { "status": "AVAILABLE" },
    "authorizationStatus": "AUTHORIZED",
    "entitlementAvailability": "AVAILABLE",
    "regionAvailability": "AVAILABLE"
}

넷이 다 AVAILABLE/AUTHORIZED인데도 AccessDenied가 나면 그 기능(캐싱 등)을 그 모델이 지원하지 않는 것입니다(9장 마지막 항목).

📎 정리 — 이번 편에서 만든 것

step2_converse.py     첫 호출 + 응답 구조 해부 (26 in / 22 out / 650ms)
step3_params.py       maxTokens·stopSequences·temperature 체감 (stopReason 3종)
step4_tokens.py       토큰 실측 — 영어 4.45자/토큰 vs 한글 0.78자/토큰
step5_system.py       시스템 프롬프트
step6_stream.py       converse_stream 이벤트 5종
step7_chat.py         멀티턴 — messages 배열이 대화 기억의 전부 (in 55 → 112)
step8_tool.py         도구 호출 루프 (tool_use → toolResult → end_turn)
step9_cache.py        프롬프트 캐싱 (input 8,214 → read 8,188) + 최소 토큰 실측
step10_thinking.py    Extended Thinking (reasoningContent)
step11_server.py      FastAPI + SSE 백엔드

파일 10개, 전부 합쳐 250줄(주석·빈 줄 빼면 213줄)입니다. 프레임워크 없이도 이만큼은 됩니다.

이 글에서 꼭 가져가셨으면 하는 것 다섯 개입니다.

1. 모델 ID는 us. 접두어(추론 프로파일) — 목록에 있어도 그대로는 못 부른다
2. content는 블록 배열, stopReason이 진짜 결과 코드 — content[0]["text"]는 언젠가 터진다
3. 한글은 영어보다 토큰이 ~3배 — 시스템 프롬프트 길이를 한 번 재보자
4. 대화 기억은 내가 들고 있는 messages 배열 — 비용은 N²로 늘고, 캐싱은 한 줄로 켠다
5. 에이전트 = stopReason == "tool_use"인 동안 도는 while 루프 — 실행은 내 코드가 한다

다음 편 예고

이 글은 터미널에서 curl로 SSE가 흘러나오는 화면에서 끝났습니다. 그 화면을 보고 있으면 "이걸 폰에서 보고 싶다"는 생각이 먼저 듭니다. 2편은 그래서 iPhone 앱입니다 — Xcode 새 프로젝트 만들기부터 SwiftUI 채팅 화면, URLSession.bytes(for:) 두 줄로 끝나는 SSE 파싱, 서버 주소 설정 화면, 실기기 설치까지 Swift 약 260줄로 따라갑니다. Swift를 처음 보는 분도 따라올 수 있게 파일 단위로 그대로 실을 예정입니다.

원래 2편으로 예고했던 운영 이슈들 — botocore 타임아웃 기본값(60초)이 스트리밍에 맞지 않는 이유, retries 설정이 스트림 소비 중에는 동작하지 않는 것, ALB idle timeout, 모델마다 다른 파라미터 지원 — 은 앱을 실제로 매일 써야 만나는 것들이라 3편으로 미뤘습니다. 먼저 쓸 수 있는 물건을 만들고, 그다음에 운영 이야기를 하는 게 순서에 맞겠다고 판단했습니다.

이 글의 내용은 개인 AWS 계정에서 개인적으로 실험한 결과이며, 모든 의견은 제 개인 의견입니다. 요금·모델 지원 사항은 작성 시점(2026년 9월, us-east-2) 기준입니다.

이 글에서는 AWS에서 제공하는 Landing Zone Accelerator (LZA)를 활용하여 Control Tower 및 AWS Organizations를 구축하는 방법을 다룹니다.
LZA를 통해 조직 전체의 네트워크, 보안, 계정, 로깅 등의 구성요소를 코드 기반으로 중앙에서 통합 관리할 수 있으며, 특히 엔터프라이즈 환경에서 강력한 거버넌스를 제공합니다.

🛠️ 사전 준비 사항

• AWS Organizations Root 계정 접근 권한
• AWS CLI + CDK 환경 구성 (추가 설명)

📦 구성 요소 요약

🔧 실제 구축 순서

1. AWS Root Account로 로그인 및 Control Tower Enable

먼저 Landing Zone Accelator Code를 사용하여 Control Tower를 배포하기 위해서는 AWS Control Tower가 Enable 되어 있어야 합니다.

1) AWS Console에서 Home Region으로 사용하실 리전을 선택하고 Landing Zone을 Set up합니다.

리전 등을 설정하고 OU 명칭을 입력해줍니다. 이때 OU명칭은 나중에 변경하기 쉽지 않으니 신중히 선택해주세요.

Log Archive 및 Audit Log의 이메일의 경우 LZA 코드에서 활용됩니다. 기록하여 나중에 활용되도록 합시다.

나머지 설정의 경우 Default로 하여 Control Tower를 설정합니다. 초기 설정의 경우 약 한시간의 시간이 소요됩니다.

2. LZA GitHub Repository 복제

Landing Zone Accelator 코드 실행을 위해서는 먼저 LZA Sample Code를 Clone합니다.

git clone https://github.com/awslabs/landing-zone-accelerator-on-aws.git
cd source
yarn install # 만약 yarn install 실패 시 yarn.lock 파일 지우고 재 실행
cd packages/@aws-accelerator/installer
yarn build && yarn cdk synth

그후 yarn을 이용해 template 생성을 진행합니다. NPM 및 Yarn Install은 환경에 따라 다르므로 개인적으로 설치 및 환경변수 등록 하시면 됩니다.

맥북 기준

brew install node
npm install -g aws-cdk
npm install -g yarn

여기까지 잘 따라오셨다면, 아래와 같이 json파일이 생성된 것을 확인할 수 있습니다. 해당 파일의 경로는 아래와 같습니다.

/source/packages/@aws-accelerator/installer/cdk.out/

3. LZA template 배포(Secret 생성)

먼저 CodePipeline 수행을 위한 github personal key를 만들어줍니다.

개인 github에 로그인 후 Settings -> Developer Settings -> Personal access Token으로 이동합니다.

이후 Generate New token을 클릭하여 Token을 발행해줍니다.

이후 생성된 Personal token은 AWS환경에서 사용될 예정이므로 잘 저장해두도록 합니다.

다시 AWS 콘솔로 돌아가 AWS Secret Manager를 생성해줍니다.

AWS Secret Manager -> Secrets -> Store a new secret -> Other typs of secret -> Plaintext 선택 후 token 붙여넣기

Encryption key의 경우 그대로 두고 다음으로 넘어갑니다.

Secret Name의 경우 아래 명칭을 그대로 입력합니다.

accelerator/github-token

나머지 설정의 경우 default로 하여 설정하면 secret이 설정됩니다.

3. LZA template 배포(S3 생성 및 stack 배포)

위에 생성된 template 파일의 경우 stack생성 및 배포를 위해 활용될 예정입니다. 이 template 파일의 저장을 위해 S3를 생성합니다.

Bucket 명칭 예시 : seungwoo-lza-template
(나머지는 default로 설정합니다)

S3에 템플릿 파일을 업로드 하기 위해 aws cli를 설정합니다. (profile 설정을 하는 것을 추천드리나 이 블로그에서는 프로파일 설정 없이 진행하도록 하겠습니다)

AWS Cli access-key를 IAM으로 설정하거나 아니면 아래와 같은 방법으로 설정합니다.

IAM Identity Center 접속
Access URL 확인

해당 URL로 접속 시 로그인 페이지 확인 가능하며 기존 설정해둔 이메일로 로그인합니다.

이후 Access Key를 눌러 임시 토큰을 가이드에 따라 배포합니다.

토큰 배포

AWS CLI 설정이 완료되었다면 아까 만들었던 S3에 Template 파일을 업로드합니다.

cd source/packages/@aws-accelerator/installer
aws s3 mb s3://seungwoo-lza-template # (S3 버킷 명)
export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws s3api head-bucket --bucket seungwoo-lza-template # (S3 버킷 명) --expected-bucket-owner $ACCOUNT_ID
aws s3 cp ./cdk.out/AWSAccelerator-InstallerStack.template.json s3://seungwoo-lza-template # (S3 버킷 명)

아래와 같이 생성된 S3버킷에서 템플릿 파일 확인이 가능해야 합니다.

이제 거의 완료되었습니다. Stack을 배포해봅시다.

aws cloudformation create-stack \
--stack-name AWSAccelerator-InstallerStack \
--template-url [https://seungwoo-lza-template.s3.us-west-2.amazonaws.com/AWSAccelerator-InstallerStack.template.json] \
--parameters \
ParameterKey=RepositoryName,ParameterValue=[landing-zone-accelerator-on-aws] \
ParameterKey=RepositoryBranchName,ParameterValue=[main] \
ParameterKey=ConfigurationRepositoryLocation,ParameterValue=s3 \
ParameterKey=ManagementAccountEmail,ParameterValue=[seungwooson2709@gmail.com] \
ParameterKey=LogArchiveAccountEmail,ParameterValue=[logarchive@sean-chloe.com ]\
ParameterKey=AuditAccountEmail,ParameterValue=[audit@sean-chloe.com] \
ParameterKey=ApprovalStageNotifyEmailList,ParameterValue=[seungwooson2709@gmail.com] \
ParameterKey=EnableApprovalStage,ParameterValue=Yes \
ParameterKey=ControlTowerEnabled,ParameterValue=Yes \
--capabilities CAPABILITY_IAM

아래와 같이 Stack이 생성되면 정상적으로 수행된 것입니다.

자동적으로 Code Pipeline이 수행되며, Control 타워를 구성하게 됩니다.

✅ 정리 Landing Zone Accelerator는 단순한 VPC 템플릿 그 이상입니다. 제대로 구성하면 AWS 인프라의 표준화, 보안 정책 통제, 계정 자동화까지 가능해집니다.

LZA + Control Tower 조합은 AWS 거버넌스의 핵심입니다.

여기까지 오게 되면 기본적으로 LZA를 활용하여 AWS Control Tower를 구성할수 있게되는 기본 조건이 만족됩니다. 다음 포스트에서는 LZA 코드를 활용해 기본적인 OU / Accounts 구성 및 네트워크 구성에 대해 알아봅시다.