byteforce

CPN 한국어 자습서 · 러닝패스 2 / 4 — Building with the Claude API

API로 Claude에 접근하기

첫 요청 보내기

Making a request

이제 직접 코드를 씁니다. Jupyter 노트북에서 Anthropic Python SDK를 설치하고, API 키를 안전하게 관리하고, 클라이언트를 만들어 Claude에 첫 요청을 보낸 뒤 응답을 꺼내기까지 — 네 단계를 따라갑니다.

전체 내레이션영상 나레이션 한국어 번역 (전체)›

Stephen Grider · Anthropic 기술 스태프

지금까지 이야기를 꽤 많이 했으니, 이번에는 분위기를 바꿔 직접 코드를 조금 써 보겠습니다. Anthropic API에 간단하고 기본적인 요청을 보내는 방법을 배웁니다. 설정은 네 단계로 안내하겠습니다.

1단계에서는 Jupyter 노트북을 열고 Anthropic Python SDK와 python-dotenv 패키지를 설치합니다. 저는 미리 노트북에 주석을 달아 두어 과정을 따라가기 쉽게 했습니다. 여기 1단계에 매직 설치 명령을 추가합니다. percent, pip, install, anthropic, python-dotenv 입니다. 저처럼 Visual Studio Code 안에서 노트북을 작성하면, percent 기호에서 빨간 문법 오류가 보일 수 있습니다. 그 오류가 보여도 전혀 문제없습니다. 무시해도 됩니다. 명령을 다 쓰면 실행해 패키지를 설치합니다. 그런 다음 화면을 더 깔끔하게 보여 드리기 위해 출력을 지웁니다.

다음으로 python-dotenv 패키지로 API 키를 저장하고 불러옵니다. 참고로 API 키를 만드는 방법은 이전 강의에서 안내했습니다. 아직 키를 만들지 않았다면 이전 강의로 돌아가 그 안내를 따라 주세요. 키를 에디터 안에 저장하기 위해, 노트북과 같은 디렉터리에 아주 특별한 이름의 파일을 하나 만듭니다. 이 파일의 이름을 .env 로 짓겠습니다. 그리고 그 안에 방금 생성한 API 키를 넣습니다. 정확히 ANTHROPIC_API_KEY 라고 쓰고, 등호를 붙인 뒤, 큰따옴표 안에 키를 넣습니다.

잠깐 짚고 넘어가면, 이 파일을 만들어 키를 그 안에 두는 이유는 버전 관리를 할 때 이 파일을 무시하기 위해서입니다. 그래야 이 파일을 실수로 git에 커밋하고, 누구나 볼 수 있는 공개 저장소에 실수로 올리는 일을 막을 수 있습니다. Git이나 비슷한 버전 관리 시스템을 쓴다면, 작업을 커밋할 때마다 이 파일을 반드시 무시하도록 설정해 두세요. 이제 노트북으로 돌아와, 그 환경 변수를 안전하게 불러옵니다.

3단계에서는 Anthropic 패키지로 API 클라이언트를 만듭니다. 같은 셀에서 model 이라는 변수도 선언합니다. 이 변수는 문자열이며, Anthropic API에서 실행할 모델의 이름을 담습니다. 영상에서는 Claude 3.7 Sonnet 을 사용합니다.

마지막 단계로, 방금 만든 클라이언트로 실제 요청을 보냅니다. 다만 코드를 쓰기 전에 용어를 조금 짚어, 앞으로를 더 수월하게 만들겠습니다. 먼저 이해할 것은, Anthropic SDK의 create 함수로 Claude에 접근한다는 점입니다. 이 함수는 세 개의 키워드 인자를 받습니다. model, max_tokens, messages 입니다. model 인자는 실행할 모델의 이름으로, 앞 셀에서 미리 변수로 정의해 두었습니다.

두 번째 필수 인자는 max_tokens 입니다. Claude가 생성할 수 있는 토큰 수에 최대 예산을 정합니다. 예를 들어 max_tokens를 1000으로 넘기면, Claude가 그보다 길게 생성하려 할 때 생성이 자동으로 멈추고, 처음 생성된 1000개의 토큰을 돌려받습니다. 한 가지 짚을 점은, Claude가 이 max_tokens 수를 목표로 삼지 않는다는 것입니다. 다시 말해 Claude는 1000 토큰짜리 응답을 일부러 채우려 하지 않고, 적절하다고 판단한 응답을 그대로 씁니다. 그래서 max_tokens는 텍스트를 너무 많이 생성하지 않도록 막는 안전장치로 보는 것이 좋습니다.

마지막으로 messages 입니다. 앞으로의 영상에서 크게 다룰 부분이라 특히 집중하고 싶습니다. messages가 무엇인지 이해하려면, 조금 전 이야기한 챗 애플리케이션을 떠올려 보세요. 사용자가 Claude에 질문을 입력하면 답을 받기를 기대합니다. create 함수에 넘기는 messages는 바로 이런 주고받음을 표현합니다. 메시지에는 두 종류가 있습니다. user 메시지와 assistant 메시지입니다. user 메시지에는 Claude에 넣고 싶은 텍스트가 담깁니다. user 메시지의 content는 사용자나 개발자인 우리가 작성한 텍스트, 즉 사람이 쓴 텍스트입니다. 두 번째 종류인 assistant 메시지에는 모델이 생성해 우리에게 돌려준 텍스트가 담깁니다.

