기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # AgentCore 런타임에서 Amazon Bedrock Managed Agents(OpenAI 사용) 시작하기 **참고** Amazon Bedrock Managed Agents(OpenAI 사용)는 미리 보기 상태입니다. 기능 및 APIs 정식 출시 전에 변경될 수 있습니다. Amazon Bedrock Managed Agents는 OpenAI Codex 하네스를 실행합니다 AWS. 하네스는 모델과 도구 간에 루프를 실행하고 세션을 유지하며 대화가 증가함에 따라 컨텍스트를 압축합니다. 에이전트가 명령을 실행하거나 파일로 작업해야 하는 경우 Bedrock Managed Agents는 작업을 환경으로 보냅니다. 해당 환경이 실행되는 위치를 결정합니다. 로컬 개발을 위해 자체 컴퓨터에서 Codex exec-server를 실행할 수 있습니다. 다른 워크로드의 경우 Bedrock Managed Agents는 계정에서 AgentCore 런타임을 호출합니다. 런타임은 각 세션에 고유한 microVM을 제공합니다. 세션은 사용자가 제어하는 실행 역할로 실행되며 런타임은 에이전트가 프라이빗 리소스에 도달할 수 있도록 VPC에 연결할 수 있습니다. 모델 호출은 Bedrock Managed Agents에 유지되므로 컨테이너는 에이전트가 보내는 명령만 실행합니다. 이 자습서에서는 다음 작업을 수행합니다. + AgentCore CLI를 사용하여 런타임을 생성하고 배포합니다. + OpenAI SDK로 세션을 시작합니다. 에이전트는 런타임에서 샘플 스킬을 사용합니다. + (선택 사항) 자체 기술을 추가합니다. 1\~4단계에는 약 15분이 걸립니다. 이 자습서에서 생성한 AWS 리소스로 인해 AWS 계정에 요금이 부과될 수 있습니다. 이러한 리소스에는 런타임, AWS CodeBuild 이미지 빌드 및 Bedrock Managed Agents 모델 호출이 포함됩니다. 자세한 내용은 [AgentCore 요금을](https://aws.amazon.com/bedrock/agentcore/pricing/) 참조하세요. 요금을 중지하려면에서 리소스를 제거합니다[8단계: 정리](#runtime-get-started-bma-clean-up). ## 사전 조건 + **Node.js 20 이상.** AgentCore CLI는 npm 패키지로 배포됩니다. 로 확인합니다`node --version`. + **uv.** 샘플 클라이언트는 [uv](https://docs.astral.sh/uv/)를 사용하여 Python 종속성을 설치합니다. + **자격 증명이 구성된 AWS 계정입니다.** 계정을 생성하려면 [AWS 계정 시작하기를 참조하세요](https://docs.aws.amazon.com/accounts/latest/reference/getting-started.html). 자격 증명을 구성하려면 [AWS CLI 구성을 참조하세요](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). + **IAM 권한**. 자격 증명에는 AgentCore API를 호출하고 배포 중에 사용되는 CDK 부트스트랩 역할을 수임할 수 있는 권한이 필요합니다. [AgentCore CLI 사용을 참조하세요](runtime-permissions.md#runtime-permissions-cli). 샘플 클라이언트에는 IAM 권한도 필요합니다. [세션 역할](#runtime-get-started-bma-session-role) 섹션을 참조하세요. + **모델 액세스.** 계정에 Bedrock Managed Agents 모델에 대한 액세스 권한이 필요합니다`openai.gpt-5.6-luna`. CLI는 계정에서 AWS CodeBuild를 사용하여 컨테이너 이미지를 빌드합니다. ## 1단계: 프로젝트 생성 AgentCore CLI를 설치하고 자격 증명과 리전을 설정합니다. ``` npm install -g @aws/agentcore agentcore --version export AWS_PROFILE=your-profile export AWS_REGION=us-east-1 ``` `BedrockManagedAgents` 프레임워크를 사용하여 프로젝트를 생성합니다. 플래그 없이 `agentcore create`를 실행할 수도 있습니다. **에이전트**를 선택한 다음 **Bedrock Managed Agents**를 프레임워크로 선택합니다. ``` agentcore create --name MyManagedAgent --framework BedrockManagedAgents cd MyManagedAgent ``` 프로젝트에는의 런타임 구성`agentcore/agentcore.json`과의 컨테이너 소스가 있습니다`app/MyManagedAgent/`. 컨테이너는 Bedrock Managed Agents에 `codex exec-server`연결하고 에이전트의 명령을 실행하는를 실행합니다. 프로젝트는 다음과 같은 기본값으로 런타임을 구성합니다. + 유휴 제한 시간 30분 및 최대 수명 8시간. [수명 주기 설정 구성을](runtime-lifecycle-settings.md) 참조하세요. + 의 권한이 있는 실행 역할입니다`policies/bma-acr-policy.json`. ### 프로젝트 구조 ``` MyManagedAgent/ ├── agentcore/ │ ├── agentcore.json │ └── cdk/ └── app/MyManagedAgent/ ├── Dockerfile ├── lifecycle/server.py ├── otel/collector.yaml ├── plugins/acr-report/ ├── policies/ │ ├── bma-acr-policy.json │ ├── bma-session-trust.json │ └── bma-session-policy.json ├── pyproject.toml ├── client.py └── README.md ``` 키 파일: + `lifecycle/server.py` - 수명 주기 서버입니다. Bedrock Managed Agents는 이를 호출하여 런타임 세션`codex exec-server`에서 시작합니다. 이 파일을 변경하지 마십시오. + `Dockerfile` - Codex, CloudWatch 에이전트 및 Python을 설치하고 , `otel/`및 `lifecycle/`를 `plugins/`에 복사합니다`/opt/bma`. + `otel/collector.yaml` - exec-server의 스팬과 로그를 CloudWatch로 전송합니다. + `plugins/acr-report/` - 하나의 스킬이 있는 샘플 플러그인입니다. 스킬은 워크스페이스`acr-report.txt`에 저장됩니다. + `policies/bma-acr-policy.json` - 런타임 실행 역할의 정책입니다. `bedrock-mantle:RegisterEnvironment` 및 `bedrock-mantle:ConnectEnvironment`를 허용합니다. 한 프로젝트로 제한하려면를 `Resource`로 변경합니다`arn:aws:bedrock-mantle:::project/`. + `pyproject.toml` - Python 종속성입니다. `dev` 그룹은 `client.py` 용입니다. + `policies/bma-session-trust.json` 및 `policies/bma-session-policy.json` - 신뢰 정책 및 세션 역할의 권한입니다. [세션 역할](#runtime-get-started-bma-session-role) 섹션을 참조하세요. + `client.py` - 세션을 시작하는 샘플 클라이언트입니다. 3단계에서 실행합니다. ### VPC에 런타임 배포 에 네트워크 옵션을 추가합니다`agentcore create`. ``` agentcore create --name MyManagedAgent --framework BedrockManagedAgents \ --network-mode VPC --vpc-id --subnets \ --security-groups ``` VPC에는 Bedrock Managed Agents 엔드포인트에 대한 경로가 있어야 합니다. exec-server가 연결되어 있기 때문입니다. 이미지 빌드는 Codex 및 Python을 다운로드하므로 인터넷에 대한 경로도 필요합니다. [VPC용 AgentCore 구성을](agentcore-vpc.md) 참조하세요. ### 인스턴스에서 런타임 실행 동일한 프로젝트가 인스턴스 컴퓨팅 유형에서 실행**됩니다**. 프로젝트에 용량 공급자를 추가한 다음 용량 공급자와 함께 에이전트를 추가합니다. ``` agentcore create --name MyManagedAgent --no-agent cd MyManagedAgent agentcore add capacity-provider --name MyCapacityProvider \ --subnets --security-groups \ --os LINUX_ARM64 --instance-types c7g.large agentcore add agent --name MyManagedAgent --framework BedrockManagedAgents \ --capacity-provider MyCapacityProvider ``` 그런 다음를 계속합니다[2단계: 배포](#runtime-get-started-bma-deploy).는 용량 공급자와 해당 연산자 역할`agentcore deploy`도 생성합니다. + 이미지 빌드는 ARM64 이미지를 만들기 때문에 `LINUX_ARM64` 및 Graviton 인스턴스 유형을 사용합니다. + 용량 공급자는 네트워크를 제공합니다. 서브넷에는 Bedrock Managed Agents 엔드포인트에 대한 경로가 있어야 합니다. 프로젝트에 없는 용량 공급자를 연결하려면 해당 ARN을에 제공합니다`agentcore create --framework BedrockManagedAgents --capacity-provider `. [런타임 인스턴스 및 용량 공급자를 참조하세요](runtime-instances.md). ## 2단계: 배포 ``` agentcore deploy agentcore status ``` CLI는 계정에서 AWS CodeBuild로 이미지를 빌드하고 런타임 및 실행 역할을 배포합니다. Bedrock Managed Agents는 런타임을 호출합니다. 의 출력에서 런타임 ARN을 저장합니다`agentcore status`. ``` arn:aws:bedrock-agentcore:us-east-1::runtime/ ``` ## 3단계: 세션 실행 Bedrock Managed Agents는 세션 역할을 사용하여 모델을 호출하고 런타임을 호출합니다. 세션 역할은 런타임 실행 역할이 아닙니다. **를 실행하면 계정에 세션 역할`client.py`이 생성됩니다. **`agentcore deploy`는 세션 역할을 생성하지 않고 삭제하지 `agentcore remove` 않습니다. [세션 역할](#runtime-get-started-bma-session-role) 섹션을 참조하세요. 에이전트 디렉터리에서 클라이언트를 실행합니다. ``` cd app/MyManagedAgent uv run client.py --runtime ``` 클라이언트는 세션을 생성하고 세션 ID, 출력이 포함된 각 명령, 에이전트의 응답을 인쇄합니다. 기본적으로 에이전트는 `acr-report` 스킬을 사용하여 워크스페이스`acr-report.txt`에 저장합니다. 다음 섹션에서는 클라이언트가 세션 역할을 관리하는 방법과 클라이언트를 실행하는 데 필요한 IAM 권한을 설명합니다. ### 세션 역할 세션 역할은 런타임 실행 역할이 아닙니다.는를 사용하여 실행 역할을 `agentcore deploy` 생성합니다`policies/bma-acr-policy.json`. 클라이언트는 세션을 생성할 때 `role_arn` 필드의 Bedrock Managed Agents에 세션 역할을 부여합니다. 새 세션을 시작하고 `--role-arn`를 제공하지 않으면 클라이언트는 다음 단계를 수행합니다. 1. 역할`BmaSessionRole-`이 없으면 클라이언트가 생성합니다. 1. 클라이언트는 신뢰 정책과 역할`BmaSession`의 인라인 정책을 `policies/bma-session-trust.json` 및와 비교합니다`policies/bma-session-policy.json`. 정책이 동일하지 않은 경우 클라이언트는 파일을 역할에 씁니다. 파일은 런타임의 계정 및 리전으로 제한됩니다. 1. 클라이언트가 역할을 변경한 경우 15초 동안 기다립니다. Bedrock Managed Agents가 변경 사항을 사용하려면 IAM에이 시간이 필요합니다. 역할을 변경하려면 파일을 변경합니다. 클라이언트는 다른 사용자가 역할에 추가하는 다른 정책을 제거하지 않습니다. 를 제공할 때 역할을 확인하지 않으며 `--session-id`를 사용하여 제공하는 역할을 변경하지 않습니다`--role-arn`. 프로덕션의 경우 클라이언트에를 사용하여 하나의 런타임과 하나의 게이트웨이에 대한 역할을 부여합니다`--role-arn`. 역할을 만들려면의 두 파일을 사용합니다`policies/`. 파티션, 리전 및 계정 ID를 입력하고 및 ` `에서를 런타임 ID 및 게이트웨이 ID`runtime/``gateway/*`로 변경합니다. 리전의 모든 프로젝트가를 공유하므로 프로젝트의 파일을 변경하지 마십시오`BmaSessionRole-`. 클라이언트를 실행하는 자격 증명에는 세션 역할에 `iam:PassRole` 대한 Bedrock Managed Agents 클라이언트 권한`bedrock-mantle:CallWithBearerToken`, 및가 필요합니다. 클라이언트가 역할을 생성하고 복구하도록 하려면에 `iam:GetRole`, `iam:CreateRole`, `iam:GetRolePolicy`, `iam:UpdateAssumeRolePolicy`및 `iam:PutRolePolicy` 도 제공합니다`arn:aws:iam:::role/BmaSessionRole-*`. 를 부여하면 클라이언트`--role-arn`에 이러한 5가지 권한이 필요하지 않습니다. 신뢰 정책, 세션 역할의 권한 및 클라이언트 권한은 *Amazon Bedrock 사용 설명서*의 [보안 및 IAM 역할을](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-managed-agents-openai-security.html) 참조하세요. ### 클라이언트 작동 방식 클라이언트는 `openai` 패키지의 `client.beta.agents` 리소스를 사용합니다. Bedrock Managed Agents는 에이전트 루프를 실행합니다. 클라이언트는 세션을 생성할 때에서 `environment`다음 값을 설정합니다. + `type` - `aws_bedrock_agentcore`- Bedrock Managed Agents에 AgentCore 런타임을 사용하도록 지시합니다. + `runtime_arn` - 런타임. 세션은 런타임의 리전에서 실행됩니다. + `workspace_directory` - 에이전트가 명령을 실행하는 디렉터리입니다. 클라이언트는를 사용합니다`/home/app/workspace`. 수명 주기 서버는 디렉터리를 생성합니다. + `runtime_qualifier` - 런타임의 엔드포인트입니다. 클라이언트는를 사용합니다`DEFAULT`. + `capability_directories` - Bedrock Managed Agents가 기술을 찾는 디렉터리입니다. 클라이언트는를 사용합니다`/opt/bma/plugins`. 또한 클라이언트는 `role_arn`를 세션 역할`extra_body`로 설정합니다. `openai` 패키지에는이 필드에 대한 파라미터가 없습니다. `provide_token` 헬퍼는 자격 AWS 증명을 사용하여 각 요청에 대해 수명이 짧은 Amazon Bedrock 보유자 토큰을 가져옵니다. 프로젝트에 게이트웨이를 추가하는 경우를 `agentcore deploy` 사용하여의 출력에서 해당 ARN을 제공합니다`--gateway`. 플래그는 새 세션에만 사용합니다. 클라이언트는에서 ARN이 있는 `mcp` 도구로 게이트웨이를 추가합니다`connector_id`. Bedrock Managed Agents는 세션 역할을 사용하여 게이트웨이를 호출합니다. 게이트웨이는 MCP 버전를 지원해야 합니다`2025-03-26`. 그렇지 않으면 에이전트는 게이트웨이 도구를 가져오지 않으며 Bedrock Managed Agents는 오류를 표시하지 않습니다. ``` """Send an input to a Bedrock Managed Agents session that uses this project's ACR.""" import argparse import json import time from pathlib import Path from typing import Any import boto3 from aws_bedrock_token_generator import provide_token from botocore.exceptions import ClientError from openai import NotFoundError, OpenAI BMA_MODEL_ID = "openai.gpt-5.6-luna" # The agent runs its commands in this directory. The lifecycle server creates it. WORKSPACE_DIRECTORY = "/home/app/workspace" # Plugins and skills that the agent can use. The image has the acr-report plugin # at this path. Add the path of an S3 Files mount to use the skills in a bucket. CAPABILITY_DIRECTORIES = ["/opt/bma/plugins"] TURN_END = ("completed", "failed", "cancelled") TOOL_CALLS = ("mcp_call", "function_call", "web_search_call") POLICIES = Path(__file__).parent / "policies" SESSION_ROLE = "BmaSessionRole-{region}" SESSION_POLICY = "BmaSession" def show(data: dict[str, Any]) -> None: """Prints the session ID, the commands, the tool calls, and the answer.""" kind = data["type"].removeprefix("agent.session.") item = data.get("item") or {} if kind == "created": print(f"Session {data['session']['id']}") elif kind == "turn.output_text.delta": print(data["delta"], end="", flush=True) elif kind == "turn.item.done" and item.get("type") == "command_execution": print(f"\n$ {item['command']}\n{item.get('output') or ''}".rstrip()) elif kind == "turn.item.done" and item.get("type") in TOOL_CALLS: print(f"\nTool {item.get('name') or item['type']} {item.get('status')}") elif kind == "error" or kind.split(".")[-1] in TURN_END: source = data.get("turn") or data.get("environment") or data.get("session") print(f"\n{kind} {(source or data).get('error') or ''}".rstrip()) def load_policy(name: str, partition: str, region: str, account: str) -> str: """Reads a policy file and puts in the partition, the Region, and the account.""" text = (POLICIES / name).read_text() for key, value in (("Partition", partition), ("Region", region), ("AccountId", account)): text = text.replace("${AWS::" + key + "}", value) return text def session_role(runtime_arn: str) -> str: """Creates or repairs the session role, and returns its ARN. If the trust policy or the policy of the role is not the same as the file in `policies/`, the client writes the file to the role. """ _, partition, _, region, account = runtime_arn.split(":")[:5] name = SESSION_ROLE.format(region=region) trust = load_policy("bma-session-trust.json", partition, region, account) policy = load_policy("bma-session-policy.json", partition, region, account) iam = boto3.client("iam") changed = False try: role = iam.get_role(RoleName=name)["Role"] except iam.exceptions.NoSuchEntityException: role = iam.create_role(RoleName=name, AssumeRolePolicyDocument=trust)["Role"] print(f"Created the session role {name}") changed = True else: if role["AssumeRolePolicyDocument"] != json.loads(trust): iam.update_assume_role_policy(RoleName=name, PolicyDocument=trust) print(f"Updated the trust policy of {name}") changed = True try: current = iam.get_role_policy(RoleName=name, PolicyName=SESSION_POLICY)["PolicyDocument"] except iam.exceptions.NoSuchEntityException: current = None if current != json.loads(policy): iam.put_role_policy(RoleName=name, PolicyName=SESSION_POLICY, PolicyDocument=policy) if not changed: print(f"Updated the policy of {name}") changed = True if changed: # IAM needs some seconds before Bedrock Managed Agents can use a new or changed role. time.sleep(15) return role["Arn"] def main() -> None: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--runtime", required=True, help="The ACR ARN.") parser.add_argument( "--session-id", help="The BMA session ID. If it does not exist, the client creates a session.", ) parser.add_argument( "--input", default="Use the acr-report skill to save an ACR report in the workspace.", ) parser.add_argument( "--gateway", help="The Gateway ARN from the output of `agentcore deploy`.", ) parser.add_argument( "--role-arn", help="The session role that BMA assumes. If you do not give it, the client creates a role.", ) parser.add_argument("--delete", action="store_true", help="Delete the session.") parser.add_argument("--raw", action="store_true", help="Print events as JSON.") args = parser.parse_args() # BMA must run in the Region of the ACR. region = args.runtime.split(":")[3] with OpenAI( api_key=lambda: provide_token(region=region), base_url=f"https://bedrock-mantle.{region}.api.aws/openai/v1", ) as client: sessions = client.beta.agents.sessions session_id = args.session_id if session_id: try: session = sessions.retrieve(session_id).model_dump(warnings=False) except NotFoundError: print(f"Session {session_id} does not exist.") session_id = None else: if session["environment"].get("runtime_arn") != args.runtime: raise ValueError(f"Session {session_id} uses another ACR.") if not session_id and not args.role_arn: try: args.role_arn = session_role(args.runtime) except ClientError as error: parser.error( f"The client cannot create or check the session role: {error}. " "Get the IAM permissions in README.md, or give --role-arn." ) print(f"Session role {args.role_arn}") if session_id: # BMA opens the stream only with stream=true, and the SDK does not send it. events = sessions.events.stream(session_id, extra_query={"stream": "true"}) message = { "role": "user", "content": [{"type": "input_text", "text": args.input}], } sessions.events.create( session_id, events=[{"type": "agent.session.input.message", "input": [message]}], ) else: agent: dict[str, Any] = { "model": BMA_MODEL_ID, "instructions": "Use the available tools to complete the task.", } if args.gateway: # Bedrock Managed Agents calls Gateway with the session role from the service side. agent["tools"] = [ {"type": "mcp", "server_label": "team_tools", "connector_id": args.gateway} ] args.input += " Then list the tools that the Gateway gives you." events = sessions.create( agent=agent, environment={ "type": "aws_bedrock_agentcore", "runtime_arn": args.runtime, "runtime_qualifier": "DEFAULT", "workspace_directory": WORKSPACE_DIRECTORY, "capability_directories": CAPABILITY_DIRECTORIES, }, input=args.input, stream=True, # The SDK has no role_arn parameter. BMA assumes this role to call the ACR. extra_body={"role_arn": args.role_arn}, ) with events: for event in events: data = event.model_dump(mode="json", warnings=False) session_id = session_id or (data.get("session") or {}).get("id") if args.raw: print(json.dumps(data), flush=True) else: show(data) if data["type"].removeprefix("agent.session.turn.") in TURN_END: break if args.delete: sessions.delete(session_id) print(f"\nDeleted session {session_id}") if __name__ == "__main__": main() ``` ## 4단계: 세션 계속 동일한 세션에 다른 입력을 보내려면 세션 ID를 추가합니다. 턴은 동일한 워크스페이스를 사용합니다. 유휴 중지 후에도 워크스페이스를 유지하려면 에서와 같이 세션 스토리지를 추가합니다[유휴 중지 후 파일 유지](#runtime-get-started-bma-keep-files). ``` uv run client.py --runtime --session-id \ --input "Run cat acr-report.txt and show the output." ``` 세션이 없는 경우 클라이언트는 새 세션을 생성합니다. `--delete`를 추가하여 턴 후 세션을 삭제하거나 `--raw`를 추가하여 각 이벤트를 JSON으로 인쇄합니다. ### 유휴 중지 후 파일 유지 microVM 런타임에서 exec-server의 홈 디렉터리를 세션 스토리지에 배치합니다. 그런 다음 워크스페이스, 연결 상태 및는 유휴 중지 후에도 `CODEX_HOME` 유지됩니다. 1. 1단계의 명령 대신 세션 스토리지를 사용하여 프로젝트를 생성합니다. ``` agentcore create --name MyManagedAgent --framework BedrockManagedAgents \ --session-storage-mount-path /mnt/home cd MyManagedAgent ``` 1. 에서 런타임 항목에이 변수를 `agentcore/agentcore.json`추가합니다. ``` "envVars": [{ "name": "BMA_HOME_DIR", "value": "/mnt/home" }] ``` 1. 에서를 `client.py`설정합니다`WORKSPACE_DIRECTORY = "/mnt/home/workspace"`. 1. 클라이언트를 배포하고 실행합니다. 세션 스토리지에 대한 자세한 내용은 [ AgentCore 런타임의 파일 시스템 구성을 참조하세요](runtime-filesystem-configurations.md). ## 5단계: (선택 사항) 스킬 추가 이미지에 스킬을 추가하려면 아래에 플러그인을 추가`plugins/`하고 배포합니다. 플러그인에는 `.codex-plugin/plugin.json` 파일과 `skills/` 디렉터리가 있습니다. `skills/` 디렉터리에는 각 스킬에 대해 하나의 하위 디렉터리가 있으며, 그 안에 `SKILL.md` 파일이 있습니다. 이미지는 클라이언트`/opt/bma/plugins`가 Bedrock Managed Agents에 이미 제공한에 복사합니다. 시작하려면를 복사`plugins/acr-report/`하고 플러그인 디렉터리 및 `skills/acr-report/`의 이름을 플러그인 및 스킬의 이름으로 바꿉니다. 에서 `plugin.json`, `name``version`, 및 `description`를 설정합니다`"skills": "./skills/"`. 각는 `name` 및가 있는 전면부터 `SKILL.md` 시작합니다`description`. 배포 후를 사용하여 새 세션을 시작합니다`--input "Use the skill to …​"`. ### Amazon S3 버킷에서 스킬 공유 런타임에 S3 파일 액세스 포인트를 마운트합니다. 그런 다음 버킷이 변경되면 기술이 변경되고 이미지는 동일하게 유지됩니다. S3 파일 시스템, 액세스 포인트 및 보안 그룹 규칙은 [ AgentCore 런타임에 대한 파일 시스템 구성을](runtime-filesystem-configurations.md) 참조하세요. S3 파일 탑재에는 VPC 네트워크 모드의 런타임이 필요합니다. 의 네트워크 옵션을 사용하여 프로젝트를 생성합니다[VPC에 런타임 배포](#runtime-get-started-bma-vpc). 버킷에서 각 플러그인을 액세스 포인트의 루트 디렉터리 아래에 있는 자체 디렉터리에 넣습니다. `plugins/acr-report/`: `/.codex-plugin/plugin.json` 및와 동일한 레이아웃을 사용합니다`/skills//SKILL.md`. 에서 런타임 항목에 탑재를 추가합니다`agentcore/agentcore.json`. ``` { "filesystemConfigurations": [ { "s3FilesAccessPoint": { "accessPointArn": "arn:aws:s3files:us-east-1:111122223333:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0", "mountPath": "/mnt/skills" } } ] } ``` 그런 다음 `CAPABILITY_DIRECTORIES`를 `client.py`로 설정하고 `["/opt/bma/plugins", "/mnt/skills"]`배포합니다. ## 6단계: 로그 및 추적 보기 ``` agentcore logs --since 15m ``` 첫 번째 배포는 계정에서 CloudWatch 트랜잭션 검색을 켭니다. 트레이스는 약 10분 후에 표시됩니다. 추적을 보려면 CloudWatch 콘솔을 열고 **GenAI 관찰성을** 선택합니다. Bedrock Managed Agents에서 수명 주기 서버로의 각 호출에는 하나의 `bma.invocation` 범위가 있습니다. 자세한 내용은 [Amazon Bedrock AgentCore 에이전트의 관찰성 데이터 보기를 참조하세요](observability-view.md). **트랜잭션 검색 설정은 전체 계정에 적용됩니다.** 트랜잭션 검색 및 해당 범위 인덱싱은 리전의 전체 계정에 적용되며 추가 요금이 적용될 수 있습니다. 현재 설정을 유지하려면 배포`~/.agentcore/config.json`하기 전에 `"disableTransactionSearch": true`에를 추가합니다. ## 7단계: 업데이트 및 재배포 의 런타임 설정 `agentcore/agentcore.json`또는 이미지 파일을 변경하고 다시 배포합니다. 예를 들어이 설정은 10분 후에 유휴 세션을 중지합니다. 값은 초 단위입니다. ``` { "lifecycleConfiguration": { "idleRuntimeSessionTimeout": 600, "maxLifetime": 28800 } } ``` ``` agentcore deploy ``` 변경 사항은 새 세션에 적용됩니다. ### 수명 주기 서버의 환경 변수 런타임 `envVars` 항목에 변수를 추가합니다. 예: `{ "name": "DISABLE_ADOT_OBSERVABILITY", "value": "true" }`. | 변수 | 기본값 | 설명 | | --- | --- | --- | | `DISABLE_ADOT_OBSERVABILITY` | 설정되지 않음 | 추적 및 exec-server 로그를 끄`true`려면 로 설정합니다. 수명 주기 서버는 여전히 런타임의 로그 그룹에 자체 로그를 기록합니다. | | `BMA_HOME_DIR` | `/home/app` | `HOME` exec-server의 입니다. | | `BMA_STATE_DIR` | `.bma`의 `BMA_HOME_DIR` | 세션의 연결 상태를 `state.json`유지하는의 디렉터리입니다. | | `BMA_CODEX_HOME` | `.codex`의 `BMA_HOME_DIR` | `CODEX_HOME` exec-server의 입니다. | | `BMA_CODEX_BINARY` | `/opt/bma/bin/codex` | Codex 바이너리입니다. | | `BMA_MAX_TURN_LEASE` | `300` | 초 단위의 가장 긴 턴 리스입니다. | 각 이미지 빌드는 최신 Codex 릴리스를 설치합니다. 수명 주기 서버에는 Codex 0.154.0 이상이 필요합니다. 릴리스를 고정하려면 `CODEX_NON_INTERACTIVE=1`의 `CODEX_RELEASE=` 옆에를 추가합니다`Dockerfile`. ## 8단계: 정리 세션을 삭제하려면 해당 세션에 대한 클라이언트`--delete`의 마지막 실행에를 추가합니다. 그런 다음 프로젝트의 리소스를 제거하고를 배포하여 런타임, 실행 역할 및 스택을 삭제합니다. ``` agentcore remove all agentcore deploy ``` 배포는 다음 리소스를 삭제하지 않습니다. + 런타임, 이미지를 빌드하는 CodeBuild 프로젝트 및 빌드를 시작하는 Lambda 함수의 CloudWatch Logs 로그 그룹입니다. + Amazon ECR 리포지토리의 AWS KMS 키입니다. 키는 **삭제 보류** 중 상태로 30일 동안 유지된 다음 AWS KMS가 삭제합니다. + 첫 번째 배포가 계정 및 리전을 부트스트래핑한 경우 `CDKToolkit` 스택입니다. 다른 AWS CDK 앱은이 스택을 사용할 수 있습니다. 다른 앱이 사용하지 않는 경우에만 삭제합니다. + 6단계의 트랜잭션 검색 설정입니다. + 3단계에서 `client.py` 생성한 세션 역할입니다. 세션 역할을 삭제하려면 다음 명령을 실행합니다. ``` aws iam delete-role-policy --role-name BmaSessionRole- --policy-name BmaSession aws iam delete-role --role-name BmaSessionRole- ``` 로그 그룹을 찾으려면 다음 명령을 실행합니다. 그런 다음 각 로그 그룹을 삭제합니다. ``` aws logs describe-log-groups --log-group-name-prefix /aws/bedrock-agentcore/runtimes/_- --query 'logGroups[].logGroupName' aws logs describe-log-groups --log-group-name-prefix /aws/codebuild/AgentCore--- --query 'logGroups[].logGroupName' aws logs describe-log-groups --log-group-name-prefix /aws/lambda/AgentCore- --query 'logGroups[].logGroupName' aws logs delete-log-group --log-group-name ``` 다음 값을 바꿉니다. + `` - 프로젝트의 이름입니다. 1단계에서는 입니다`MyManagedAgent`. + `` - 에이전트의 이름입니다. 1단계에서는 이기도 합니다`MyManagedAgent`. + `` -의 배포 대상 이름입니다`agentcore/aws-targets.json`. 기본값은 `default`입니다. CodeBuild 이름에서 프로젝트 이름의 각 밑줄(`_`)과 대상 이름이 하이픈()으로 변경됩니다`-`. 다음 예제와 같이 Lambda 로그 그룹의 이름이 단축됩니다. ``` /aws/lambda/AgentCore-MyManagedAgent--ApplicationAgentMyManage- ``` 명령은 리전에 있는 모든 AgentCore CLI 프로젝트의 Lambda 로그 그룹을 나열합니다. 프로젝트의 로그 그룹만 삭제합니다. 게이트웨이 또는 메모리와 같은 다른 리소스를 프로젝트에 추가한 경우 배포에서 해당 리소스가 삭제되었는지 확인합니다. ## 관련 리소스 + [AgentCore CLI 사용](runtime-permissions.md#runtime-permissions-cli) + [수명 주기 설정 구성](runtime-lifecycle-settings.md) + [AgentCore 런타임에 대한 파일 시스템 구성](runtime-filesystem-configurations.md) + [VPC용 AgentCore 구성](agentcore-vpc.md) + [런타임 인스턴스 및 용량 공급자](runtime-instances.md) + [Amazon Bedrock AgentCore 에이전트의 관찰성 데이터 보기](observability-view.md)