AgentCore

AgentCore

Amazon AgentCore에서 실행하는 AI 에이전트도 Confident AI로 추적하고 평가하고 싶을 때가 있어요. Amazon Bedrock AgentCore를 쓰면 몇 줄의 코드로 그대로 가능합니다. /invocations 요청 하나가 Observatory에서 하나의 트레이스로 나타나고, 그 안에서 실행한 프레임워크의 모델·도구·에이전트 스팬이 중첩되어 보여요. 배포한 에이전트가 처리하는 모든 턴과 성능을 한눈에 볼 수 있죠.

출처: 문서

본문

개요

Amazon Bedrock AgentCore는 AI 에이전트를 배포하고 확장하기 위한 AWS의 관리형 런타임입니다. Confident AI는 몇 줄의 코드로 AgentCore에서 실행되는 에이전트를 추적·평가할 수 있게 해 줘요 — 각 /invocations 요청이 Observatory에서 하나의 트레이스로 나타나고, 그 안에서 실행하는 프레임워크의 모델·도구·에이전트 스팬이 아래에 중첩되죠. 배포한 에이전트가 처리하는 모든 턴과 성능을 볼 수 있어요.

AgentCore는 런타임이지 모델이나 에이전트 프레임워크가 아니에요. 각 요청 안의 모델·도구·에이전트 스팬은 여전히 애플리케이션이 쓰는 Bedrock, Strands 또는 다른 프로바이더·프레임워크 통합에서 나옵니다 — init()이 동시에 그것들을 켜 줘요.

Runtime Requirements Setup
Python Python 3.10+, bedrock-agentcore (tested with 1.22.0), OTel ASGI instrumentation (tested with 0.63b1) Call init() explicitly before creating the app
TypeScript Not supported —

자동 계측

EU 리전 사용자는 OTEL 엔드포인트를 EU 버전으로 설정하세요. 그렇지 않으면 트레이스가 우리 US 서버로 보내집니다.

export CONFIDENT_OTEL_ENDPOINT="https://eu.otel.confident-ai.com/v1/traces"

의존성 설치

다음 명령으로 confident-trace를 agentcore extra와 함께, 그리고 AgentCore 런타임과 모델 SDK를 설치하세요.

pip install 'confident-trace[agentcore]' bedrock-agentcore boto3

agentcore extra는 OpenTelemetry의 ASGI 미들웨어를 가져옵니다. 이 미들웨어 덕분에 confident-trace가 AgentCore HTTP 서버를 감싸 들어오는 각 /invocations 요청마다 스팬을 열 수 있어요. Strands와 함께 AgentCore를 쓴다면 다음도 설치하세요.

pip install 'strands-agents[otel]'

Confident AI 키 설정

Confident AI Project API key를 받아 환경 변수로 설정합니다. Boto3는 평소의 AWS 자격 증명 체인을 사용해요.

export CONFIDENT_API_KEY="<your-confident-api-key>"
export BEDROCK_MODEL="<bedrock-model-id>"
# plus AWS_REGION and AWS credentials for Bedrock

AgentCore 계측

시작 시, BedrockAgentCoreApp을 만들기 전에 init()을 한 번 호출하세요. 그러면 엔드포인트에 도달하는 모든 요청이 서버 스팬 아래에 Bedrock converse 스팬을 둔 트레이스를 만들어요.

import asyncio
import os

import boto3
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from confident_trace import init, shutdown

init(
    endpoint="https://otel.confident-ai.com/v1/traces",
    protocol="http/protobuf",
    api_key=os.environ["CONFIDENT_API_KEY"],
)
app = BedrockAgentCoreApp()
client = boto3.client("bedrock-runtime")


@app.entrypoint
async def invoke(payload, context):
    # Offloading to a thread keeps the trace context intact for the sync Boto3 call.
    return await asyncio.to_thread(
        client.converse,
        modelId=os.environ["BEDROCK_MODEL"],
        messages=[{"role": "user", "content": [{"text": payload["prompt"]}]}],
    )


if __name__ == "__main__":
    try:
        app.run()
    finally:
        shutdown()

AWS에서는 exporter 설정을 명시적으로 전달하세요. AWS 환경은 표준 OTEL_EXPORTER_OTLP_* 변수를 설정해서, Confident AI의 exporter를 AWS 자체 컬렉터로 보내 버릴 수 있어요. 위처럼 endpoint(EU 리전이라면 위 EU URL 사용), protocol="http/protobuf", api_key를 init()에 항상 전달하고, 환경 기본값에 의존하지 마세요. 기존 AWS 프로세서, 샘플링, 리소스, 프로파게이터는 그대로 둔 채 유지됩니다.

한 번 초기화하고, 한 번 종료하세요. 시작 시 init()을, 정상 종료 시 활성 요청이 끝난 뒤 shutdown()을 호출하세요 — 요청마다 하지 마세요. shutdown()은 Confident AI의 exporter만 멈추고, 애플리케이션과 AWS exporter는 계속 돌아요. 한 번 초기화를 참고하세요.

에이전트 실행

앱을 로컬에서 시작하고 요청을 보내 보세요.

