개요
Strands Agents는 Python과 TypeScript에서 AI 에이전트를 빌드하고 실행하기 위한 모델 기반 오픈소스 SDK입니다. 라이프사이클 제어, 도구 호출, 구조화된 출력, MCP, 멀티 에이전트 패턴, 메모리, 세션, 스트리밍 출력, 가드레일, 트레이싱 및 평가 기능을 기본 제공하며, Bedrock, Anthropic, OpenAI, Gemini 등 다양한 모델 제공업체를 지원합니다.
README 미리보기
\n \n \n \n \n \n \n \n \n\n \n Strands Agents\n \n\n \n A model-driven approach to building AI agents in just a few lines of code.\n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n Documentation\n ◆ Samples\n ◆ MCP Server\n ◆ Discord\n \n\n\nStrands Agents is an open-source SDK for building and running AI agents in Python and TypeScript. Choose Strands when you would otherwise write your own agent loop: it runs in your process with no hosted control plane, and it covers the jobs a hand-rolled loop grows into. In one SDK you get [lifecycle controls](https://strandsagents.com/docs/user-guide/concepts/agents/agent-loop/) (turn limits, token budgets, cancellation, stop reasons), [tools](https://strandsagents.com/docs/user-guide/concepts/tools/) and [structured output](https://strandsagents.com/docs/user-guide/concepts/agents/structured-output/), [MCP](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/), [multi-agent patterns](https://strandsagents.com/docs/user-guide/concepts/multi-agent/multi-agent-patterns/), [memory](https://strandsagents.com/docs/user-guide/concepts/memory/overview/) and [sessions](https://strandsagents.com/docs/user-guide/concepts/agents/session-management/), [model portability](https://strandsagents.com/docs/user-guide/concepts/model-providers/), [streaming](https://strandsagents.com/docs/user-guide/concepts/streaming/), [guardrails](https://strandsagents.com/docs/user-guide/safety-security/guardrails/), [tracing](https://strandsagents.com/docs/user-guide/observability-evaluation/observability/), and [evals](https://strandsagents.com/docs/user-guide/evals-sdk/quickstart/).\n\nThis monorepo contains Strands harness, the Python and TypeScript SDKs, the documentation site, and supporting packages:\n\n| Directory | Description |\n|-----------|-------------|\n| [`harness-py/`](harness-py/) | Python Strands harness: fully assembled agent via `create_harne
FAQ (5)
문제 해결Strands Agent를 다른 에이전트 내부에서 도구로 사용할 때 출력이 뒤섞이거나 중복되는 문제를 어떻게 해결하나요?
서브 에이전트에 callback_handler=None을 설정하면 해당 에이전트의 토큰 스트림이 오케스트레이터의 출력 채널을 통해 내보내지지 않습니다. 서브 에이전트는 여전히 실행되어 결과를 반환하지만, 최종 응답은 부모/오케스트레이터만 스트리밍합니다.
sub_agent = Agent(
model=model,
system_prompt="You are a news fetcher.",
tools=[some_tool],
callback_handler=None # Required when this agent is used as a tool
)
@tool(name="live_news", description="Fetches latest news")
def live_news(input: str) -> str:
result = sub_agent(input)
return str(result) # Clean text returned to the orchestrator
orchestrator = Agent(
model=model,
system_prompt="You are Jarvis.",
tools=[live_news]
)오케스트레이터의 최종 출력까지 억제하려는 경우가 아니라면 오케스트레이터의 콜백 핸들러를 비활성화하지 마세요. TypeScript 커스텀 에이전트 래퍼에서는 중첩된 에이전트에 printer: false를 설정하는 것이 이에 해당합니다.
문제 해결Strands MCPClient에서 'Unsupported protocol version from the server: 2026-07-28' 오류를 해결하는 방법
strands-agents를 버전 1.55.0 이상으로 업그레이드하세요: pip install -U strands-agents. 이전 릴리스는 mcp>=1.23.0,<2.0.0으로 고정되어 있었고 레거시 ClientSession.initialize() 핸드셰이크를 사용했으며, 이 핸드셰이크는 최신 2026-07-28 프로토콜을 협상하는 서버(예: supportedVersions=["2026-07-28"]를 사용하는 AWS Bedrock AgentCore Gateway)를 거부합니다. v1.55.0에서는 종속성 범위가 mcp 2.x를 허용하며, MCPClient가 negotiate_session을 통해 연결되어 mcp 2.x에서는 최신 프로토콜을 협상하고 이전 서버에 대해서는 레거시 핸드셰이크로 투명하게 폴백합니다.
문제 해결Strands OpenAIModel이 chat 모드에서 OpenRouter를 사용할 때 토큰 사용량이 0으로 보고되는 이유는 무엇인가요?
OpenRouter는 choices[0].finish_reason이 포함된 마지막 스트림 청크에서 usage 객체를 전송합니다. Strands TypeScript SDK 1.19.0에서는 _streamChat이 choices 배열이 비어 있는 청크에서만 usage를 읽기 때문에, 해당 마지막 청크가 누락되고 agent.metrics.accumulatedUsage는 { inputTokens: 0, outputTokens: 0, totalTokens: 0 } 상태로 남게 됩니다.
즉시 해결 방법: 대신 Responses API를 사용하세요:
new OpenAIModel({
api: 'responses',
modelId: 'openai/gpt-6-luna',
apiKey: process.env.OPENROUTER_API_KEY,
clientConfig: { baseURL: 'https://openrouter.ai/api/v1' },
})코드 수정: _streamChat에서 choices가 비어 있는지 확인하기 전에 모든 청크에서 chunk.usage를 읽으세요:
if (chunk.usage) {
bufferedUsage = chunk.usage
}
if (!chunk.choices || chunk.choices.length === 0) {
continue
}가능한 경우 fix(openai): read chat usage reported on the finish_reason chunk 수정이 포함된 Strands 릴리스로 업그레이드하세요.
문제 해결I can't verify the specifics here — I don't have information about a model called Claude Haiku 5.5 (it may be newer than my knowledge cutoff, or you might be thinking of a different version like Haiku 4.5), and I don't know Strands' exact context window configuration for it.
That said, common reasons an agent framework might default to 200k even when a larger window exists:
- **Opt-in beta features**: Larger context windows are sometimes gated behind beta headers or explicit parameters, which frameworks often don't enable by default.
- **Pricing tiers**: Some models charge premium rates for requests beyond 200k tokens, so frameworks cap the default to avoid surprising costs.
- **Conservative defaults**: Agent SDKs tend to pick safe limits to manage cost, latency, and memory, letting users override them.
- **Stale configuration**: The SDK's model metadata may simply not have been updated to reflect a newer limit.
For the definitive answer, I'd check the Strands Agents source code (the model provider configuration for Anthropic/Bedrock), their GitHub issues, or their docs — the limit is likely a configurable default rather than a hard constraint.
Strands 1.58.1에는 Claude Haiku 5.5에 대한 컨텍스트 윈도우 매핑이 없으므로, BedrockModel.context_window_limit이 기본값인 200,000 토큰으로 폴백됩니다. 이로 인해 estimate_utilization(150000)이 0.15 대신 0.75를 반환하게 되며, 0.7 임계값 기준으로 700k가 아닌 약 140k 토큰에서 선제적 요약이 트리거될 수 있습니다.
즉시 적용 가능한 해결 방법: 제한값을 명시적으로 설정하세요.
from strands.models import BedrockModel
model = BedrockModel(
model_id="eu.anthropic.claude-haiku-5-5",
region_name="eu-west-2",
context_window_limit=1_000_000,
)global.anthropic.claude-haiku-5-5에도 동일한 값을 사용하세요. 영구적인 해결책은 PR #4998이 포함된 Strands 릴리스로 업그레이드하는 것이며, 해당 PR은 anthropic.claude-haiku-5-5 및 claude-haiku-5-5에 대한 1,000,000 토큰 항목을 Python과 TypeScript 기본값 모두에 추가합니다.
문제 해결AWS_REGION이 설정되지 않았을 때 Strands CLI Bedrock 모델 목록이 비어 있는 이유는 무엇인가요?
이 문제는 @strands-agents/cli 0.1.0에서 발생합니다. STS 자격 증명 검증은 us-east-1로 폴백되는 반면, Bedrock 모델 검색은 확인된 리전이 없으면 리전을 생략하기 때문에, 카탈로그 요청이 조용히 실패하고 모델이 하나도 반환되지 않습니다.
즉각적인 해결 방법: CLI를 시작하기 전에 리전을 설정하세요:
export AWS_REGION=us-east-1
strands
또는 config.json에서 providers.environment.AWS_REGION을 Bedrock 모델을 사용할 수 있는 리전으로 설정하세요.
이 수정 사항은 PR #4581(커밋 9b7657f1)을 통해 main에서 제공됩니다. 이제 awsClientConfiguration은 일관된 우선순위로 리전을 확인합니다: 명시적 리전 → 프로필에서 파생된 리전 → us-east-1. 이 수정이 포함된 CLI 릴리스로 업데이트하세요. config.json이 다시 작성되어 providers.environment.AWS_REGION이 사라지는 경우, 이는 별도의 미해결 문제이므로 별도로 보고해야 합니다.