이제 첫 요청을 보내기에 충분한 지식이 쌓였으니, 먼저 요청을 보내고 messages는 뒤에서 더 다루겠습니다. 노트북의 가장 마지막 셀에서 message 변수를 선언하고, client.messages.create 의 결과를 담습니다. 방금 이야기한 인자들을 넘깁니다. model에는 model 변수를, max_tokens에는 1000을 넣습니다. 안전한 한도라고 봅니다. 그리고 입력 메시지 리스트를 넣습니다. 여기서는 user 메시지 하나만 넣고, 그 안에 Claude에 보낼 질문을 담습니다. user 메시지를 만들려면, role 이 user 이고 content 가 Claude에 보낼 실제 문자열인 딕셔너리를 만듭니다. 이번에는 Claude에 양자 컴퓨팅을 정의해 달라고, "What is quantum computing? Answer in one sentence" 정도로 물어보겠습니다. 실행하면 실제로 Claude에 접근하므로 1~2초 걸립니다.

다음 셀에서 message 변수를 출력해 결과를 봅니다. 보시면 많은 내용이 나오는데, 이 부근에 양자 컴퓨팅이 무엇인지에 대한 정의가 있습니다. 우리가 돌려받은 이 message 변수 안에서 텍스트는 꽤 깊이 중첩돼 있습니다. 우리는 보통 Claude가 생성한 텍스트만 원하고, 그 안의 다른 속성에는 별로 관심이 없을 때가 많습니다. 생성된 텍스트만 꺼내려면 message.content[0].text 라고 씁니다. 이 셀을 다시 실행하면, 이제 생성된 텍스트만 보이고 다른 것은 보이지 않습니다.

이 장에서 배우는 것What you'll learn

약 6분

노트북 환경 4단계 설정 (SDK 설치 → 키 관리 → 클라이언트 → 요청)

.env로 API 키를 안전하게 보관하고 load_dotenv()로 불러오기

create()의 세 인자 — model · max_tokens · messages

메시지의 두 역할 — user · assistant

응답 구조와 message.content[0].text로 텍스트만 꺼내기

네 단계로 환경 준비

Setting up your environment

첫 요청까지 네 단계를 거칩니다. 먼저 전체 그림을 보고, 한 단계씩 노트북에서 진행합니다.

시작하기 · 단계를 눌러 상세 보기

%pip install anthropic python-dotenv — 노트북에서 SDK와 키 관리 패키지를 한 번에 설치합니다.

.env 파일에 키를 두고 load_dotenv()로 불러옵니다. 키 발급은 이전 장에서 다뤘습니다.

Anthropic() 클라이언트를 만들어 Anthropic API에 요청을 보낼 준비를 합니다.

client.messages.create(...)로 첫 요청을 보내고, 돌아온 응답에서 텍스트만 꺼냅니다.

1단계, 노트북에 매직 설치 명령으로 SDK와 python-dotenv를 설치합니다.

의존성 설치 · 노트북 셀

%pip install anthropic python-dotenv

참고

VS Code 노트북에서 % 기호에 빨간 문법 오류 표시가 떠도 정상입니다. 매직 명령이라 그렇게 보일 뿐, 그대로 실행하면 됩니다.

2단계, 노트북과 같은 디렉터리에 .env 파일을 만들고 발급받은 키를 넣습니다.

.env 파일 · API 키 보관

ANTHROPIC_API_KEY="sk-ant-api03-XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

키를 코드에서 분리하는 이유

키를 .env에 두면 노트북 코드와 키가 분리됩니다.
버전 관리(Git)를 쓴다면 .gitignore에 .env를 추가해, 키가 담긴 파일이 커밋되지 않게 합니다.
그래야 키를 공개 저장소에 실수로 올려 누구나 보게 되는 일을 막을 수 있습니다.

그런 다음 노트북에서 환경 변수를 안전하게 불러옵니다.

환경 변수 로드 · 노트북 셀

from dotenv import load_dotenv

load_dotenv()

클라이언트와 모델

Creating a client

3단계, Anthropic 패키지로 클라이언트를 만들고, 실행할 모델 이름을 model 변수에 담습니다.

클라이언트와 모델 · 노트북 셀

from anthropic import Anthropic

client = Anthropic()   # ANTHROPIC_API_KEY 환경 변수에서 키를 읽습니다
model = "claude-sonnet-4-6"   # 영상은 Claude 3.7 Sonnet, 현행 최신 Sonnet은 claude-sonnet-4-6

모델 문자열

영상에서는 Claude 3.7 Sonnet을 사용합니다. 이 자습서는 현행 최신 Sonnet인 claude-sonnet-4-6으로 적어 두었습니다. 코드를 따라 할 때는 사용할 모델의 정확한 이름을 넣으면 됩니다.

