주메뉴 바로가기 본문 바로가기

알림

콘솔 이동 시 로그인이 필요합니다.

로그인하시겠습니까?

아니요 예

닫기

주문 불가 알림

주문권한이 없습니다.

콘솔에 접근할 수 없는 계정입니다.

확인

닫기

알림

신용카드 등록이 필요합니다.

신용카드 등록 페이지로 이동하시겠습니까?

아니요 예

닫기
AX Tech
img

에이전트 흐름을 멈추고 사람에게 넘기는 Step Functions 콜백 패턴

img 이용원
| 2026.11.06
  • AWS
  • Bedrock
  • GenerativeAI

이번 10편에서는 에이전트가 스스로 처리하면 안 되는 판단을 어떻게 사람에게 넘기고, 사람이 응답할 때까지 흐름을 멈춰 두었다가 다시 이어가는지를 다룹니다.

에이전트 흐름을 멈추고 사람에게 넘기는 Step Functions 콜백 패턴



 

고객이 "노트북 환불해 주세요"라고 말했습니다. 에이전트는 9편에서 연결한 Knowledge Bases를 뒤져 규정상 환불이 가능하다는 것까지 확인했습니다. 그런데 금액이 큽니다. 콜센터에서 상담원이 하던 시절이라면 "잠시만요, 팀장님 확인 받겠습니다"라고 말한 뒤 내부 메신저로 승인을 요청했을 겁니다.

에이전트에게는 그 "잠시만요" 뒤에 기다리는 구조가 없습니다. 잘못된 환불은 되돌리기 어렵고, 고액 건은 감사 대상이기도 합니다. 그렇다고 모든 요청을 사람에게 돌리면 에이전트를 둔 의미가 사라집니다. 필요한 것은 특정 조건일 때만 흐름을 멈추고 사람에게 넘기는 구조입니다.

이 글에서는 Step Functions의 waitForTaskToken 패턴으로 그 구조를 만듭니다. 에이전트가 환불 승인 워크플로를 시작하면 Step Functions가 토큰을 발급하고 멈춥니다. 승인자가 토큰과 함께 승인 또는 거부를 보내면 그때 흐름이 다시 이어집니다.


3줄 요약

  • waitForTaskToken 패턴은 대기 중 상태 전환이 없으므로 며칠을 기다려도 대기 자체에 추가 비용이 발생하지 않습니다.
  • HeartbeatSeconds 또는 TimeoutSeconds를 설정하지 않으면 태스크가 최대 1년까지 응답 없이 멈추고, 이 한도는 변경할 수 없는 하드 쿼터입니다.
  • ResultPath를 지정하지 않으면 Task와 Catch 모두 결과가 원본 입력을 덮어씁니다. 승인이 떨어져도 주문 ID와 금액이 사라져서 정작 환불을 실행할 수 없습니다.


검증 환경


 

1. 왜 에이전트 흐름에 사람이 끼어야 하는가

3편에서 에이전트에 주문 조회·배송 조회 도구를 달았고, 9편에서 환불 규정 문서까지 연결했습니다. 에이전트는 이제 "이 상품 환불되나요?"에 규정을 근거로 답합니다. 그러나 규정을 아는 것과 실행해도 되는 것은 다릅니다.

고액 환불이 대표적입니다. 규정상 환불 가능하더라도 금액이 일정 선을 넘으면 팀장이나 운영 담당자가 건별로 확인해야 합니다. 사람 상담원이 하던 시절에는 "잠시만요, 확인 받겠습니다"라고 말한 뒤 내부 메신저로 승인을 요청했습니다. 에이전트도 같은 일을 해야 하는데, 에이전트에게는 "잠시만요" 뒤에 기다리는 구조가 없습니다.

여기서 두 가지 요구가 생깁니다. 하나는 에이전트 흐름을 특정 지점에서 멈추는 것이고, 다른 하나는 사람이 판단을 내린 뒤 그 결과를 에이전트에게 돌려주는 것입니다. 단순히 멈추기만 하면 안 됩니다. 승인자가 하루 뒤에 볼 수도 있고, 주말을 넘길 수도 있습니다. 그 사이에 에이전트가 리소스를 잡고 있으면 비용이 쌓이고, 타임아웃으로 끊기면 고객에게 다시 처음부터 안내해야 합니다.

Step Functions의 waitForTaskToken 패턴이 이 문제를 풀어 줍니다. waitForTaskToken은 상태 머신이 태스크를 시작할 때 고유한 토큰을 발급하고, 외부에서 그 토큰과 함께 SendTaskSuccess 또는 SendTaskFailure를 호출할 때까지 실행을 멈춰 두는 콜백 방식입니다. Standard Workflow는 상태 전환 횟수로 과금되는데, 대기 중에는 전환이 일어나지 않으므로 며칠을 기다려도 대기 자체에 추가 비용이 들지 않습니다.


2. 아키텍처


[그림 1] 에이전트 → Step Functions → 승인자 → 에이전트 재개 전체 구성


