02. 에이전트 정의와 실행 — 합격하는 Claude Certified Architect 자격증

에이전트 정의와 실행

에이전트를 정의한다는 것은 모델에게 역할, 사용할 도구, 행동 경계를 묶어 주는 일이다. Agent SDK에서는 이를 세 층위로 구성한다. 첫째는 ClaudeAgentOptions의 system_prompt와 도구 설정으로 하나의 메인 에이전트를 정의하는 것이고, 둘째는 agents 필드에 AgentDefinition을 등록해 메인 에이전트가 위임할 수 있는 서브에이전트를 정의하는 것이며, 셋째는 사용자 정의 도구를 인프로세스 MCP 서버로 만들어 에이전트의 능력을 확장하는 것이다. 시험은 이 세 층위를 언제 어느 것으로 풀어야 하는지를 묻는다.

서브에이전트는 작업을 격리하고 위임하기 위한 장치다. 긴 탐색이나 검색처럼 컨텍스트를 많이 소비하는 하위 작업을 별도 에이전트에게 맡기면, 그 과정의 중간 산출물이 메인 대화의 컨텍스트를 오염시키지 않고 결과만 돌아온다. agents 딕셔너리에 이름과 AgentDefinition을 등록하면 메인 에이전트가 필요할 때 해당 서브에이전트를 호출한다. 각 서브에이전트는 자체 설명과 프롬프트, 허용 도구를 가질 수 있어 권한을 좁게 가두는 데도 유리하다.

# examples/subagents.pyfrom claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinitionoptions = ClaudeAgentOptions(    model="claude-opus-4-8",    agents={        "researcher": AgentDefinition(            description="코드베이스를 탐색해 관련 파일과 근거를 수집한다",            prompt="너는 조사 담당이다. 결론만 간결히 보고하라.",            tools=["Read", "Grep", "Glob"],        ),    },)async for message in query(prompt="인증 로직이 어디서 처리되는지 조사해 줘", options=options):    print(message)

사용자 정의 도구는 tool 데코레이터로 함수를 도구로 표시하고, create_sdk_mcp_server로 묶어 인프로세스 MCP 서버를 만든다. 핵심은 인프로세스라는 점이다. 별도 프로세스를 띄우거나 표준 입출력으로 IPC를 주고받는 외부 MCP 서버와 달리, SDK MCP 서버는 같은 파이썬 프로세스 안에서 함수를 직접 호출하므로 서브프로세스 관리와 통신 오버헤드가 없다. 시험은 "외부 API 호출 없이 애플리케이션 내부 함수를 도구로 노출"하는 시나리오에서 이 인프로세스 방식을 정답으로 둔다.

# examples/inprocess_tools.pyfrom claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient@tool("add", "두 수를 더한다", {"a": float, "b": float})async def add(args):    return {"content": [{"type": "text", "text": str(args["a"] + args["b"])}]}calculator = create_sdk_mcp_server(name="calc", version="1.0.0", tools=[add])options = ClaudeAgentOptions(    mcp_servers={"calc": calculator},    allowed_tools=["mcp__calc__add"],    model="claude-opus-4-8",)

여기서 두 가지를 반드시 외워야 한다. 첫째, 도구 함수는 반드시 content 키를 가진 딕셔너리를 반환해야 한다. content는 text, image, resource_link, resource 같은 항목의 리스트이며, 오류 상황은 is_error 플래그로 표시한다. 둘째, MCP 도구의 호출 이름은 mcp__{서버이름}__{도구이름} 규칙을 따른다. 위 예시에서 서버 이름이 calc이고 도구 이름이 add이므로 allowed_tools에는 mcp__calc__add로 적는다. 이 접두어 규칙을 틀려 도구가 승인되지 않는 것이 흔한 함정이다.

실행 시점의 추론 깊이는 adaptive thinking으로 모델이 작업 난이도에 맞춰 스스로 조절한다. 과거 모델에서 쓰던 temperature, top_p, 사고 토큰 예산 같은 수치 손잡이는 최신 모델에서 제거되었으므로, 에이전트 정의에서 이런 값을 직접 지정하려는 보기는 오답으로 본다. 추론 강도는 모델의 적응적 사고에 맡기고, 개발자는 도구 구성과 권한 경계, 서브에이전트 위임 구조 설계에 집중하는 것이 올바른 접근이다.

정리

에이전트 정의는 메인 에이전트 설정, agents 필드의 AgentDefinition 서브에이전트, 인프로세스 MCP 도구 세 층위로 이루어진다.
서브에이전트는 작업을 격리해 컨텍스트 오염을 막고 권한을 좁히는 위임 장치다.
tool 데코레이터와 create_sdk_mcp_server로 만든 SDK MCP 서버는 인프로세스로 동작해 서브프로세스와 IPC 오버헤드가 없다.
사용자 정의 도구는 content 키를 가진 딕셔너리를 반환해야 하며, 호출 이름은 mcp__{서버}__{도구} 규칙을 따른다.
추론 깊이는 adaptive thinking이 자동 조절한다. temperature, top_p, 사고 토큰 예산을 지정하는 보기는 오답이다.