🎯 Strands SDK 기초

혹시 LLM API로 에이전트를 직접 만들어보신 분 계신가요? 루프를 돌리고 응답을 파싱하다 보면 에이전트마다 똑같은 기반 코드를 반복해서 짜게 됩니다. 그래서 프레임워크가 나왔는데, 이번에는 그래프와 상태 머신을 설계하는 부담이 새로 생겼죠. 그 사이 모델의 추론 능력이 크게 좋아지면서, 흐름 자체를 모델에게 맡겨도 되는 시점이 온 겁니다. 이 세 번째 접근을 AWS가 구현한 것이 오늘 다룰 Strands Agents SDK입니다.

이 슬라이드가 오늘 강의의 핵심 한 장입니다. 왼쪽을 보시면 개발자가 하는 일이 도구 등록에서 끝나고, 어떤 도구를 언제 어떤 순서로 부를지는 오른쪽의 모델이 결정합니다. 그래서 docstring과 타입 힌트가 단순한 주석이 아니라 모델이 읽는 설명서가 되는 거죠. 도구 설명을 대충 쓰면 모델이 엉뚱한 도구를 고르는 걸 직접 경험하시게 될 텐데, 그만큼 설명서의 품질이 곧 에이전트의 품질입니다.

실무 감각으로 말씀드리면, 2세대 프레임워크로 에이전트를 만들 때는 설계 문서부터 노드와 엣지를 그리는 일로 시작합니다. Strands에서는 그 자리를 필요한 도구 목록을 정리하는 일이 대신하죠. 시작 코드도 보일러플레이트 수십 줄에서 3줄로 줄어듭니다. 아래 인용이 Strands의 출발점인데, Amazon 내부 팀들이 에이전트를 운영하면서 얻은 결론입니다. 단순함이 곧 배포 속도라는 겁니다.

숫자 몇 개만 짚고 가겠습니다. 2025년에 오픈소스로 공개됐고, 월간 PyPI 다운로드가 3,400만을 넘습니다. 신생 프레임워크치고는 채택 속도가 상당히 빠른 편이죠. 그리고 중요한 포인트는 AgentCore와의 관계인데, Strands는 AgentCore의 기반 오케스트레이션 엔진이라서 로컬에서 만든 에이전트를 코드 수정 없이 관리형 런타임으로 올릴 수 있습니다. 핵심 원칙 세 가지 중에서는 점진적 확장을 기억해 주세요. 3줄로 시작해서 프로덕션 요구가 생길 때 Hooks를 붙여가는 방식입니다.

패키지 구조를 보시면 설계 철학이 그대로 보입니다. 코어인 strands-agents 하나만 설치해도 에이전트가 돌아가고, 나머지는 전부 선택이에요. 도구가 필요하면 tools 패키지를, 품질 측정이 필요하면 evals 패키지를 더하는 식입니다. 웹 서비스나 프론트엔드에 붙이실 분들은 TypeScript SDK도 있다는 점 참고하시고요. 오늘 다루는 범위는 코어와 tools 두 개면 충분합니다.

에이전트라고 하면 뭔가 복잡한 구조물을 상상하기 쉬운데, Strands에서는 이 세 가지가 전부입니다. 비유하자면 Model은 두뇌, Tools는 손발, System Prompt는 업무 지침서예요. 새로 온 팀원에게 지침서를 주고 필요한 도구를 쥐여주는 것과 같은 구조입니다. 이 그림 하나만 머리에 넣어두시면, 이후 파트들이 전부 이 세 요소를 하나씩 깊이 파는 심화라는 걸 아시게 됩니다.

세 요소 중에 필수가 Model 하나뿐이라는 게 재미있는 부분입니다. Tools 없이 만들면 그냥 채팅봇이 되고, System Prompt가 없으면 범용 응답을 하는 비서가 됩니다. 거꾸로 말하면, 이미 갖고 계신 채팅봇에 도구만 더하면 에이전트가 된다는 뜻이기도 하죠. 각 요소는 뒤 파트에서 깊이 다루니까, 여기서는 역할 구분만 잡고 넘어가시면 됩니다.

