기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Step Functions를 사용하여 Amazon Bedrock AgentCore 하네스 간접 호출
Step Functions를 Amazon Bedrock AgentCore와 통합하여 상태 시스템에서 하네스를 호출할 수 있습니다. 하네스는 모델 추론, 도구 사용 및 멀티턴 대화를 오케스트레이션하는 관리형 런타임입니다. Workflow Studio에서 **AgentCore InvokeHarness**를 검색하여이 상태를 찾아 워크플로로 끕니다.
구성 패널에서 **빠른** 하네스 생성을 사용하여 새 하네스 및 실행 역할을 생성하거나 기존 하네스 ARN을 선택할 수 있습니다. 기존 하네스를 사용하는 경우 호출별로 구성을 재정의할 수 있습니다. Task 상태 정의의 값은 하네스 기본값을 재정의합니다. 사용 가능한 파라미터는 Amazon Bedrock AgentCore API 참조의 [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)를 참조하세요. * AgentCore * 하네스 실행 역할에 대한 자세한 내용은 *Amazon Bedrock AgentCore 개발자 안내서*의 [런타임 권한을](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html) 참조하세요.
**작은 정보**
에이전트 리소스에 관찰성을 추가하려면 CloudWatch 트랜잭션 검색을 활성화합니다. 자세한 내용은 *Amazon CloudWatch 사용 설명서*의 [에이전트 리소스에 관찰성 추가를 참조하세요](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AgentCore-GettingStarted.html#add-observability-agentic-resources).
Step Functions의 AWS 서비스와 통합에 대한 자세한 내용은 [ 서비스 통합](integrate-services.md) 및 섹션을 참조하세요[Step Functions의 서비스 API에 파라미터 전달](connect-parameters.md).
**최적화된 AgentCore 하네스 통합의 주요 기능**
[요청 및 응답](connect-to-resource.md#connect-default) 통합 패턴만 지원됩니다. [작업 실행(.sync)](connect-to-resource.md#connect-sync) 및 [작업 토큰을 사용하여 콜백 대기](connect-to-resource.md#connect-wait-token) 패턴은 지원되지 않습니다.
응답은 [역](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html#API_runtime_Converse_ResponseSyntax)방향 JSON 구조로 변환됩니다. 최종 어시스턴트 메시지만 반환되고 멀티턴 대화의 이전 턴은 삭제됩니다.
토큰 사용량 지표(`InputTokens`, `OutputTokens`, `TotalTokens`)는 대화의 모든 메시지에 걸쳐 집계됩니다.
텍스트 콘텐츠만 응답에 포함됩니다. 도구 사용 및 추론 블록은에서 생략됩니다`Output.Message.Content`.
출력 크기에는 작업 상태 출력 제한이 적용됩니다. 현재 값은 섹션을 참조하세요[작업 실행과 관련된 할당량](service-quotas.md#service-limits-task-executions).
`InvokeHarness` Task 상태는 `TimeoutSeconds` 값이 해당 제한을 초과하더라도 최대 실행 시간이 15분(900초)입니다. 작업 상태 제한 시간이 초과되면 구성된 자체 제한 시간에 도달할 때까지 하네스가 계속 실행됩니다. 예기치 않은 비용을 방지하려면 하네스 제한 시간이 15분을 초과하지 않도록 하세요.
Step Functions 콘솔 실행 세부 정보 보기에는 에이전트 단계 옆에 CloudWatch 링크가 표시되어 도구 사용을 포함한 에이전트의 추론을 turn-by-turn 볼 수 있습니다.
## 최적화된 Amazon Bedrock AgentCore 하네스 APIs
다음 API가 지원됩니다.
### [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)
도구를 사용하고, 메모리에 액세스하고, 멀티턴 대화를 실행할 수 있는 AI 에이전트를 실행하는 하네스를 호출합니다.
**지원되는 패턴:** 요청 응답만.
전체 요청 구문은 Amazon Bedrock AgentCore API 참조의 [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)를 참조하세요. * AgentCore *
**Step Functions의 파라미터는 PascalCase로 표현됩니다.**
기본 서비스 API가 API 작업 `startSyncExecution`과 같은 camelCase에 있더라도 `StateMachineArn`과 같은 파라미터를 PascalCase에 지정합니다.
**응답 필드**
+ `Output.Message` - 에이전트의 최종 어시스턴트 메시지입니다. `Role` (항상 `"assistant"`) 및 `Content` (텍스트 블록 배열)을 포함합니다. 마지막 어시스턴트 턴만 반환되고 멀티턴 대화의 이전 턴은 삭제됩니다.
+ `Output.Message.Content` - 콘텐츠 블록 배열입니다. 각 블록에는 에이전트의 응답 텍스트가 있는 `Text` 필드가 포함되어 있습니다. 텍스트 콘텐츠만 포함되며 도구 사용 및 추론 블록은 생략됩니다.
+ `StopReason` - 에이전트가 중지된 이유입니다. 값: `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`.
+ `Usage` - 모든 턴에 걸쳐 집계된 토큰 소비 지표입니다. `InputTokens`, `OutputTokens`및를 포함합니다`TotalTokens`.
+ `Metrics.LatencyMs` - 모든 턴에 걸쳐 집계된 밀리초 단위의 총 호출 지연 시간입니다.
**응답 구문**
```
{
"Output": {
"Message": {
"Role": "{{string}}",
"Content": [
{
"Text": "{{string}}"
}
]
}
},
"StopReason": "{{string}}",
"Usage": {
"InputTokens": {{long}},
"OutputTokens": {{long}},
"TotalTokens": {{long}}
},
"Metrics": {
"LatencyMs": {{long}}
}
}
```
**참고**
실행 또는 작업 상태를 중지해도 하네스가 계속 실행되지 않습니다.
## Amazon Bedrock AgentCore 통합을 위한 태스크 상태 정의
다음 예제에서는 Amazon Bedrock AgentCore 하네스를 호출하는 작업 상태를 정의하는 방법을 보여줍니다.
`RuntimeSessionId` 필드는 대화 세션을 식별합니다. 간접 호출 간에 동일한 세션 ID를 사용하여 대화를 계속합니다.
**참고**
Step Functions 리소스 URI는 `bedrockagentcore` (하이픈 없음)를 사용하는 반면, Amazon Bedrock AgentCore 리소스 ARNs `bedrock-agentcore` (하이픈 있음)을 사용합니다.
**Example 모델 재정의 및 시스템 프롬프트를 사용한 기본 호출**
```
{
"Type": "Task",
"Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
"Arguments": {
"HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{my-agent-harness}}",
"RuntimeSessionId": "{% $uuid() %}",
"Messages": [
{
"Content": [{ "Text": "{% $states.input.userMessage %}" }],
"Role": "user"
}
],
"SystemPrompt": [{ "Text": "You are a helpful customer service agent." }],
"Model": {
"BedrockModelConfig": {
"Temperature": 0.7,
"ModelId": "global.anthropic.claude-sonnet-4-6"
}
},
"MaxIterations": 75,
"TimeoutSeconds": 600
},
"End": true
}
```
**Example 도구를 사용한 호출(브라우저)**
```
{
"Type": "Task",
"Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
"Arguments": {
"HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{order-agent}}",
"RuntimeSessionId": "{% $uuid() %}",
"Messages": [
{
"Content": [{ "Text": "What is the status of order #12345?" }],
"Role": "user"
}
],
"Tools": [
{
"Type": "agentcore_browser",
"Name": "aws_browser_v1",
"Config": {
"AgentCoreBrowser": {
"BrowserArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:aws:browser/aws.browser.v1"
}
}
}
],
"MaxIterations": 10,
"TimeoutSeconds": 300
},
"End": true
}
```
**작은 정보**
전체 실행을 실행하기 전에 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API를 사용하여이 상태를 개별적으로 테스트할 수 있습니다.
## 오류 처리
`InvokeHarness` API는 제한, 검증, 액세스 거부 오류 등 다양한 오류와 함께 실패할 수 있습니다. 전체 목록은 Amazon Bedrock AgentCore API 참조의 [InvokeHarness 오류를](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html#API_InvokeHarness_Errors) 참조하세요. * AgentCore *
다음 예제에서는 오류 처리를 위한 `Retry` 및 `Catch` 필드가 있는 작업 상태를 보여줍니다.
```
{
"Type": "Task",
"Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
"Arguments": {
"HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{my-harness}}",
"Messages": [
{
"Content": [{ "Text": "{% $states.input.userMessage %}" }],
"Role": "user"
}
]
},
"Retry": [
{
"ErrorEquals": ["BedrockAgentCore.ThrottlingException"],
"IntervalSeconds": 2,
"MaxAttempts": 3,
"BackoffRate": 2.0
}
],
"Catch": [
{
"ErrorEquals": ["BedrockAgentCore.ResourceNotFoundException"],
"Next": "HandleNotFound"
},
{
"ErrorEquals": ["States.ALL"],
"Next": "HandleError"
}
],
"End": true
}
```
## Amazon Bedrock AgentCore 호출을 위한 IAM 정책
다음 예제 템플릿은가 상태 시스템 정의의 리소스를 기반으로 IAM 정책을 AWS Step Functions 생성하는 방법을 보여줍니다. 자세한 내용은 [Step Functions가 통합 서비스용 IAM 정책을 생성하는 방법](service-integration-iam-templates.md) 및 [Step Functions에서 서비스 통합 패턴 검색](connect-to-resource.md) 섹션을 참조하세요.
### Amazon Bedrock AgentCore 통합을 위한 IAM 정책 예제
다음 예제에서는 Step Functions 실행 역할에 대한 IAM 정책을 생성하여 Amazon Bedrock AgentCore 리소스와 상호 작용하는 방법을 보여줍니다.
다음 정책 예제에서 자리 표시자 값을 고유한 값으로 바꿉니다.
+ [특정 하네스를 호출하는 IAM 정책](#bedrockagentcore-policy-invoke-specific-harness)
+ [계정의 모든 하네스를 호출하는 IAM 정책](#bedrockagentcore-policy-invoke-all-harnesses)
#### 특정 하네스를 호출하는 IAM 정책
다음 예제 정책은 ARN으로 특정 Amazon Bedrock AgentCore 하네스를 호출할 수 있도록 허용합니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "InvokeSpecificHarness",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:InvokeHarness",
"bedrock-agentcore:InvokeAgentRuntime"
],
"Resource": "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:harness/{{harnessName}}"
}
]
}
```
#### 계정의 모든 하네스를 호출하는 IAM 정책
다음 예제 정책은 계정에서 Amazon Bedrock AgentCore 하네스를 호출할 수 있도록 허용합니다. 가능하면 특정 하네스 ARN으로 범위를 줄이는 것이 좋습니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "InvokeAllHarnesses",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:InvokeHarness",
"bedrock-agentcore:InvokeAgentRuntime"
],
"Resource": "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:harness/*"
}
]
}
```
**참고**
하네스가 게이트웨이, 브라우저 또는 코드 인터프리터와 같은 도구를 사용하는 경우 이러한 권한은 Step Functions *실행 역할이 아닌 하네스* 실행 역할에 구성됩니다. 자세한 내용은 *Amazon Bedrock AgentCore 사용 설명서*의 [Harness 실행 역할 권한을](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html) 참조하세요.