전체 흐름은 네 구성요소가 이어받는 구조입니다.


 

요청이 흐르는 순서를 따라가 보겠습니다. 고객이 "노트북 환불해 주세요"라고 말하면 에이전트가 금액을 확인하고 고액 기준을 넘는다고 판단합니다. 에이전트는 start_refund_approval 도구를 호출해 Step Functions 실행을 시작합니다. 상태 머신은 승인 Lambda를 waitForTaskToken 모드로 부르면서 토큰을 함께 넘깁니다. Lambda는 토큰과 환불 정보를 승인자에게 전달하고 즉시 반환합니다. 전달 방식은 Slack이든 이메일이든 내부 시스템이든 상관없습니다. 상태 머신은 여기서 멈춥니다.

승인자가 판단을 내리면 승인 Lambda가 토큰과 함께 SendTaskSuccess(승인) 또는 SendTaskFailure(거부)를 호출합니다. 상태 머신이 다시 움직이고, 결과를 에이전트에게 돌려줍니다. 에이전트는 승인이면 환불을 진행하고, 거부면 고객에게 사유를 안내합니다.


3. waitForTaskToken을 고른 이유

에이전트 흐름을 멈추고 외부 응답을 기다리는 방법은 세 가지가 있습니다.


[그림 2] waitForTaskToken 콜백 흐름 — 토큰 발급, 대기, SendTaskSuccess/Failure 분기



[그림 3] 대기 패턴 비교 — 폴링·동기 Lambda 대기·waitForTaskToken의 비용과 대기 한도


환불 승인은 당일에 끝날 수도 있지만 주말을 넘기거나 담당자가 휴가 중이면 며칠이 걸립니다. 동기 Lambda 대기는 실행 시간 한도가 있어 승인자가 주말을 넘기는 상황에 쓸 수 없습니다. 폴링은 시간 제한이 느슨하지만 조회할 때마다 비용이 쌓이고, 상태를 어딘가에 저장하고 꺼내는 코드를 직접 짜야 합니다.

waitForTaskToken은 Standard Workflow의 최대 실행 시간인 1년까지 대기할 수 있고, 대기 중에는 상태 전환이 일어나지 않으므로 과금 기준인 전환 횟수가 늘지 않습니다. 따라서 폴링 간격을 고민하거나 상태 저장소를 따로 둘 필요가 없습니다. 구현도 단순합니다. 상태 머신이 토큰을 발급하고, 외부에서 그 토큰으로 SendTaskSuccess 또는 SendTaskFailure를 호출하면 끝입니다.

이 패턴에서 $$.Task.Token이라는 표기가 나옵니다. 앞의 $$는 Step Functions의 Context 객체에 접근하는 경로이고, Task.Token은 현재 실행 중인 태스크에 발급된 고유 토큰을 가리킵니다. 이 토큰을 Lambda에 넘기면 Lambda가 나중에 그 토큰으로 상태 머신을 깨우는 구조입니다.


4. 구현


[그림 4] 구현 순서 — IAM 역할, 상태 머신, 승인 Lambda, 에이전트 도구 등록 단계별 산출물


네 단계를 순서대로 밟습니다. IAM 실행 역할을 만들고, 상태 머신을 정의하고, 승인 처리 Lambda를 올리고, 에이전트에 도구로 등록합니다. 먼저 이후 명령에서 반복할 값을 변수로 선언합니다.

ACCOUNT=<your-account-id>
REGION=ap-northeast-2
SFN_ROLE_NAME=support-approval-sfn-role
SM_NAME=support-refund-approval
APPROVAL_FN_NAME=support-approval-handler
APPROVAL_FN_ROLE=support-approval-lambda-role

<your-account-id>는 여러분의 AWS 계정 ID입니다. aws sts get-caller-identity --query Account --output text로 확인합니다.

승인 Lambda가 쓸 IAM 실행 역할이 아직 없다면 아래 명령으로 만듭니다. 이미 갖고 있다면 이 블록을 건너뛰고 APPROVAL_FN_ROLE_ARN 변수에 기존 역할 ARN을 넣으면 됩니다.

cat > lambda-trust-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF
aws iam create-role \
  --role-name "${APPROVAL_FN_ROLE}" \
  --assume-role-policy-document \
    file://lambda-trust-policy.json

기본 Lambda 실행 권한을 붙입니다. CloudWatch Logs에 로그를 남기려면 이 정책이 필요합니다.

aws iam attach-role-policy \
  --role-name "${APPROVAL_FN_ROLE}" \
  --policy-arn \
    arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

이 Lambda는 상태 머신에 콜백해야 하므로 states:SendTaskSuccess와 states:SendTaskFailure 권한도 필요합니다.

cat > lambda-sfn-callback-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "states:SendTaskSuccess",
        "states:SendTaskFailure"
      ],
      "Resource": "*"
    }
  ]
}
EOF
aws iam put-role-policy \
  --role-name "${APPROVAL_FN_ROLE}" \
  --policy-name sfn-callback \
  --policy-document \
    file://lambda-sfn-callback-policy.json

