AgentCore Harness 개요

완성된 에이전트, 남은 배포

Runtime 커스텀 배포가 요구하는 것들 — 전부 개발자의 몫

Managed Agent Harness

에이전트를 "코드"가 아니라 "스펙"으로 정의 — 실행은 AgentCore 소유

하네스란 무엇인가 — Agent = Model + Harness

모델을 감싸는 나머지 전부 — 도구·메모리·컨텍스트·샌드박스·오케스트레이션·서빙을 누가 소유하는가의 문제

같은 에이전트, 두 가지 배포 방식

Runtime과 Harness — 정의·오케스트레이션·배포·변경의 구조적 차이

Harness API

선언(CreateHarness)과 호출(InvokeHarness)의 2단 구조

Harness 라이프사이클 — Create · Invoke · Update

컨트롤 플레인에서 선언, 데이터 플레인에서 호출, 다시 컨트롤 플레인에서 갱신

버전과 엔드포인트

UpdateHarness가 쌓는 기록과, 호출이 들어오는 진입점 — Runtime과 같은 운영 문법

컨트롤 플레인 vs 데이터 플레인

boto3 서비스명이 다름 — 바꿔 쓰면 API를 찾지 못하는 함정

CreateHarness — 최소 선언

이름 + IAM 역할 — 파라미터 2개로 생성되는 에이전트

핵심 포인트

harnessName

영숫자+밑줄, 최대 40자 — 생성 후 변경 불가

executionRoleArn

Harness가 리소스에 접근할 IAM 역할 — 필수 2개 중 하나

기본 모델

모델 미지정 시 Claude Sonnet 4.6 자동 적용

빌트인 도구

도구 미지정 시 shell + file_operations 자동 포함

코드

import boto3

# 생성은 컨트롤 플레인 — bedrock-agentcore-control
client = boto3.client('bedrock-agentcore-control')

# 최소 선언 2개 — 이름 + IAM 역할만으로 에이전트 생성
response = client.create_harness(
    harnessName='helpdesk_harness',
    executionRoleArn='arn:aws:iam::123456789012:role/HarnessRole',
)

# 모델 미지정 → Claude Sonnet 4.6 · 도구 미지정 → 빌트인 자동 포함
print(response['harnessArn'])

InvokeHarness — 스트리밍 호출

세션 ID로 대화 유지, 응답은 토큰 단위 스트림으로 수신

핵심 포인트

runtimeSessionId

33~100자 필수 — 짧으면 ValidationException, UUID(36자) 권장

세션 유지

같은 ID로 재호출하면 이전 대화 컨텍스트 유지, 새 ID면 새 세션

messages

Converse 형식 — role + content 배열

response['stream']

이벤트 스트림 — contentBlockDelta의 delta.text로 텍스트 수신, messageStop에 stopReason

toolResultMetadata

MCP 도구 결과 메타데이터 전용 델타 채널 — 텍스트 델타와 별도 이벤트로 스트리밍 수신

코드

import boto3, uuid

# 호출은 데이터 플레인 — bedrock-agentcore
client = boto3.client('bedrock-agentcore')

# runtimeSessionId — 33~100자 필수, UUID(36자) 사용 권장
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=str(uuid.uuid4()),
    # messages — Converse 형식 (role + content 배열)
    messages=[{'role': 'user', 'content': [{'text': 'VPN 연결이 안 됩니다'}]}],
)

# 이벤트 스트림 — contentBlockDelta에서 텍스트 추출
for event in response['stream']:
    if 'contentBlockDelta' in event:
        delta = event['contentBlockDelta']['delta']
        print(delta.get('text', ''), end='')

워크플로 속의 Harness — Step Functions

InvokeHarness를 워크플로의 한 스텝으로 — 문서 분류·추출 같은 추론 태스크를 파이프라인에 삽입

CLI로 같은 일 — create · deploy · invoke

API가 정의라면 CLI는 지름길 — 위저드가 스펙 작성을 대신하는 경로

선언 스펙

에이전트를 이루는 여섯 조각 — 전부 CreateHarness의 파라미터

선언 스펙의 뼈대

코드로 만들던 모든 것이 CreateHarness의 파라미터 트리로 — 필수는 단 두 개, 나머지는 전부 선택

모델 소스 4종 — 멀티 프로바이더 선언

model은 Tagged Union — 4종 소스 중 하나만 지정, 미지정 시 Claude Sonnet 4.6