코드에서 주목하실 부분은 교체 비용입니다. 프로덕션에서는 IAM 인증을 쓰는 BedrockModel을 권장하고, 로컬 개발로 전환할 때는 주석 처리된 두 줄처럼 Ollama로 바꾸면 끝이에요. 모델을 바꿔도 tools와 system_prompt 쪽 코드는 한 글자도 안 바뀝니다. 회사의 모델 정책이 바뀌어도 에이전트 로직을 다시 짤 필요가 없다는 건 실무에서 꽤 큰 장점입니다.

여기서 많은 분들이 놀라시는데, 도구를 만드는 데 별도의 클래스나 스키마 정의가 없습니다. 평범한 Python 함수에 @tool 하나 붙이면 끝이에요. 대신 docstring이 모델에게 그대로 전달되기 때문에, 함수 설명을 사람 동료에게 인수인계하듯 구체적으로 쓰는 습관이 중요합니다. tools 리스트에 담는 순간 모델의 선택지가 되는 거고요. 도구 이야기는 PART 4에서 본격적으로 이어가겠습니다.

시스템 프롬프트는 셋 중에 가장 저평가되는 요소인데, 사실 가장 강력한 행동 제어 수단입니다. 예시의 규칙 섹션을 보시면 도구 사용 조건을 문장으로 통제하고 있죠. 추측 금지, 데이터가 없으면 확인 불가로 답하라 — 이런 문장 하나가 근거 없는 답변을 실질적으로 줄여줍니다. 에이전트가 이상하게 동작할 때는 코드보다 시스템 프롬프트를 먼저 의심해 보시길 권합니다.

앞서 본 세 구성요소를 실제로 조립하면 이 코드가 됩니다. 임포트를 빼면 실질적인 코드는 Agent 생성과 호출뿐이에요. 그런데 마지막 줄에서 질문을 넘기는 순간 무슨 일이 벌어질까요? 모델이 http_request 도구로 GitHub API를 부르고, 결과를 관찰하고, 답할지 더 조회할지 스스로 판단합니다. 이 반복 과정이 바로 다음 파트의 주제, 에이전틱 루프입니다.

루프는 이 세 단계의 반복입니다. 사람이 일하는 방식과 똑같다고 보시면 돼요. 상황을 파악하고, 행동하고, 결과를 확인해서 다음을 정하는 겁니다. 중요한 건 이 사이클을 몇 번 돌지 개발자가 미리 정하지 않는다는 점입니다. 목표가 달성됐다고 모델이 판단할 때까지 돌아갑니다.

이 그림에서 Agent가 가운데 허브라는 점을 봐주세요. 모델이 도구를 직접 실행하는 게 아닙니다. 모델은 어떤 도구를 쓰겠다는 결정만 반환하고, 실제 실행은 Agent가 맡습니다. 그래서 도구 실행 앞뒤에 검증이나 로깅을 끼워 넣을 수 있는 거고, 잠시 뒤에 볼 Hooks가 걸리는 지점도 바로 이 허브입니다. 점선 박스 안이 agent 호출 한 번 안에서 벌어지는 일 전체입니다.

이번에는 실제 시간 순서로 따라가 보시죠. 첫 회전에서 모델이 tool_use를 반환하면 Agent가 도구를 실행하고, 그 결과를 대화에 추가해서 다시 모델에게 보냅니다. 두 번째 회전에서 모델이 도구 호출 없이 텍스트로만 답하면 그게 곧 종료 신호예요. 별도의 종료 API가 있는 게 아니라, 응답의 형태 자체가 계속과 종료를 구분한다는 게 포인트입니다.

그럼 모델이 계속 도구만 부르면 어떻게 될까요? 이럴 때를 위해 limits 파라미터가 내장되어 있습니다. 호출할 때 turns, output_tokens, total_tokens 예산을 지정하면 각 루프 반복이 시작될 때 검사해서, 초과하면 limit_turns 같은 stop_reason으로 대화 상태를 보존한 채 종료됩니다. 보조 수단도 두 가지 있는데요, 훅에서 cancel_tool로 도구 실행을 차단하면 그 사유가 모델에 전달되어 모델이 마무리 응답을 하고, 사용자 취소나 타임아웃 같은 외부 신호는 agent.cancel()로 처리합니다. 프로덕션에서는 비용 방어선으로 limits를 기본으로 걸어두시는 걸 권합니다.