응답의 Role.Arn을 변수에 담습니다. 4.3절에서 Lambda를 만들 때 넘길 값입니다.

APPROVAL_FN_ROLE_ARN=$(aws iam get-role \
  --role-name "${APPROVAL_FN_ROLE}" \
  --query 'Role.Arn' --output text)


4.1 Step Functions 실행 역할 만들기

상태 머신이 Lambda를 호출하려면 IAM 역할이 필요합니다. 이 역할의 신뢰 정책에는 Step Functions 서비스 주체를 넣는데, 리전별 엔드포인트 states.{region}.amazonaws.com 또는 글로벌 엔드포인트 states.amazonaws.com 중 하나를 지정합니다. 여기서는 리전별 엔드포인트를 씁니다. 글로벌로 열면 다른 리전에서도 이 역할을 빌릴 수 있어 범위가 넓어지기 때문입니다.

cat > sfn-trust-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "states.${REGION}.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF

이 파일로 역할을 만듭니다.

aws iam create-role \
  --role-name "${SFN_ROLE_NAME}" \
  --assume-role-policy-document \
    file://sfn-trust-policy.json

응답의 Role.Arn을 변수에 담습니다. 다음 절에서 상태 머신을 만들 때 넘길 값입니다.

SFN_ROLE_ARN=$(aws iam get-role \
  --role-name "${SFN_ROLE_NAME}" \
  --query 'Role.Arn' --output text)

이제 이 역할에 Lambda 호출 권한을 붙입니다. 상태 머신이 승인 Lambda를 Invoke할 수 있어야 합니다.

FN_ARN="arn:aws:lambda:${REGION}:${ACCOUNT}"
FN_ARN="${FN_ARN}:function:${APPROVAL_FN_NAME}"

cat > sfn-lambda-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "lambda:InvokeFunction",
      "Resource": "${FN_ARN}"
    }
  ]
}
EOF
aws iam put-role-policy \
  --role-name "${SFN_ROLE_NAME}" \
  --policy-name sfn-invoke-approval \
  --policy-document file://sfn-lambda-policy.json

역할이 만들어지고 정책이 붙었습니다. IAM 전파에 수 초가 걸리므로 바로 다음 명령이 실패하면 잠시 뒤 다시 시도합니다.


4.2 상태 머신 정의

상태 머신은 네 상태로 구성됩니다. 승인 요청을 보내는 RequestApproval, 승인을 처리하는 Approved, 거부를 처리하는 Rejected, 무응답 타임아웃을 처리하는 TimedOut입니다.

핵심은 RequestApproval 상태입니다. Resource에 .waitForTaskToken 접미사를 붙이면 Step Functions가 Lambda를 호출할 때 토큰을 함께 발급하고, 외부에서 그 토큰으로 응답할 때까지 실행을 멈춥니다. 토큰은 Parameters.Payload 안에 "token.$": "$$.Task.Token"으로 넣습니다. $$.Task.Token에서 $$가 Context 객체를 가리키고, Task.Token이 현재 태스크의 고유 토큰을 꺼내는 경로입니다.

HeartbeatSeconds를 259200(3일)으로 설정합니다. 이 값을 빼면 태스크가 최대 1년까지 응답 없이 멈출 수 있고, 이 1년 한도는 변경할 수 없는 하드 쿼터입니다. 3일이면 주말을 넘기기에 충분하고, 그 안에 응답이 없으면 좀비 실행으로 남는 대신 타임아웃으로 정리됩니다.

ResultPath는 Task와 Catch 양쪽에 지정합니다. 지정하지 않으면 기본값이 $여서 결과가 원본 입력 전체를 덮어씁니다. Catch 쪽은 에러를 다루는 자리라 눈에 띕니다. 그러나 Task 쪽은 평소 잘 돌 때 지나가는 길목이어서 빠뜨려도 바로 드러나지 않습니다. 그래서 Task에는 $.approval, Catch에는 $.error로 지정합니다. 그러면 콜백 결과와 에러 정보가 각각 그 필드로 들어가고 원래 요청 데이터는 그대로 남습니다.

Catch는 두 갈래로 나눕니다. States.Timeout은 아무도 응답하지 않은 것이고 거부는 사람이 판단한 것이어서, 고객에게 할 말이 다릅니다. 한 갈래로 묶으면 3일간 방치된 건에 환불 거부를 안내하게 됩니다. 구체적인 오류 이름을 앞에 두면 그쪽이 먼저 걸립니다.

APPROVAL_FN_ARN="arn:aws:lambda:${REGION}"
APPROVAL_FN_ARN="${APPROVAL_FN_ARN}:${ACCOUNT}"
APPROVAL_FN_ARN="${APPROVAL_FN_ARN}:function:${APPROVAL_FN_NAME}"

이 ARN을 상태 머신 정의에 넣습니다. heredoc 안에서 변수가 치환되도록 따옴표를 빼고 << EOF를 씁니다.

