기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS CLI 또는 SDK를 사용하여 인스턴스 시작하기
이 자습서에서는 AWS 명령줄 인터페이스(AWS CLI) 및 SDK를 사용하여 **인스턴스** 컴퓨팅 유형에서 에이전트를 호스팅하는 방법을 안내합니다. SDKs 먼저 Amazon Elastic Compute Cloud(Amazon EC2) 인프라를 정의하는 [용량 공급자](runtime-instances-how-it-works.md#runtime-instances-capacity-provider)를 생성한 다음 이를 사용하는 에이전트 런타임을 생성하고 마지막으로 에이전트를 호출합니다.
사전 조건은 [인스턴스 시작하기를 참조하세요](runtime-instances-getting-started.md).
**참고**
이 예제의 파라미터 이름은 AgentCore 컨트롤 플레인 모델을 따릅니다. 신뢰할 수 있는 요청 및 응답 형태는 [Amazon Bedrock AgentCore 제어 API 참조](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html)를 참조하세요.
## 1단계: 용량 공급자 생성
`CreateCapacityProvider` 작업을 사용하여 EC2 인프라를 정의합니다. 요청은 `permissionsConfiguration` ( AgentCore가 용량 공급자를 운영하는 데 사용하는 IAM 역할) 및 시작 템플릿을 통해 EC2 인스턴스를 `computeConfiguration` 설명하는를 사용합니다. 다음 예시에서는 허용되는 단일 인스턴스 유형과 영구 EBS 볼륨을 사용하여 Linux 용량 공급자를 생성합니다.
**Example**
1.
```
aws bedrock-agentcore-control create-capacity-provider \
--name "my_capacity_provider" \
--permissions-configuration '{
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
}' \
--compute-configuration '{
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"]
}
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"]
},
"lifecycleConfiguration": {
"maxLifetime": 3600
},
"volumes": [
{ "ebsConfiguration": { "name": "scratch", "sizeGiB": 50, "volumeType": "gp3" } }
]
}
}'
```
1. boto3를 사용하여 용량 공급자를 생성하는 Python 예제입니다.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_capacity_provider(
name="my_capacity_provider",
permissionsConfiguration={
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
},
computeConfiguration={
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"],
},
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"],
},
"lifecycleConfiguration": {
"maxLifetime": 3600,
},
"volumes": [
{"ebsConfiguration": {"name": "scratch", "sizeGiB": 50, "volumeType": "gp3"}}
],
}
},
)
print(f"Capacity provider ARN: {response['capacityProviderArn']}")
```
GPU 워크로드를 실행하려면에 지원되는 GPU 인스턴스 유형을 포함합니다`allowedInstanceTypes`. AgentCore는 인스턴스에 GPU 드라이버를 프로비저닝하므로 표준 컨테이너 이미지는 드라이버 번들링 없이 작동합니다. 지원되는 패밀리는 `g4dn`, `g5`, `g6`, `g6e`, `gr6`, `g6f`, `gr6f`, 및 `g7e`입니다`inf2`. 지원되지 않는 패밀리의 액셀러레이터 인스턴스 유형을 포함하면에서 요청이 실패합니다`ValidationException`. 자세한 내용은 [GPU 인스턴스 유형 사용을](runtime-instances-how-it-works.md#runtime-instances-gpu) 참조하세요.
용량 공급자를 런타임과 연결`READY`하기 전에 상태가가 될 `GetCapacityProvider` 때까지 폴링합니다. 상태가가 되면 `statusCode` 및를 `CREATE_FAILED`검사`statusReason`하여 원인을 확인합니다.
## 2단계: 용량 공급자에서 에이전트 런타임 생성
용량 공급자를 참조`capacityProviderConfiguration`하는를 사용하여 에이전트 런타임을 생성합니다. 용량 공급자에 정의된 볼륨을 에이전트의 파일 시스템에 탑재하려면 볼륨을 이름으로 참조`filesystemConfigurations`하는 `capacityProviderVolume` 항목을에 추가합니다. 탑재 경로는 단일 하위 디렉터리(예: )를 `/mnt` 사용하여 아래에 있어야 합니다`/mnt/scratch`.
에이전트 런타임에는 기본값이 28,800초(8시간)`lifecycleConfiguration.maxLifetime`인 자체이 있습니다. 이 값은 용량 공급자`maxLifetime`가에 설정한 보다 작거나 같아야 합니다`ec2Configuration.lifecycleConfiguration`. 1단계의 용량 공급자는이 값을 3600초(1시간)로 설정하므로 런타임 기본값인 8시간이이 값을 초과하고에서 `CreateAgentRuntime` 실패합니다`ValidationException`. 따라서 다음 예제에서는 런타임을 용량 공급자`maxLifetime`의 제한 내에 있는 1800초로 설정합니다.
**참고**
두 리소스 모두 `lifecycleConfiguration` 멤버를 사용하지만 구조는 다릅니다. 용량 공급자의 버전은 `idleInstanceTimeout` 및를 가져`maxLifetime`와 인스턴스에 적용합니다. 에이전트 런타임의 버전은 `idleRuntimeSessionTimeout` 및를 가져`maxLifetime`와 세션에 적용합니다. 자세한 내용은 [Amazon Bedrock AgentCore 수명 주기 설정 구성을](runtime-lifecycle-settings.md) 참조하세요.
를 지정할 `networkConfiguration` 때 전달하지 마십시오`capacityProviderConfiguration`. 인스턴스 런타임은 용량 공급자의에서 네트워킹을 상속`ec2Configuration.vpcConfiguration`하므로를 둘 다 지정하면 실패합니다`ValidationException`.
**Example**
1.
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "my_instances_agent" \
--role-arn "arn:aws:iam::111122223333:role/AgentRuntimeRole" \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
}' \
--capacity-provider-configuration '{
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5"
}' \
--lifecycle-configuration '{
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800
}' \
--filesystem-configurations '[
{
"capacityProviderVolume": { "volumeName": "scratch", "mountPath": "/mnt/scratch" }
}
]'
```
1. boto3를 사용하여 인스턴스에서 에이전트 런타임을 생성하는 Python 예제입니다.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="my_instances_agent",
roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
},
capacityProviderConfiguration={
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5",
},
lifecycleConfiguration={
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800,
},
filesystemConfigurations=[
{
"capacityProviderVolume": {"volumeName": "scratch", "mountPath": "/mnt/scratch"}
}
],
)
print(f"Agent runtime ARN: {response['agentRuntimeArn']}")
```
## 3단계: 에이전트 간접 호출
microVM 지원 런타임과 동일한 방식으로 런타임을 호출합니다. 간접 호출 `runtimeSessionId` 간에 동일한를 재사용하여 세션을 동일한 인스턴스에 유지합니다. 이렇게 하면 에이전트가 이전 호출의 데이터에 액세스할 수 있습니다. 공동 작업 에이전트를 공동 배치하려면 용량 공급자를 공유하는 여러 런타임`runtimeSessionId`에서 동일한를 사용합니다.
**Example**
1.
```
echo '{"prompt": "Analyze the sales data and summarize the key trends."}' > payload.json
aws bedrock-agentcore invoke-agent-runtime \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000" \
--qualifier "DEFAULT" \
--payload fileb://payload.json \
response.json
```
`payload` 파라미터는 바이너리 Blob이며 AWS CLI는 기본적으로 Blob이 base64로 인코딩될 것으로 예상합니다. 와 같은 원시 JSON 인라인 전달은 요청에 도달하기 전에 `Invalid base64` 오류와 함께 클라이언트 측에서 `--payload '{"prompt": "…"}'`실패합니다. 여기에 사용된 `fileb://` 양식은 `cli_binary_format` 설정에 관계없이 파일을 바이너리로 읽으므로 인코딩 단계를 방지합니다.
에이전트의 응답은이 예제에서 AWS CLI가 마지막 인수로 지정한 출력 파일에 쓰는 스트리밍 BLOB입니다`response.json`. 표준 출력에는 `runtimeSessionId`, `contentType`및 `statusCode` 필드만 포함되므로 출력 파일을 읽고 에이전트가 반환한 내용을 확인합니다.
AWS SDK
1. boto3를 사용하여 인스턴스에서 에이전트 런타임을 호출하는 Python 예제입니다.
```
import boto3
import json
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000", # 33+ chars; reuse to keep the session
payload=json.dumps({"prompt": "Analyze the sales data and summarize the key trends."}).encode(),
qualifier="DEFAULT",
)
print("Agent response:", json.loads(response["response"].read()))
```
는 33자 이상이어야 `runtimeSessionId` 합니다.
새 세션의 첫 번째 호출은 계정에 EC2 인스턴스를 프로비저닝하고 에이전트를 시작하므로 일반적으로 이후 호출보다 오래 걸립니다. 동일한 세션에 대한 후속 호출은 실행 중인 인스턴스를 재사용하고 훨씬 더 빠르게 반환합니다.
AgentCore는 이러한 인스턴스를 [Amazon EC2 관리형 인스턴스](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html)로 프로비저닝하며, 기본적으로 `DescribeInstances` 및 EC2 콘솔 보기에서 숨겨집니다. 일반 `aws ec2 describe-instances` 호출에는 나열되지 않습니다. 이를 보려면 관리형 리소스를 포함합니다.
```
aws ec2 describe-instances --include-managed-resources \
--filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"
```
인스턴스 가시성 관리에 대한 자세한 내용은 [관리형 리소스 가시성 설정을](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html#managed-resource-visibility-settings) 참조하세요.
## 인스턴스 하나에 여러 에이전트 공동 배치
두 에이전트 런타임이 **동일한** 용량 공급자를 참조하고 **동일한** 로 호출하면 `runtimeSessionId`두 에이전트 모두 동일한 EC2 인스턴스에서 실행됩니다. 여기에서 파일 시스템 구성에 구성된 볼륨을 공유할 수 있습니다. 에이전트는 공유 볼륨에서 파일을 읽고 기록하여 협업합니다. 각 에이전트는 독립적으로 호출되며 달리 상태를 공유하지 않습니다. 예를 들어 테스트 실행기는 볼륨에 결과를 쓸 수 있으며, 동일한 세션에서 호출된 코드 분석기는 결과를 읽을 수 있습니다. 공유 인스턴스의 에이전트 간 경계는 [런타임 인스턴스에 대한 보안 모델 및 권한을 참조하세요](runtime-instances-security.md).
```
import boto3
import json
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
session_id = "collab-session-000000000000000000000"
# Agent A — created on capacity provider "my_capacity_provider"
client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test-runner-suffix",
runtimeSessionId=session_id,
payload=json.dumps({"prompt": "Run the test suite for project ABC"}).encode(),
qualifier="DEFAULT",
)
# Agent B — a different runtime that shares the SAME capacity provider and session ID,
# so it runs on the same instance as Agent A and can read the files Agent A wrote to the shared volume.
client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/code-analyzer-suffix",
runtimeSessionId=session_id,
payload=json.dumps({"prompt": "Analyze the code for project ABC"}).encode(),
qualifier="DEFAULT",
)
```
각 에이전트는 런타임의 실행 역할에서 파생된 자체 IAM 자격 증명으로 실행되므로 공동 작업 에이전트가 동일한 인스턴스를 공유하더라도 서로 다른 권한을 부여할 수 있습니다. 그러나 동일한 인스턴스의 에이전트는 서로 격리되어 있지 않으므로 모든 에이전트는 잠재적으로 다른 에이전트의 자격 증명을 읽을 수 있습니다. 상호 신뢰할 수 있는 에이전트만 공동 배치합니다. 자세한 내용은 [런타임 인스턴스에 대한 보안 모델 및 권한을 참조하세요](runtime-instances-security.md).
## 정리: 세션 중지 및 삭제
**주의**
계정에 프로비저닝된 Amazon EC2 인스턴스 및 Amazon EBS 볼륨에 대한 요금이 계속 부과되지 않도록 하려면이 자습서를 완료할 때 더 이상 필요하지 않은 세션 및 용량 공급자를 삭제합니다.
세션은 동일한 인스턴스에서 여러 에이전트 런타임을 호스팅할 수 있으므로 AgentCore는 두 가지 고유한 작업을 제공합니다.
+ **세션에서 에이전트 런타임 중지** -는 런타임 ARN 및 세션 ID로 식별되는 세션 내에서 단일 에이전트 런타임을 `StopRuntimeSession` 중지합니다. 동일한 세션과 인스턴스를 공유하는 다른 에이전트 런타임은 영향을 받지 않습니다.
+ **세션 삭제** -는 전체 세션을 `DeleteCapacityProviderSession` 삭제하고 계정에서 생성된 EC2 리소스(인스턴스, 네트워크 인터페이스 및 영구 EBS 볼륨)의 프로비저닝을 해제하므로 인프라 및 스토리지 비용 발생을 중지합니다.
세션에서 특정 에이전트 런타임을 중지하려면 런타임 ARN 및 세션 ID를 사용하여 [StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) 작업을 호출합니다.
**Example**
1.
```
aws bedrock-agentcore stop-runtime-session \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000"
```
1. boto3를 사용하여 런타임 세션을 중지하는 Python 예제입니다.
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
client.stop_runtime_session(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000",
)
```
세션을 삭제하고 영구 EBS 볼륨을 포함한 모든 리소스를 프로비저닝 해제하려면 용량 공급자 ID와 세션 ID를 `DeleteCapacityProviderSession` 사용하여를 호출합니다. 작업은 멱등성 및 비동기식입니다. AgentCore가 인스턴스를 종료하고 백그라운드에서 볼륨을 삭제하는 동안 즉시 반환됩니다.
세션 IDs는 호출 시 제공하는 값이며 용량 공급자의 세션을 나열하는 작업은 없습니다. 나중에 각 세션을 삭제할 수 있도록 사용하는 `runtimeSessionId` 값을 기록해 둡니다. 더 이상 인스턴스가 없는 경우 아직 실행 중인 인스턴스를 찾은 다음 용량 공급자를 삭제하여 모든 세션을 프로비저닝 해제할 수 있습니다.
```
aws ec2 describe-instances --include-managed-resources \
--filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id" \
--query 'Reservations[].Instances[?State.Name!=`terminated`].[InstanceId,State.Name]'
```
**Example**
1.
```
aws bedrock-agentcore delete-capacity-provider-session \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5" \
--session-id "project-xyz-0000000000000000000000000000"
```
1. boto3를 사용하여 용량 공급자 세션을 삭제하는 Python 예제입니다.
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.delete_capacity_provider_session(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
sessionId="project-xyz-0000000000000000000000000000",
)
print("Session status:", response["status"])
```
## 용량 공급자 삭제
용량 공급자가 더 이상 필요하지 않으면 `DeleteCapacityProvider` 작업으로 용량 공급자를 삭제합니다. 용량 공급자를 삭제하면 연결된 모든 세션과 영구 스토리지가 중지되고 삭제되므로 더 이상 IDs 합니다. 세션을 먼저 삭제할 필요는 없습니다. 그러나 용량 공급자를 참조하는 런타임을 제거해야 합니다. 연결된 버전, 엔드포인트 또는 런타임을 먼저 삭제하거나에서 삭제 요청이 실패합니다`ValidationException`. 작업은 비동기식이며 ID로 용량 공급자를 식별합니다.
**Example**
1.
```
aws bedrock-agentcore-control delete-capacity-provider \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5"
```
1. boto3를 사용하여 용량 공급자를 삭제하는 Python 예제입니다.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
client.delete_capacity_provider(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
)
```