도구를 확보하는 경로는 세 가지입니다. 사내 API처럼 우리 회사에만 있는 기능은 @tool로 직접 만들고, 파일 읽기나 HTTP 호출처럼 흔한 기능은 카테고리별 빌트인에서 가져다 쓰고, 이미 MCP 서버로 공개된 기능은 MCPClient로 연결합니다. 실무에서는 세 경로를 섞어 쓰게 되는데, 새 도구를 만들기 전에 빌트인과 MCP 생태계부터 검색해 보시는 게 시간을 아끼는 길입니다. 이제 하나씩 코드로 보겠습니다.

아까 잠깐 본 @tool을 이번엔 자세히 뜯어보겠습니다. 타입 힌트에서 파라미터 스키마가 자동 생성되니까, unit처럼 기본값이 있는 선택 파라미터도 그대로 표현됩니다. docstring에는 언제 호출해야 하는지, 파라미터 예시, 반환 형태까지 적어주는 게 좋아요. 모델 입장에서는 이 문서가 도구에 대해 아는 전부거든요. 도구 선택이 자꾸 어긋난다면 코드가 아니라 docstring을 다듬는 게 정답인 경우가 많습니다.

직접 만들기 전에 여기 있는지 먼저 확인하세요. 빌트인 도구의 공급원은 두 갈래인데, bash나 file_editor, http_request 같은 핵심 6종은 SDK 코어에 동봉되어 있어서 tools 패키지를 설치하지 않아도 바로 쓸 수 있고, 그 밖의 카테고리별 확장 도구는 strands-agents-tools 패키지에서 import 한 줄이면 바로 씁니다. 특히 use_aws는 AWS CLI를 래핑해서 에이전트가 AWS 리소스를 직접 다루게 해주니까 AWS 환경에서는 활용도가 높습니다. 다만 shell이나 python_repl처럼 강력한 도구는 에이전트에게 실행 권한을 주는 셈이라는 점을 기억하세요. 프로덕션에서는 꼭 필요한 도구만 골라 넣는 최소 권한 원칙이 안전합니다.

마지막 경로는 외부 연결입니다. MCP는 도구를 표준 프로토콜로 노출하는 방식이라, 이미 공개된 MCP 서버가 있다면 코드 몇 줄로 그 서버의 도구 전체를 가져올 수 있습니다. 예시는 npx로 파일시스템 MCP 서버를 띄워 연결하는 코드인데요, with 블록이 연결 수명을 관리하니까 도구 사용은 반드시 블록 안에서 해야 합니다. list_tools_sync()가 서버의 도구 목록을 받아 Agent에 등록해 주고요. 서버에 우리 클라이언트를 알리고 싶으면 client_name 파라미터를 지정할 수 있고, 연결할 서버가 여럿이면 mcpServers JSON 설정을 통째로 읽어 서버당 MCPClient를 만들어 주는 load_servers()도 보조로 제공됩니다. 사내에 이미 MCP 서버를 운영 중이시라면, Strands 에이전트에 그대로 꽂을 수 있다는 뜻입니다.

본격적으로 들어가기 전에 큰 그림을 한 장으로 잡고 시작하겠습니다. 메시지는 하나예요. 모델을 바꿔도 Agent 코드는 그대로라는 겁니다. 공식 15종 프로바이더 중 기본은 BedrockModel이고, 개발 단계에서는 무료인 Ollama로 돌리다가 프로덕션에서 Bedrock으로 넘어가는 조합이 흔합니다. 이제 전체 목록부터 표로 보시죠.