cat > state-machine.json << EOF
{
  "Comment": "고액 환불 승인 워크플로",
  "StartAt": "RequestApproval",
  "States": {
    "RequestApproval": {
      "Type": "Task",
      "Resource":
        "arn:aws:states:::lambda:invoke.waitForTaskToken",
      "Parameters": {
        "FunctionName": "${APPROVAL_FN_ARN}",
        "Payload": {
          "token.\$": "\$\$.Task.Token",
          "order_id.\$": "\$.order_id",
          "amount.\$": "\$.amount",
          "reason.\$": "\$.reason"
        }
      },
      "HeartbeatSeconds": 259200,
      "ResultPath": "\$.approval",
      "Catch": [
        {
          "ErrorEquals": ["States.Timeout"],
          "Next": "TimedOut",
          "ResultPath": "\$.error"
        },
        {
          "ErrorEquals": ["States.ALL"],
          "Next": "Rejected",
          "ResultPath": "\$.error"
        }
      ],
      "Next": "Approved"
    },
    "Approved": {
      "Type": "Pass",
      "Result": "approved",
      "ResultPath": "\$.decision",
      "End": true
    },
    "Rejected": {
      "Type": "Pass",
      "Result": "rejected",
      "ResultPath": "\$.decision",
      "End": true
    },
    "TimedOut": {
      "Type": "Pass",
      "Result": "timed_out",
      "ResultPath": "\$.decision",
      "End": true
    }
  }
}
EOF

$ 앞에 백슬래시를 붙인 것은 셸이 변수로 해석하는 것을 막기 위해서입니다. ${APPROVAL_FN_ARN}만 치환되고 나머지 $는 JSON 경로 표기 그대로 파일에 들어갑니다.

Retry와 Catch가 모두 있을 때 Step Functions는 Retry를 먼저 적용하고, 재시도가 모두 실패한 뒤에야 Catch로 넘어갑니다. 이 정의에서는 승인 대기 자체를 재시도할 이유가 없으므로 Retry를 빼고 Catch만 둡니다.

이제 상태 머신을 생성합니다.

export SM_ARN=$(aws stepfunctions create-state-machine \
  --name "${SM_NAME}" \
  --definition file://state-machine.json \
  --role-arn "${SFN_ROLE_ARN}" \
  --type STANDARD \
  --query 'stateMachineArn' --output text)

응답에서 stateMachineArn을 꺼내 SM_ARN에 담았습니다. 이 값이 에이전트 도구에서 실행을 시작할 때 넘길 대상입니다. CreateStateMachine의 name은 최대 80자이고, definition은 최대 1,048,576자까지 허용됩니다.


4.3 승인 처리 Lambda 만들기

이 Lambda는 콜백 전용입니다. 승인자의 판단(승인 또는 거부)과 토큰을 받아 SendTaskSuccess 또는 SendTaskFailure를 호출하는 것이 전부입니다. 승인자에게 알림을 보내는 일은 상태 머신의 별도 상태나 다른 Lambda에서 처리합니다. Slack 메시지든 이메일이든 이 Lambda 밖에서 다룹니다. 토큰을 DynamoDB에 저장해 두고 승인 UI에서 꺼내 쓰는 방식이 일반적인데, 알림 채널 구성은 이 글의 범위 밖입니다.

SendTaskFailure를 호출할 때 error 필드는 최대 256자, cause 필드는 최대 32,768자입니다. cause가 error의 128배이므로 사람이 작성하는 거부 사유는 cause에 담고 error에는 REJECTED 같은 짧은 분류 코드만 넣습니다.

아래가 콜백 로직입니다.

# approval_handler.py
import boto3
import json

sfn = boto3.client("stepfunctions")

def lambda_handler(event, context):
    token = event["token"]
    decision = event["decision"]

    if decision == "approve":
        sfn.send_task_success(
            taskToken=token,
            output=json.dumps({
                "approved": True,
                "approved_by": event.get(
                    "approver", "unknown"
                )
            })
        )
    else:
        sfn.send_task_failure(
            taskToken=token,
            error="REJECTED",
            cause=event.get(
                "cause", "승인 거부"
            )
        )

    return {
        "statusCode": 200,
        "body": decision
    }

taskToken은 필수이며 최소 1자, 최대 2,048자의 문자열입니다. 상태 머신이 발급한 토큰을 그대로 넘기면 됩니다.

이 파일을 zip으로 묶어 Lambda를 배포합니다.

zip approval_handler.zip approval_handler.py
aws lambda create-function \
  --function-name "${APPROVAL_FN_NAME}" \
  --runtime python3.12 \
  --role "${APPROVAL_FN_ROLE_ARN}" \
  --handler approval_handler.lambda_handler \
  --zip-file fileb://approval_handler.zip

APPROVAL_FN_ROLE_ARN은 4절 도입부에서 만든 Lambda 실행 역할의 ARN입니다. 이 역할에 states:SendTaskSuccess와 states:SendTaskFailure 권한이 이미 붙어 있으므로 Lambda가 상태 머신에 콜백할 수 있습니다.