python main.py
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explain OpenTelemetry in one sentence."}'

완료 ✅. Confident AI 프로젝트에서 Observatory를 열어 트레이스를 확인하세요. 같은 파일은 AgentCore에 배포해도 그대로 실행됩니다.

트레이스가 안 보이면, 거의 항상 트레이스를 보낼 기회가 생기기 전에 프로세스가 종료됐거나, AWS의 OTLP 변수가 exporter를 리다이렉트했기 때문이에요(위 경고 참고). 종료 전에 반드시 shutdown()을 호출하세요 — 트러블슈팅 페이지를 참고하세요.

무엇이 포착되나

각 AgentCore 호출은 들어오는 요청을 처리 중에 수행된 모델·에이전트·도구 작업에 연결하는 트레이스로 내보내집니다.

  • 호출 수명 주기 — 요청 타이밍, 상태, 스트리밍 지속 시간, 엔트리포인트 안에 중첩된 작업
  • 대화 아이덴티티 — AgentCore 세션이 트레이스의 스레드 ID로 사용되어, 같은 세션의 호출을 묶음
  • 분산 컨텍스트 — 들어오는 W3C 트레이스 컨텍스트가 보존되어 AgentCore 작업이 상류 트레이스와 연결될 수 있음
  • 모델 호출 — 활성화된 모델 통합이 제공할 때 모델 상세, 메시지, 도구 요청과 결과, 완료 사유, 토큰 사용량
  • 에이전트·도구 호출 — 활성화된 프레임워크 통합이 만든 작업이 호출 아래에 중첩되어 유지
  • 커스텀 스팬 — 요청 처리 중 만든 커스텀 애플리케이션 스팬이 트레이스에서 자기 위치를 유지

AgentCore 요청 경계 자체는 요청·응답 본문을 들여다보거나 기록하지 않아요. 중첩된 통합이 포착하는 콘텐츠는 각각의 콘텐츠 정책을 따릅니다.

AWS나 서버 프레임워크가 이미 활성 서버 스팬을 제공하거나, OTel ASGI 미들웨어가 앱에 이미 등록되어 있으면, 이 통합은 스팬을 추가하는 대신 그 스팬을 사용해요. 다른 라우트, WebSocket, A2A, AgentCore의 내부 서비스 텔레메트리는 이 통합 범위 밖입니다.

Bedrock 커버리지는 Boto3 converse / converse_stream뿐입니다. InvokeModel과 네이티브 async AWS 클라이언트는 모델 스팬으로 추적되지 않으므로, 빠른 시작처럼 동기 Boto3 호출을 asyncio.to_thread로 오프로드하세요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. @app.entrypoint 핸들러가 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

from confident_trace import init, trace_context

init()

@app.entrypoint
async def invoke(payload, context):
    async with trace_context(
        tags=["support"],
        metadata={"release": "2026-09"},
        user_id=payload.get("user_id"),
        customer_id=payload.get("customer_id"),
    ):
        return await asyncio.to_thread(
            client.converse,
            modelId=os.environ["BEDROCK_MODEL"],
            messages=[{"role": "user", "content": [{"text": payload["prompt"]}]}],
        )

이 요청 기반 예제는 페이로드가 ID만 제공하므로 user_id와 customer_id를 사용해요.

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

AgentCore 엔트리포인트 호출 하나가 이미 하나의 대화 턴일 때는 turn()이 필요 없어요 — 통합이 그 턴의 트레이스를 자동으로 만들어 주거든요. 경계를 직접 정의하고 싶을 때, 예를 들어 두 번의 연속 AgentCore 호출을 하나의 턴으로 묶고 싶을 때 turn()을 사용하세요. 이후 턴에서 같은 스레드 ID를 재사용해 하나의 대화로 묶으면 돼요.

from confident_trace import init, turn

init()

@app.entrypoint
async def invoke(payload, context):
    async with turn("support-turn", thread_id=context.session_id):
        first = await call_agent(payload["prompt"])
        return await call_agent(f"Summarize this result: {first}")

스레드 입출력, 턴 ID, 사용자 ID는 스레드를 참고하세요.

AgentCore 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. AgentCore의 식별자는 Python에서 "agentcore"이고, 이를 빼면 이 통합이 비활성화돼요. 빈 목록은 모든 자동 계측을 비활성화합니다.

from confident_trace import init
init(instrumentations=())
# Use ("agentcore",) to opt in; omit "agentcore" to disable it.

이렇게 하면 Confident AI의 자동 계측이 꺼지고, 초기화 이후의 호출은 이 통합으로 계측되지 않아요.

다음 단계

배포한 에이전트를 추적했으니, 더 깊이 들어가 볼까요.

Online Evals

트레이스와 스팬이 Confident AI로 수집되는 실시간으로 평가를 돌려 에이전트 품질을 모니터링하세요.

Threads

모든 AgentCore 세션은 이미 스레드입니다. 전체 대화를 하나의 단위로 보고 평가하세요.

더 알아보기

  • Strands Agents — AgentCore 위에서 실행하는 Strands 에이전트 다루기
  • Online Evals — 수집되는 트레이스·스팬을 실시간으로 평가