Agent SDK 에이전트 구성 (Configure your agent)

기준일: 2026-10-23
공식 기준: Configure your agent

개요

Agent SDK 세션은 settings 파일, 환경 변수, 세션을 시작할 때 넘기는 options 객체에서 구성을 읽습니다. 이 페이지는 options 객체를 조합하는 방법과 settings 파일·환경 변수가 무엇을 제어하는지 정리합니다. 각 옵션의 타입과 기본값은 TypeScript Options와 Python ClaudeAgentOptions 레퍼런스를 보세요.

핵심 개념

TypeScript / Python	역할
model	모델 선택(별칭 또는 전체 모델 이름)
fallbackModel / fallback_model	primary가 과부하·사용 불가일 때 쓸 백업 모델
allowedTools / allowed_tools	승인 없이 실행할 툴 목록(목록 밖 툴도 사용 가능, 권한 모드가 결정)
settingSources / setting_sources	user·project·local 중 어떤 파일 시스템 settings를 읽을지
settings	settings 파일 경로 또는 인라인 JSON(TS는 객체도 가능). 파일 시스템 settings보다 우선
env	세션을 실행하는 Claude Code 프로세스의 환경 변수
cwd	작업 디렉터리
additionalDirectories / add_dirs	작업 디렉터리 밖 파일 접근 경로 추가
maxTurns / max_turns, maxBudgetUsd / max_budget_usd	turn 수·비용 상한

상세

세션에 options 넘기기

모든 query() 호출은 options 객체(TypeScript Options, Python ClaudeAgentOptions)를 받습니다. 모든 필드는 선택이며 options 없이 시작하면 SDK 기본값으로 돕니다. 아래 예시는 프로젝트의 열린 TODO를 요약하는 읽기 전용 세션입니다.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Summarize the open TODOs in this repo",
  options: {
    model: "claude-sonnet-5",
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 8,
    cwd: "/path/to/repo",
  },
})) {
  if (message.type === "result" && message.subtype === "success" && !message.is_error) {
    console.log(message.result);
  }
}

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-5",
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=8,
        cwd="/path/to/repo",
    )

    async for message in query(
        prompt="Summarize the open TODOs in this repo",
        options=options,
    ):
        if isinstance(message, ResultMessage) and not message.is_error:
            print(message.result)

asyncio.run(main())

cwd를 내 프로젝트로 바꿔 실행하면 result 메시지가 도착할 때 TODO 요약이 출력됩니다. allowedTools는 나열한 툴을 미리 승인할 뿐이고, 목록에 없는 툴도 계속 쓸 수 있습니다. Claude가 목록 밖 툴을 호출하면 권한 모드가 실행 여부를 정합니다(Agent SDK 권한의 allow·deny 규칙 참고).

settings 파일 로드

• settingSources / setting_sources: user, project, local 중 어느 파일 시스템 소스를 읽을지 정합니다. settings 파일과 CLAUDE.md가 이 소스로 들어옵니다. []를 넘기면 user·project·local settings를 모두 끕니다.
• settings: settings 파일 경로나 인라인 JSON 문자열을 받고, TypeScript는 settings 객체도 받습니다. 어떤 형태든 user·project·local 파일 settings보다 우선하며, 이보다 높은 것은 managed policy settings뿐입니다. 전체 우선순위는 각 언어 레퍼런스의 Settings precedence 절에 있습니다.

자세한 내용은 SDK에서 Claude Code 기능 쓰기를 보세요.

모델 선택

model 옵션, settings, 환경 중 어느 것도 모델을 정하지 않으면 새 세션은 Claude Code 기본 모델로 시작합니다. 특정 모델을 고정하거나 더 빠르고 저렴한 작은 모델을 쓰려면 model을 설정합니다. 값은 모델 별칭이나 전체 모델 이름입니다.

fallbackModel(TS) / fallback_model(Python)은 백업 모델입니다. primary가 과부하이거나 사용할 수 없으면 백업으로 전환하고, 매 사용자 turn 시작 시 primary를 다시 시도하므로 장애가 지나가면 돌아옵니다. 두 언어 모두 모델 하나 또는 쉼표로 구분한 백업 목록을 받으며, 순서와 체인 상한은 모델 설정 문서의 Fallback model chains 절을 따릅니다. TypeScript에서 fallback이 model과 같으면 시작 시 오류가 납니다.

const options = {
  model: "claude-fable-5",
  fallbackModel: "claude-opus-5,claude-sonnet-5",
};

options = ClaudeAgentOptions(
    model="claude-fable-5",
    fallback_model="claude-opus-5",
)