4.4 에이전트에 승인 도구 등록하기

2편에서 배포한 상담 에이전트가 Step Functions 실행을 시작할 수 있어야 합니다. 에이전트 코드에 도구를 하나 추가합니다. 이 도구는 boto3로 start_execution을 호출하는 것이 전부입니다.

에이전트의 실행 역할에 states:StartExecution 권한이 있어야 합니다. 2편에서 만든 support-agent-runtime-role에 아래 정책을 붙입니다.

cat > agent-sfn-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "states:StartExecution",
      "Resource": "${SM_ARN}"
    }
  ]
}
EOF
aws iam put-role-policy \
  --role-name support-agent-runtime-role \
  --policy-name agent-start-approval \
  --policy-document file://agent-sfn-policy.json

에이전트 코드에서 도구를 정의합니다. strands는 2편 app/requirements.txt에 strands-agents로 이미 들어 있습니다. 다만 컨테이너에 넣기 전에 이 도구만 로컬에서 돌려 보려면 따로 설치합니다.

pip install strands-agents

Strands는 평범한 함수에 @tool 데코레이터를 붙이면 도구로 만들어 줍니다. 데코레이터가 docstring과 타입 힌트를 읽어 도구 명세를 만드는데, 첫 문단이 도구 설명이 되고 Args 절이 파라미터 설명이 됩니다. 모델은 이 글만 보고 언제 부를지 판단합니다.

승인이 필요한 최소 금액은 업무 규칙이므로 코드에 박지 않고 환경 변수로 받습니다. 판단을 모델에게만 맡기지 않고 코드가 한 번 더 막는 구조입니다. 모델이 잘못 읽어도 기준 이하 금액은 워크플로를 타지 않습니다.

# app/approval_tool.py
import boto3
import json
import os

from strands import tool

sfn = boto3.client("stepfunctions")
SM_ARN = os.environ["SM_ARN"]
THRESHOLD = int(os.environ["APPROVAL_THRESHOLD"])


@tool
def start_refund_approval(
    order_id: str,
    amount: int,
    reason: str
) -> str:
    """환불에 사람의 승인이 필요한지 판단해 워크플로를 시작합니다.
    환불을 실행하기 전에 모든 환불 요청에 대해 호출합니다.
    기준 금액 이하면 승인 없이 처리해도 된다고 돌려줍니다.

    Args:
        order_id: 환불 대상 주문 ID
        amount: 환불 금액 (원)
        reason: 환불 사유
    """
    if amount <= THRESHOLD:
        return json.dumps({
            "approval_required": False,
            "status": "승인 없이 처리할 금액입니다"
        })
    resp = sfn.start_execution(
        stateMachineArn=SM_ARN,
        input=json.dumps({
            "order_id": order_id,
            "amount": amount,
            "reason": reason
        })
    )
    return json.dumps({
        "approval_required": True,
        "execution_arn": resp["executionArn"],
        "status": "승인 요청이 접수되었습니다"
    })

2편 app/main.py에서 만든 Agent에 이 도구를 넘깁니다. 8편에서 Code Interpreter 도구를 붙인 것과 같은 자리입니다. MODEL_ID는 2편에서 쓴 값 그대로입니다.

# app/main.py 의 Agent 에 tools 를 더한다
from strands import Agent
from strands.models import BedrockModel

from approval_tool import start_refund_approval

agent = Agent(
    model=BedrockModel(model_id=MODEL_ID),
    tools=[start_refund_approval],
)

도구 코드를 더했으므로 이미지를 다시 빌드해 올려야 합니다. 빌드·푸시 절차는 9편에서 에이전트를 다시 올릴 때와 같고 태그만 올립니다. 그다음 Runtime이 새 이미지와 환경 변수를 쓰도록 갱신합니다. APPROVAL_THRESHOLD에는 조직의 환불 승인 규정에서 정한 금액을 넣습니다. 규정이 없다면 운영 담당자와 먼저 합의하는 것이 코드보다 앞섭니다. 아래 값은 예시입니다.

RUNTIME_ID=$(aws bedrock-agentcore-control list-agent-runtimes \
  --query 'agentRuntimes[?agentRuntimeName==
    `support_agent_runtime`].agentRuntimeId' \
  --output text)

ECR_REPO=support-agent
IMAGE_TAG=approval-tool
ECR_URI="${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com"
CONTAINER_URI="${ECR_URI}/${ECR_REPO}:${IMAGE_TAG}"

export APPROVAL_THRESHOLD=300000

AGENT_ROLE_ARN="arn:aws:iam::${ACCOUNT}:role"
AGENT_ROLE_ARN="${AGENT_ROLE_ARN}/support-agent-runtime-role"

UpdateAgentRuntime의 필수 입력은 agentRuntimeId, agentRuntimeArtifact, roleArn 셋입니다. 환경 변수만 따로 넘기는 호출은 없으므로 artifact와 역할을 함께 다시 넘깁니다. --network-configuration도 넣습니다. 생략하면 2편에서 지정한 PUBLIC 모드가 유지되지 않을 수 있습니다.

