제로에서 에이전트까지 (Part‑I)
I’m happy to translate the article for you, but I’ll need the text you’d like translated. Could you please paste the content (or the portion you want translated) here? Once I have the text, I’ll keep the source line unchanged and translate the rest into Korean while preserving all formatting.
Step 1: 클라우드에서 첫 번째 Strands 에이전트
파이썬 몇 줄만으로 Amazon Bedrock에서 Claude Sonnet 4를 백엔드로 하는 에이전트를 실행할 수 있습니다:
from strands import Agent
agent = Agent(
system_prompt="You are a helpful assistant that provides concise responses."
)
agent("Tell me a joke.")프로비저닝할 인프라가 없습니다. 구성할 API 게이트웨이도 없습니다.
기본 모델 제공자는 Amazon Bedrock이며, 기본 모델은 현재 AWS 리전의 Claude Sonnet 4입니다. 여기서 strands‑agents‑tools 패키지의 내장 도구(예: calculator)와 @tool으로 데코레이트한 사용자 정의 도구를 추가할 수 있습니다. 도구를 직접 호출(agent.tool.calculator(...))하고, 로깅을 설정하며, BedrockModel을 통해 모델 제공자를 교체하거나 추론 파라미터를 조정할 수도 있습니다.
아래는 DuckDuckGo 웹 검색을 도구로 사용하는 요리 도우미 RecipeBot을 50줄 미만의 코드로 구축하는 예시입니다.
import warnings
warnings.filterwarnings(action="ignore", message=r"datetime.datetime.utcnow")
from strands import Agent
# Initialise your agent
agent = Agent(
model="us.anthropic.claude-sonnet-4-5-20250929-v1:0", # optional: specify the model ID
system_prompt="You are a helpful assistant that provides concise responses."
)
# Send a message to the agent
response = agent("Hello! Tell me a joke.")핵심 요점 – Strands 에이전트는 전체 요청‑응답‑도구 루프를 추상화합니다. 에이전트가 무엇을 해야 하는지에 집중하고, 어떻게 API 호출을 연결할지는 신경 쓰지 않아도 됩니다. Bedrock에서 작동하는 에이전트를 만들기 위해 Strands가 필요한 것은 세 줄뿐입니다.
단계 2: 로컬 머신에서 개인 에이전트 어시스턴트
모든 사용 사례가 클라우드 엔드포인트를 이용해야 하는 것은 아닙니다. 이 단계에서는 Strands의 OllamaModel 제공자를 사용해 Amazon Bedrock을 Ollama(로컬 LLM 런타임)으로 교체하는 방법을 보여줍니다. 에이전트는 완전히 로컬 머신에서 실행되며, 모든 데이터가 로컬에 보관됩니다.
from strands import Agent
from strands.models.ollama import OllamaModel
ollama_model = OllamaModel(
model_id="llama3.2:3b",
host="http://localhost:11434",
temperature=0.7,
)
# Example tools (you would define these elsewhere)
tools = [file_read, file_write, list_directory]
agent = Agent(model=ollama_model, tools=tools)사용 사례는 로컬 파일 작업 어시스턴트입니다: 파일 읽기(PDF 포함), 파일 쓰기, 디렉터리 내용 나열. 에이전트는 주주 서한을 요약하거나 README를 초안으로 만들거나, 여러분을 대신해 파일을 생성할 수 있으며, 모두 로컬에서 실행되는 3 B 파라미터 모델에 의해 구동됩니다.
핵심 요점 – Strands 모델 제공자 추상화는 실제로 이식성이 뛰어납니다. Claude on Bedrock에서 Ollama의 Llama로 전환하는 것이 한 줄의 코드 변경으로 가능하므로, 오프라인 시나리오, 프라이버시‑민감 작업, 비용‑최적화 개발에 큰 의미가 있습니다.
단계 3: 에이전트를 AWS 서비스에 연결하기
여기서 실제로 유용해집니다. 예제는 두 개의 AWS 관리형 서비스에 연결되는 Restaurant Assistant를 구축합니다:
- Amazon Bedrock Knowledge Base – 레스토랑 메뉴에 대한 RAG.
- Amazon DynamoDB – 예약 관리.
이 단계에서는 도구를 정의하는 세 가지 방법을 보여줍니다:
@tool데코레이터를 사용한 인라인 – 에이전트 코드 옆에 함수를 정의합니다.@tool데코레이터를 사용한 독립 파일 – 모듈로 가져옵니다.TOOL_SPEC사전 – Bedrock Converse‑API‑스타일 스키마로, 매개변수와 반환 형태에 대한 세밀한 제어에 유용합니다.
from strands import Agent
from strands_tools import current_time, retrieve # built‑in tools
# Custom tools (could be defined inline, imported, or via TOOL_SPEC)
# Example: get_booking_details, create_booking, delete_booking
agent = Agent(
model=model,
system_prompt=system_prompt,
tools=[
retrieve,
current_time,
get_booking_details,
create_booking,
delete_booking,
],
)내장 retrieve 도구는 KNOWLEDGE_BASE_ID 환경 변수가 설정되면 자동으로 Bedrock Knowledge Base에서 읽어옵니다—별도의 커스텀 RAG 파이프라인이 필요 없습니다.
핵심 요점 – Strands 에이전트는 커스텀 도구와 boto3 호출을 통해 모든 AWS 서비스에 연결할 수 있습니다. retrieve 내장 도구는 한 줄로 RAG를 제공하고, 필요할 때 TOOL_SPEC 패턴을 사용해 정교한 도구 계약을 정의할 수 있습니다.
Step 4: MCP Tools and Multiple Servers
Model Context Protocol (MCP) 은 AI 에이전트를 외부 도구 서버와 연결하기 위한 최신 표준입니다. 여기서는 Strands 가 MCP 서버와 어떻게 네이티브하게 통합되는지 보여줍니다. 로컬 CLI‑스타일 서버의 경우 stdio 를, 네트워크 기반 무상태 서버의 경우 Streamable HTTP 를 사용합니다.
from strands.tools.mcp import MCPClient
from mcp import StdioServerParameters, stdio_client
mcp_client = MCPClient(
lambda: stdio_client(
StdioServerParameters(
command="uvx",
args=["awslabs.aws-documentation-mcp-server@latest"]
)
)
)
with mcp_client:
tools = mcp_client.list_tools_sync()
agent = Agent(tools=tools)
agent("What is Amazon Bedrock's pricing model?")이 단계에서는 다음 내용도 다룹니다:
- FastMCP 로 직접 MCP 서버 만들기
call_tool_sync를 통한 도구 직접 호출read_timeout_seconds로 타임아웃 설정- 여러 MCP 서버 를 하나의 에이전트에 동시에 연결하기
핵심 요점 – MCP 는 도구 생태계를 플러그‑앤‑플레이 마켓플레이스로 전환합니다. AWS 문서, CDK 모범 사례, 데이터베이스, API 등 MCP‑호환 서버라면 어떤 것이든 에이전트가 별도의 glue code 없이 사용할 수 있는 도구가 됩니다. 하나의 에이전트 호출에서 여러 서버를 조합할 수 있습니다.
Step 5: 고급 응답 처리, 스트리밍 및 콜백
실제 애플리케이션은 에이전트를 호출하고 결과를 기다리는 것에 그치지 않습니다. 토큰을 스트리밍하고, 부분 결과를 렌더링하며, 이벤트를 대시보드에 파이프하고, HTTP를 통해 응답을 제공합니다. 이 단계에서는 이를 구현하기 위한 두 가지 패턴을 보여줍니다.
Method 1 — Async Iterators (stream_async)
FastAPI와 같은 비동기 프레임워크에 이상적입니다. 에이전트 이벤트가 도착할 때마다 반복합니다:
async for event in agent.stream_async("Calculate 2+2"):
if "data" in event:
print(event["data"])
if "current_tool_use" in event:
print(f"Tool: {event['current_tool_use']['name']}")이벤트는 init_event_loop, start_event_loop, message, current_tool_use, data, force_stop, result와 같은 구조화된 라이프사이클 신호를 전달합니다. 이를 통해 스트리밍 UI, 진행 표시기, 맞춤 로깅 등을 세밀하게 제어할 수 있습니다.
Method 2 — Callback Handlers
동기 컨텍스트에서는 에이전트에 callback_handler 함수를 전달합니다. 이 함수는 모든 이벤트마다 호출되어 모델 출력 및 도구 호출을 실시간으로 가로채며, async 구조로 코드를 재작성할 필요가 없습니다.
핵심 요점
stream_async와 FastAPI를 결합한 방식은 스트리밍 에이전트 API를 운영 환경에 배포할 때 권장되는 패턴입니다.- 콜백 핸들러는 스크립트, CLI, 또는 기타 동기 환경에서 가볍게 사용할 수 있는 대안입니다.
두 접근 방식 모두 에이전트의 추론 과정과 도구 사용 단계마다 가시성을 제공합니다.
계속됩니다…