create 함수

The create function

요청 코드를 쓰기 전에 용어를 짚습니다. Claude에는 SDK의 create 함수로 접근하며, 이 함수는 세 개의 키워드 인자를 받습니다. 아래에서 각 인자를 눌러 역할을 확인하세요.

create 함수 · 파라미터를 눌러 보세요

client.messages.create(

)

model 생성에 사용할 모델의 이름입니다. 앞 셀에서 정의한 model 변수를 그대로 넘깁니다.

messages 모델에 넣는 입력입니다. 사용자와 모델이 주고받은 메시지들의 리스트로, 각 메시지는 role과 content를 가집니다.

max_tokens는 목표가 아니라 안전장치

Claude는 max_tokens 수를 채우려 하지 않습니다. 적절하다고 판단한 길이로 응답합니다.
응답이 한도를 넘으면 생성이 멈추고, 그때까지 생성된 토큰을 돌려받습니다.
그래서 max_tokens는 텍스트가 너무 길어지지 않게 막는 상한으로 보면 됩니다.

메시지 이해하기

Understanding messages

messages는 사용자와 모델이 주고받는 대화를 표현합니다. 챗 앱을 떠올리면 쉽습니다. 사용자가 질문을 보내면 모델이 답을 돌려줍니다.

메시지 예시 · [전송]을 눌러 보세요

메시지에는 두 종류가 있습니다.

메시지 역할	담기는 내용
user	Claude에 보낼 입력입니다. 사용자나 개발자 등 사람이 작성한 텍스트가 담깁니다.
assistant	모델이 생성해 돌려준 텍스트입니다.

형태

각 메시지는 role과 content를 담은 딕셔너리입니다. role은 "user" 또는 "assistant"이고, content는 보낼 실제 문자열입니다.

첫 요청 보내기

Making your first request

마지막 단계입니다. 방금 만든 클라이언트로 첫 요청을 보냅니다. user 메시지 하나에 질문을 담아 messages 리스트로 넘깁니다.

첫 요청 · 노트북 셀

message = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "What is quantum computing? Answer in one sentence"}
    ]
)

실행하면 실제로 Claude를 호출하므로 1~2초 걸립니다.

응답 꺼내기

Extracting the response

돌아온 응답을 그대로 출력해 봅니다.

message 출력 · 노트북 셀

message

# 출력: Message 객체 (실제로는 한 줄로 나오지만 보기 좋게 정리)
Message(
    id='msg_01DMrPLrVkvabMuZNig3btyc',
    content=[TextBlock(citations=None,
        text='Quantum computing is a type of computation that leverages '
             'quantum mechanics principles like superposition and entanglement '
             'to process information using quantum bits (qubits), potentially '
             'solving certain complex problems exponentially faster than '
             'classical computers.',
        type='text')],
    model='claude-sonnet-4-6',
    role='assistant',
    stop_reason='end_turn',
    stop_sequence=None,
    type='message',
    usage=Usage(cache_creation_input_tokens=0, cache_read_input_tokens=0,
        input_tokens=16, output_tokens=47)
)

많은 정보가 있지만, 우리가 원하는 텍스트는 깊이 중첩돼 있습니다. 보통은 생성된 텍스트만 필요하므로 content의 첫 블록에서 .text를 꺼냅니다.

message.content[0].text · 노트북 셀

message.content[0].text

# 출력: 문자열
'Quantum computing is a type of computation that leverages quantum mechanics '
'principles like superposition and entanglement to process information using '
'quantum bits (qubits), potentially solving certain complex problems '
'exponentially faster than classical computers.'

응답 객체의 주요 필드는 다음과 같습니다.

필드	의미
content	생성 결과 블록의 리스트입니다. 보통 `content[0]`이 `TextBlock`이고, 그 `.text`에 생성된 문자열이 들어 있습니다.
stop_reason	생성이 멈춘 이유입니다. 자연히 끝나면 `end_turn`, max_tokens 한도에 닿으면 `max_tokens`가 됩니다.
usage	이번 요청의 입력·출력 토큰 수입니다. (`input_tokens` · `output_tokens`)

스스로 점검

Quick check

Q1max_tokens의 역할로 가장 알맞은 것은?

max_tokens는 상한일 뿐, Claude는 그 수를 목표로 삼지 않습니다. 한도를 넘기면 생성이 멈추고 그때까지의 토큰을 돌려받습니다.

Q2user 메시지의 content에는 보통 누가 쓴 텍스트가 들어갈까요?

user 메시지는 사람이 작성한 입력, assistant 메시지는 모델이 생성한 출력입니다.

Q3응답에서 생성된 텍스트만 꺼내려면?

응답의 content는 블록 리스트이고, 첫 블록(content[0])의 .text 속성에 생성된 텍스트가 있습니다.

다음 장

요청 하나는 보냈습니다. 다음은 메시지를 쌓아 대화를 이어 가는 방법입니다. → 멀티턴 대화