cat > rt-artifact.json << EOF
{
  "containerConfiguration": {
    "containerUri": "${CONTAINER_URI}"
  }
}
EOF

cat > rt-network.json << EOF
{
  "networkMode": "PUBLIC"
}
EOF

cat > rt-env.json << EOF
{
  "SM_ARN": "${SM_ARN}",
  "APPROVAL_THRESHOLD": "${APPROVAL_THRESHOLD}"
}
EOF
aws bedrock-agentcore-control update-agent-runtime \
  --agent-runtime-id "${RUNTIME_ID}" \
  --role-arn "${AGENT_ROLE_ARN}" \
  --agent-runtime-artifact file://rt-artifact.json \
  --network-configuration file://rt-network.json \
  --environment-variables file://rt-env.json

에이전트가 이 도구를 호출하면 Step Functions 실행이 시작되고, 상태 머신은 RequestApproval 상태에서 토큰을 발급한 뒤 멈춥니다. 에이전트는 실행 ARN을 받아 고객에게 "승인 요청을 접수했습니다. 담당자 확인 후 안내드리겠습니다"라고 답할 수 있습니다.


5. 동작 확인


[그림 5] 동작 확인 — 고액 환불 요청부터 승인 후 에이전트 재개까지 요청·응답 흐름

고객이 "주문번호 ORD-001, 노트북 환불해 주세요"라고 요청한 상황을 재현합니다. 아래 요청의 금액은 4.4절에서 넣은 APPROVAL_THRESHOLD를 넘으므로 에이전트가 start_refund_approval 도구를 호출하고 승인 워크플로가 걸립니다. CLI로 같은 일을 해 보겠습니다.

EXEC_ARN=$(aws stepfunctions start-execution \
  --state-machine-arn "${SM_ARN}" \
  --input '{"order_id":"ORD-001","amount":500000,"reason":"단순 변심"}' \
  --query 'executionArn' --output text)

실행이 시작되면 상태 머신은 RequestApproval 상태에서 멈춥니다. 승인 Lambda가 토큰과 환불 정보를 받았지만 아직 아무도 승인하지 않은 상태입니다. 이 시점에서 상태를 확인합니다.

aws stepfunctions describe-execution \
  --execution-arn "${EXEC_ARN}" \
  --query 'status' --output text

RUNNING이 돌아옵니다. 상태 머신이 토큰 응답을 기다리며 멈춰 있다는 뜻입니다. 이 상태는 HeartbeatSeconds로 설정한 3일까지 유지됩니다.

토큰을 꺼내야 승인을 보낼 수 있습니다. 실행 이력에서 TaskScheduled 이벤트를 찾으면 그 안에 토큰이 들어 있습니다. get-execution-history의 parameters 필드는 JSON 문자열로 이중 직렬화되어 있으므로, 바깥 문자열을 먼저 파싱한 뒤 안쪽 객체에서 토큰을 꺼내야 합니다. 아래 명령 하나로 두 단계를 끝냅니다.