Messages API의 temperature, top_p, max_tokens는 두 언어 모두 options 객체에 필드가 없습니다. 대신 effort 수준이나 비용 상한을 쓰고, 그 파라미터가 꼭 필요하면 Messages API를 직접 호출하세요.

환경 변수 설정

env는 세션을 실행하는 Claude Code 프로세스의 환경 변수를 정합니다. 언어마다 동작이 다릅니다.

• TypeScript: env가 하위 프로세스 환경을 대체합니다. PATH, HOME, ANTHROPIC_API_KEY 같은 상속 변수를 유지하려면 process.env를 펼쳐 넣으세요.
• Python: 상속된 환경 위에 내 값을 병합하고, 겹치면 내 값이 이깁니다.
• env를 비워 두면 두 언어 모두 내 환경을 상속합니다.

const options = {
  env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

options = ClaudeAgentOptions(
    env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},
)

넘기는 변수로 Claude Code 자체도 구성할 수 있습니다. 읽는 변수 목록은 환경 변수를 보고, API 타임아웃·stall 감지는 각 언어 레퍼런스의 Handle slow or stalled API responses 절을 따르세요.

작업 디렉터리 설정

cwd를 지정하면 그 디렉터리에서 세션이 돌고, 비워 두면 내 프로세스의 작업 디렉터리를 씁니다. 두 SDK 모두 cwd setter가 없으므로 다른 디렉터리에서 돌리려면 그 cwd로 새 세션을 시작합니다. Claude Code는 작업 디렉터리로 다음을 정합니다.

• 어떤 프로젝트의 settings·hook을 불러올지
• 세션 skill을 어디서 찾을지(Agent SDK skills)
• 저장된 세션이 어느 프로젝트에 속하는지(Session storage)

작업 디렉터리 밖 파일에 툴이 닿게 하려면 additionalDirectories(TS) / add_dirs(Python)로 경로를 추가합니다. 이 권한은 파일 접근만 주고 그 경로의 구성은 불러오지 않습니다(권한 참고).

turn 수와 비용 제한

maxTurns / max_turns와 maxBudgetUsd / max_budget_usd로 상한을 겁니다. 설정하지 않으면 둘 다 꺼져 있습니다. 상한에 닿으면 subtype이 error_max_turns 또는 error_max_budget_usd인 result 메시지로 실행이 끝나고, 그 뒤 동작은 입력 모드에 따라 다릅니다.

• 단발 query(): 상한 result를 낸 뒤 예외를 던지므로, 계속 진행하려면 루프를 try로 감쌉니다.
• Streaming input: 상한 result 뒤에도 세션이 살아 있고, max-turns는 큐에 들어온 메시지마다 다시 셉니다. 비용은 메시지 사이에 누적되어 상한에 닿은 뒤의 메시지는 같은 budget result로 끝납니다. /clear로 비용 누적을 다시 시작합니다.

0의 의미가 다릅니다.

옵션	0일 때
maxTurns / max_turns	turn 제한 없음(설정하지 않은 것과 같음)
maxBudgetUsd / max_budget_usd	CLI가 시작 시 잘못된 금액으로 거부해 세션이 돌지 않음

서브에이전트 비용을 포함한 자세한 내용은 에이전트 루프의 Turns and budget을 보세요.

세션 중 구성 변경

streaming input으로 시작한 세션은 실행 중에 모델과 권한 모드를 바꿀 수 있습니다.

• TypeScript: query()가 돌려주는 객체의 메서드
• Python: ClaudeSDKClient의 메서드(query()는 제어 메서드 없는 일반 iterator를 돌려줌)

공통 setter:

• setModel() / set_model(): 모델 전환. 인자 없이 부르면 options의 model이 아니라 Claude Code 기본 모델로 바뀝니다.
• setPermissionMode() / set_permission_mode(): 권한 모드 전환

TypeScript 전용:

• applyFlagSettings(): 런타임에 settings를 적용합니다(예: await session.applyFlagSettings({ effortLevel: "high" })). options 필드가 아니라 settings 파일 키를 받으므로, 스키마와 세션 중 반영되는 키는 TypeScript 레퍼런스를 확인하세요.
• updateSettings(): 허용 목록에 있는 키 하나를 settings 파일에 씁니다. 소스별 허용 키와 최소 버전은 TypeScript 레퍼런스에 있습니다.
  • "localSettings": 프로젝트 local settings 파일에 씁니다(예: await session.updateSettings("localSettings", { outputStyle: "Explanatory" })). 다음 요청부터 반영되고, local settings를 읽는 이후 세션에도 유지됩니다.
  • "userSettings": 이 소스가 받는 유일한 키인 effortLevel만 씁니다. 현재 모델의 기본 effort로 저장되며, 실행 중인 세션의 effort는 바뀌지 않습니다.