도구 선언 — type 5종 + 빌트인

설정 없이 오는 빌트인부터, 관리형 서비스 연결과 직접 연결까지 — tools 배열의 type이 경로를 결정

Skills — 선언 스펙에 지식 주입

도구가 "할 수 있는 일"이라면 Skills는 "알고 있는 것" — Agent Skills 표준 기반 지식 패키지

핵심 포인트

Agent Skills 표준

Kiro·Claude Code 등 코딩 에이전트와 같은 형식 — SKILL.md 하나를 양쪽에서 재사용

awsSkills · paths

AWS 큐레이티드 카탈로그를 paths 글롭(core-skills/* 등)으로 골라 활성화

git · s3 · path

태그드 유니언 최상위 키로 조직 자체 Skills 연결 — git은 url 필수, path·auth 선택

Harness 전용

Gateway·Runtime 미지원 — 필요할 때만 로드되어 컨텍스트 절약

코드

# 카탈로그에서 골라 쓰기 — paths 글롭으로 활성화
skills=[{'awsSkills': {'paths': ['core-skills/*']}}]

# 조직 자체 Skills — 태그드 유니언 최상위 키 (s3·path도 동일 구조)
skills=[{'git': {'url': 'https://github.com/org/skills.git',
                 'path': 'skills/'}}]

SKILL.md — 코딩 에이전트와 한 파일

개발 때 Kiro가 쓰던 스킬을 프로덕션 에이전트가 그대로 쓰는 구조

핵심 포인트

구성 4섹션

Description · Instructions · Knowledge · Workflow — 마크다운 한 장

코딩 에이전트용

.kiro/skills/{이름}/SKILL.md로 저장하면 Kiro·Claude Code가 로드

프로덕션용

같은 파일을 skills의 git·s3 소스로 연결하면 Harness가 로드

운영 팁

스킬 리포 하나를 조직 표준으로 — 개발과 프로덕션이 같은 지식으로 움직임

SKILL.md

# order-domain/SKILL.md

## Description
고객 주문 처리 에이전트를 위한 도메인 지식

## Instructions
- 환불은 결제 수단 기준 3영업일 안내
- 주문 변경은 배송 시작 전까지만 허용

## Knowledge
- 주문 상태: CREATED → PAID → SHIPPED → DONE

## Workflow
1. 주문 조회 → 2. 정책 확인 → 3. 처리·안내

나머지 조각 — 컨텍스트 · 환경 · 인증

긴 대화와 특수 의존성, 호출 통제까지 — 전부 CreateHarness 파라미터로 선언

선언 스펙 전체 — 한 번에 선언

다섯 계층 전부 create_harness 한 호출의 파라미터 — 필수는 맨 아래 정체성 2개뿐

호출 시점 정책 — Per-invocation Override

재배포 없이, 이번 호출만 다른 모델·프롬프트·도구로 실행

핵심 포인트

최상위 파라미터

별도 override 객체 없음 — InvokeHarness에 직접 전달

model

모델 디커플링 — 세션 중간에 전환해도 컨텍스트 유지

allowedTools

이번 호출에서 쓸 도구를 화이트리스트로 제한

범위

model·systemPrompt·allowedTools 외에 tools·skills·actorId·실행 상한도 지정 가능

코드

# 재배포 없이 이번 호출만 — override 객체 없이 최상위 파라미터로
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    messages=[{'role': 'user', 'content': [{'text': '요약해주세요'}]}],
    # model — 이번 호출만 다른 모델 (세션 중간 전환에도 컨텍스트 유지)
    model={'bedrockModelConfig': {'modelId': 'us.anthropic.claude-opus-4-8'}},
    # systemPrompt — 이번 호출만 다른 역할·지시
    systemPrompt=[{'text': '짧게 3줄로 요약합니다.'}],
    # allowedTools — 나열된 도구만 허용하는 화이트리스트
    allowedTools=['shell'],
)

선택 기준

하나로 수렴하는 질문 — 커스텀 오케스트레이션의 필요 여부

Runtime vs Harness — 각자의 자리

어느 쪽이 낫냐가 아니라, 어떤 요구에 어느 쪽이 맞느냐의 문제

선택 가이드 — 두 번의 질문

커스텀 오케스트레이션 여부에서 시작해 배포 형태까지 내려가는 결정 트리

하이브리드 경로 — 선언으로 시작, 코드로 확장

갈림길은 일방통행이 아님 — agentcore export가 끊는 락인