TASK_TOKEN=$(aws stepfunctions get-execution-history \
  --execution-arn "${EXEC_ARN}" \
  --query \
    'events[?type==`TaskScheduled`]
    .taskScheduledEventDetails
    .parameters' \
  --output text \
  | python3 -c "
import sys, json
raw = sys.stdin.read().strip()
outer = json.loads(raw)
inner = json.loads(outer) \
    if isinstance(outer, str) else outer
print(inner['Payload']['token'])
")

--output text가 돌려주는 값이 JSON 문자열일 수 있고 이미 파싱된 객체일 수도 있으므로, isinstance(outer, str) 분기로 두 경우를 모두 처리합니다. 실제 운영에서는 승인 Lambda가 첫 호출 시 이 토큰을 DynamoDB에 저장해 두고 승인 UI에서 꺼내 쓰는 구조가 됩니다. 다만 동작 확인 단계에서는 이력 조회로 충분합니다. 이제 승인자가 판단을 내린 상황으로 넘어갑니다.

승인 Lambda를 직접 호출해 승인을 보냅니다. 실제 운영에서는 Slack 봇이나 승인 UI가 이 Lambda를 부릅니다. 페이로드를 파일로 만들어 넘기면 셸의 개행·공백 처리 차이에 영향을 받지 않습니다.

cat > /tmp/approve_payload.json << EOF
{
  "token": "${TASK_TOKEN}",
  "decision": "approve",
  "approver": "김팀장"
}
EOF
aws lambda invoke \
  --function-name "${APPROVAL_FN_NAME}" \
  --payload file:///tmp/approve_payload.json \
  --cli-binary-format raw-in-base64-out \
  /dev/stdout

승인이 들어간 뒤 다시 실행 상태를 확인합니다.

aws stepfunctions describe-execution \
  --execution-arn "${EXEC_ARN}" \
  --query 'status' --output text

SUCCEEDED가 돌아옵니다. 출력은 JSON 문자열로 담기므로 꺼내서 펴 봅니다.

aws stepfunctions describe-execution \
  --execution-arn "${EXEC_ARN}" \
  --query 'output' --output text \
  | python3 -m json.tool
{
  "order_id": "ORD-001",
  "reason": "단순 변심",
  "approval": {
    "approved": true,
    "approved_by": "김팀장"
  },
  "decision": "approved"
}

무엇보다 주문 ID와 사유가 그대로 남아 있습니다. 콜백이 보낸 값은 approval에, 분기 결과는 decision에 들어갔습니다. RequestApproval에 ResultPath를 $.approval로 지정한 덕입니다. 이 자리를 비워 두면 콜백 출력이 입력 전체를 덮어써서 order_id가 사라지고, 승인은 받았는데 어느 주문을 환불할지 모르는 상태가 됩니다. 에이전트는 이 결과를 받아 환불을 진행하고 고객에게 "환불이 승인되었습니다"라고 안내합니다.

거부와 타임아웃은 갈라집니다. decision을 reject로 바꾸면 승인 Lambda가 SendTaskFailure를 호출하고 States.ALL Catch를 타고 Rejected로 넘어가 decision이 rejected가 됩니다. 아무도 응답하지 않으면 States.Timeout Catch가 먼저 걸려 TimedOut으로 가고 decision이 timed_out이 됩니다. 두 경로 모두 ResultPath가 $.error이므로 원본 입력은 남습니다. 고객에게 할 말은 다릅니다. 거부는 사유를 안내하고, 타임아웃은 다시 요청하도록 안내합니다.


6. 성능과 비용

Standard Workflow는 상태 전환 횟수로 과금됩니다. AWS 요금 페이지는 전환 수를 그래프의 노드 수로 세며 Start와 End를 포함합니다. 공식 예시에서 상태 두 개짜리 순차 워크플로가 4회로 계산됩니다. 위에서 만든 상태 머신도 승인 건 하나에 네 번입니다 — Start, RequestApproval, Approved(또는 Rejected·TimedOut), End입니다.


 

waitForTaskToken 대기 중에는 상태 전환이 일어나지 않습니다. 따라서 승인자가 하루 만에 응답하든 사흘 뒤에 응답하든 전환 횟수는 같습니다. 대기 시간이 비용에 영향을 주지 않는다는 뜻입니다. 폴링 방식이라면 조회할 때마다 Lambda 실행 비용이 쌓이는 것과 대조됩니다.

비용에 영향을 주는 것은 승인 건수입니다. 이 정의에서 건당 상태 전환은 4회이므로, 월 승인 건수에 4를 곱하면 전환 총량이 나오고 리전별 상태 전환 단가는 AWS Step Functions 요금 페이지에서 확인합니다.

승인 Lambda는 SendTaskSuccess 또는 SendTaskFailure 한 번 호출하고 끝나므로 실행 시간이 짧습니다. 특히 승인 도구 호출은 Gateway를 거치지 않고 boto3로 StartExecution을 직접 부르므로 MCP 도구 호출 지연과 별개입니다. 실제 지연은 StartExecution API 응답 시간에 달려 있고, 대기 시간은 사람의 판단 속도에 좌우됩니다. 결국 비용을 좌우하는 것은 Step Functions 전환 횟수보다 에이전트 쪽 모델 호출 비용입니다.


7. 운영 시 주의사항

HeartbeatSeconds 또는 TimeoutSeconds를 반드시 설정합니다

HeartbeatSeconds와 TimeoutSeconds를 모두 생략하면 태스크가 최대 1년까지 응답 없이 멈춥니다. 이 1년은 Standard Workflow의 최대 실행 시간이며 변경할 수 없는 하드 쿼터입니다. 승인자가 토큰을 잃어버리거나 퇴사하면 그 실행은 1년간 좀비로 남습니다. 단일 실행의 최대 이력 이벤트 수가 25,000개이므로 좀비 실행이 쌓이면 이력 슬롯을 점유하는 문제도 따라옵니다.

업무 특성에 맞는 값을 넣습니다. 환불 승인이 보통 당일에서 3일 안에 끝난다면 HeartbeatSeconds를 259,200(3일)으로 잡습니다. 그 안에 응답이 없으면 States.Timeout이 나므로, 4.2절처럼 Catch를 States.Timeout과 States.ALL 두 갈래로 나눠 타임아웃을 거부와 구분합니다. 한 갈래로 묶으면 아무도 보지 않은 건에 환불 거부를 안내하게 됩니다.

ResultPath를 Task와 Catch 양쪽에 지정합니다

ResultPath를 지정하지 않으면 기본값이 $입니다. 결과가 상태 입력 전체를 덮어쓰므로 주문 ID, 환불 금액, 사유가 모두 사라집니다. 이 결함은 거부 경로를 시험할 때는 잡히지 않습니다. Catch에 $.error를 넣어 두면 거부 흐름의 출력에 원본이 남아 있어 멀쩡해 보이기 때문입니다. 그러나 승인 흐름을 돌려 보면 출력에 order_id가 없고, 그때는 이미 승인이 떨어진 상태입니다. Task와 Catch 양쪽을 함께 지정하고, 시험도 승인·거부 두 경로를 모두 돌려 봅니다.

토큰 중복 사용을 막습니다

같은 토큰으로 SendTaskSuccess를 두 번 호출하면 두 번째는 TaskTimedOut이 납니다. 이름이 타임아웃이라 헷갈리는데, API 레퍼런스가 이 오류를 "토큰이 만료됐거나 토큰이 가리키는 태스크가 이미 닫힌 경우"로 정의합니다. 중복 호출은 뒤쪽에 해당합니다. 토큰 꼴 자체가 틀렸을 때는 InvalidToken입니다. 그러나 승인 UI에서 버튼을 두 번 누르는 일은 흔합니다. 승인 Lambda에서 토큰 사용 여부를 DynamoDB 같은 곳에 기록하고, 이미 사용된 토큰이면 중복 요청임을 알려주는 것이 안전합니다.

거부 사유는 cause 필드에 담습니다

SendTaskFailure의 error 필드는 최대 256자이고 cause 필드는 최대 32,768자입니다. cause가 error의 128배이므로 사람이 작성하는 거부 사유 텍스트는 cause에 넣고, error에는 REJECTED 같은 짧은 분류 코드만 넣습니다.

실행 이력 보존 기간을 확인합니다

Standard Workflow의 실행 이력은 실행 종료 후 90일간 보존됩니다. 실행 자체가 최대 1년 지속될 수 있으므로 실행 시작 시점 기준으로 최대 약 455일(365 + 90) 뒤까지 이력을 조회할 수 있습니다. 감사 로그 보존 요건이 이보다 길면 EventBridge나 S3로 이력을 별도 아카이빙해야 합니다.


8. 리소스 정리

의존성 역순으로 삭제합니다. 상태 머신이 역할을 참조하고 있으므로 상태 머신을 먼저 지웁니다.

aws stepfunctions delete-state-machine \
  --state-machine-arn "${SM_ARN}"
aws iam delete-role-policy \
  --role-name support-agent-runtime-role \
  --policy-name agent-start-approval
aws iam delete-role-policy \
  --role-name "${SFN_ROLE_NAME}" \
  --policy-name sfn-invoke-approval
aws iam delete-role \
  --role-name "${SFN_ROLE_NAME}"

승인 Lambda와 그 실행 역할도 지웁니다.

aws lambda delete-function \
  --function-name "${APPROVAL_FN_NAME}"
aws iam delete-role-policy \
  --role-name "${APPROVAL_FN_ROLE}" \
  --policy-name sfn-callback
aws iam detach-role-policy \
  --role-name "${APPROVAL_FN_ROLE}" \
  --policy-arn \
    arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
aws iam delete-role \
  --role-name "${APPROVAL_FN_ROLE}"


맺음말

이 글에서 만든 것은 에이전트가 혼자 처리하면 안 되는 판단을 사람에게 넘기고, 사람이 응답할 때까지 비용 없이 기다렸다가 결과에 따라 다음 동작을 이어가는 구조입니다. 서론에서 세운 문제 — 고액 환불처럼 사람 확인이 필요한 건을 에이전트가 어떻게 멈추고 기다리는가 — 를 waitForTaskToken 패턴이 풀었습니다.

이 구조가 맞는 경우와 맞지 않는 경우를 구분합니다. 승인 대기가 분 단위를 넘어 시간이나 일 단위로 갈 수 있고, 승인 건수가 월 수천 건 이하라면 waitForTaskToken이 가장 단순하고 비용도 낮습니다. 반면 대기가 항상 수 초 안에 끝나는 경우 — 예를 들어 자동화된 규칙 엔진이 즉시 판정하는 경우 — 에는 Step Functions를 거치는 것이 단계만 늘립니다. 에이전트 코드 안에서 직접 호출하는 편이 짧습니다.

운영에서 가장 자주 빠뜨리는 것은 HeartbeatSeconds 설정입니다. 빼면 좀비 실행이 1년간 남고, 그 1년은 하드 쿼터라 늘릴 수도 줄일 수도 없습니다. ResultPath도 마찬가지인데, Catch보다 Task 쪽을 더 자주 놓칩니다. 승인이 떨어진 뒤 주문 ID가 사라지면 정작 환불을 실행할 수 없습니다.

다음 11편에서는 Guardrails와 Policy로 에이전트가 없는 규정을 지어내거나 고객 정보를 흘리지 않게 막는 방법을 다룹니다.


참고 자료

img
이용원 | Cloud사업개발3팀

AWS Architect로서 AWS 파트너십 기술지원을 담당하고 있으며, 2026년 AWS All Star로 선정되어 Golden Jacket을 획득했습니다.