표가 길지만 메시지는 하나입니다. Agent 코드는 그대로 두고 모델만 갈아 끼운다는 거죠. 개발 단계에서는 무료인 Ollama 로컬 모델로 돌리고 프로덕션은 Bedrock으로 가는 조합이 흔한 패턴입니다. 표에서 두 가지만 주의하시면 되는데, 최근 추가된 Amazon Nova는 Python 전용이고, 반대로 Vercel은 TypeScript SDK 전용입니다. 공식 15종 밖에도 Cohere나 vLLM 같은 커뮤니티 연동이 10종 있고, 표에 없는 모델이라도 LiteLLM 프록시를 거치면 100개 이상 연결됩니다.

기본 프로바이더인 BedrockModel 설정을 보겠습니다. 가장 흔한 실수가 model_id인데, 파운데이션 모델 ARN이 아니라 추론 프로파일 ID를 넣어야 합니다. us. 접두어가 붙으면 크로스 리전 추론 프로파일이라 트래픽이 여러 리전으로 분산되고요. temperature는 에이전트 용도라면 낮게 잡아서 도구 선택이 결정적으로 나오게 하는 편이 안정적입니다. 어떤 설정을 하든 Agent에는 model 인자 하나로 들어간다는 구조는 동일합니다.

에이전트의 답을 사람이 아니라 코드가 받아야 할 때가 있죠. 자유 텍스트를 정규식으로 파싱하는 대신, Pydantic 클래스로 스키마를 선언하고 structured_output_model로 넘기면 됩니다. 클래스 필드 선언이 그대로 JSON Schema로 변환되어 모델에 전달되고, 결과는 타입 있는 Python 객체로 돌아옵니다. 에이전트를 파이프라인의 한 단계로 쓰거나 다른 시스템과 연동할 때 사실상 필수 기능이고요. 특정 모델 전용이 아니라 프로바이더 공통으로 동작한다는 점도 기억해 주세요.

마지막 파트입니다. 네 프레임워크는 우열이 아니라 설계 철학의 차이로 갈립니다. 코드 레벨 제어가 필요 없다면 완전 관리형인 Bedrock Agents, 그래프 설계가 핵심이면 LangGraph, 역할 기반의 빠른 프로토타입이면 CrewAI, 프로덕션 에이전트를 직접 빌드한다면 Strands입니다. 이제 여섯 개 축으로 나란히 놓고 비교해 보겠습니다.

어느 하나가 정답이라기보다, 설계 철학이 다른 네 가지 선택지입니다. 표에서 배포 행을 봐주세요. LangGraph와 CrewAI는 배포 인프라를 직접 관리해야 하는 반면, Strands는 Lambda, Fargate, AgentCore까지 AWS 배포 경로가 열려 있습니다. 반대편 극단인 Bedrock Agents는 완전 관리형이라 편하지만 커스터마이징이 제한되고요. 여러분 팀이라면 이 여섯 개 축 중에 어느 것을 가장 중요하게 보시겠어요? 그 답에 따라 선택이 달라집니다.

방금 그 질문을 순서도로 만들면 이렇게 됩니다. 첫 분기가 가장 중요한데, 코드 레벨 제어가 필요 없다면 고민할 것 없이 Bedrock Agents로 운영 부담을 없애는 게 낫습니다. 제어가 필요하다면 그다음은 워크플로우의 성격이에요. 복잡한 조건부 분기가 핵심이면 LangGraph, 역할 기반의 빠른 프로토타입이면 CrewAI, 그리고 프로덕션 에이전트를 직접 빌드하는 일반적인 경우가 Strands입니다. 지금 진행 중인 프로젝트를 이 트리에 한번 대입해 보시죠.

마무리하면서 Strands의 설계 결정 세 가지를 정리하겠습니다. 첫째, 추상화를 최소로 유지해서 디버깅할 때 프레임워크 내부를 파고들 일이 적습니다. 둘째, 프로바이더 독립이라 모델 선택이 벤더 계약이 아니라 코드 한 줄의 문제가 됩니다. 셋째, agentcore CLI 두 명령으로 관리형 런타임까지 가는 배포 경로가 SDK에 내장되어 있습니다. 오늘 내용을 한 문장으로 줄이면, Agent, Tool, Model 세 가지로 시작해서 프로덕션까지 가는 SDK라고 기억해 주시면 됩니다.