아래 예시는 두 turn 사이에 구성을 바꾸고 각 turn에 답한 모델을 출력합니다. TypeScript에서는 setter가 끝날 때까지 프롬프트 스트림이 두 번째 메시지를 붙잡아 두므로 두 번째 turn이 새 모델로 돕니다.

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

function userMessage(text: string): SDKUserMessage {
  return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
  startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
  yield userMessage("Reply with exactly: ready");
  await secondTurnReady;
  yield userMessage("Reply with exactly: done");
}

const session = query({
  prompt: turnPrompts(),
  options: {
    model: "claude-sonnet-5",
  },
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
  if (message.type === "assistant") {
    turnModel = message.message.model;
  } else if (message.type === "result") {
    completedTurns += 1;
    if (completedTurns === 1) {
      console.log(`First turn model: ${turnModel}`);
      await session.setModel("claude-opus-5");
      await session.setPermissionMode("acceptEdits");
      startSecondTurn();
    } else {
      console.log(`Second turn model: ${turnModel}`);
      break;
    }
  }
}

import asyncio

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

async def main():
    options = ClaudeAgentOptions(model="claude-sonnet-5")

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Reply with exactly: ready")
        first_model = ""
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                first_model = message.model

        await client.set_model("claude-opus-5")
        await client.set_permission_mode("acceptEdits")

        await client.query("Reply with exactly: done")
        second_model = ""
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                second_model = message.model

    print(f"First turn model: {first_model}")
    print(f"Second turn model: {second_model}")

asyncio.run(main())

Claude API에서는 First turn model: claude-sonnet-5, 전환 뒤 Second turn model: claude-opus-5가 출력됩니다.

모델마다 prompt cache가 따로 있어, 세션 중 모델을 바꾸면 다음 요청은 전체 대화를 캐시 없이 새 모델 요율로 다시 계산합니다(프롬프트 캐싱 참고).

기능별 옵션

이 페이지에서 다루지 않는 옵션은 TypeScript·Python 레퍼런스를 보고, 목표는 알지만 옵션을 모르겠다면 SDK에서 Claude Code 기능 쓰기의 Choose the right feature부터 보세요.

TypeScript	Python	제어 대상	문서
permissionMode	permission_mode	승인 없이 할 수 있는 일	권한
allowedTools	allowed_tools	미리 승인할 툴 호출	권한
canUseTool	can_use_tool	툴 호출 승인 콜백	승인과 사용자 입력
systemPrompt	system_prompt	에이전트 지시	시스템 프롬프트 수정
settingSources	setting_sources	파일 시스템 settings 로드	Claude Code 기능
mcpServers	mcp_servers	외부 툴 서버	MCP
agents	agents	서브에이전트 정의	서브에이전트
hooks	hooks	라이프사이클 콜백	Hooks
skills	skills	불러올 skill	Skills
plugins	plugins	불러올 플러그인	Plugins
outputFormat	output_format	구조화 출력 스키마	Structured outputs
resume	resume	저장된 세션 이어 가기	Sessions
forkSession	fork_session	세션 분기	Sessions
sessionStore	session_store	외부 세션 저장	Session storage
enableFileCheckpointing	enable_file_checkpointing	되돌릴 수 있는 파일 편집	File checkpointing
effort	effort	응답에 들이는 작업량	에이전트 루프
sandbox	sandbox	툴 실행 샌드박스	TypeScript·Python 레퍼런스, 배포 맥락은 Secure deployment

체크리스트

• 필요한 옵션만 options 객체에 넣고 나머지는 SDK 기본값에 맡겼다.
• allowedTools는 미리 승인일 뿐이며 목록 밖 툴은 권한 모드가 결정한다는 점을 반영했다.
• settingSources로 읽을 settings 범위를 정했다(격리가 필요하면 []).
• TypeScript env에 process.env를 펼쳐 넣어 PATH·인증 변수를 유지했다.
• fallbackModel이 model과 다르게 설정됐다.
• maxBudgetUsd에 0을 넣지 않았고, 단발 query()의 상한 예외를 try로 처리했다.
• 세션 중 모델 전환 시 prompt cache가 다시 계산된다는 비용을 감안했다.

다음 단계

• Quickstart로 첫 에이전트를 끝까지 실행해 봅니다.
• Examples에서 만들려는 것과 맞는 프로젝트·Cookbook 레시피를 찾습니다.
• 멀티 테넌트라면 Hosting의 Multi-tenant isolation에서 settingSources·env·cwd로 테넌트별 settings와 memory를 격리합니다.

기준일

이 문서는 2026-10-23에 공식 Configure your agent 페이지를 기준으로 작성했습니다. 옵션 타입과 기본값은 각 언어 레퍼런스를 함께 확인하세요.