AgentCore 런타임 에이전트 호출

InvokeAgentRuntime 작업을 사용하면 Amazon 리소스 이름(ARN)으로 식별되는 특정 AgentCore 런타임 엔드포인트에 요청을 보내고 에이전트의 출력이 포함된 스트리밍 응답을 수신할 수 있습니다. API는 세션 식별자를 통한 세션 관리를 지원하므로 여러 상호 작용에서 대화 컨텍스트를 유지할 수 있습니다. 선택적 한정자를 사용하여 특정 에이전트 엔드포인트를 대상으로 지정할 수 있습니다.

InvokeAgentRuntime를 호출하려면 bedrock-agentcore:InvokeAgentRuntime 권한이 필요합니다. 호출 시 에이전트가 사용자 인증에 사용할 수 있는 보유자 토큰을 전달할 수도 있습니다.

InvokeAgentRuntime 작업은 요청 페이로드를 최대 100MB 크기의 바이너리 데이터로 수락하고 에이전트가 요청을 처리할 때 실시간으로 데이터 청크를 전달하는 스트리밍 응답을 반환합니다. 이 스트리밍 접근 방식을 사용하면 완전한 응답을 기다리지 않고 즉시 부분적인 결과를 수신할 수 있으므로 대화형 애플리케이션에 적합합니다.

동일한 세션에서 쉘 명령(예: 테스트 실행, git 작업 또는 환경 설정)을 실행하려면 AgentCore 런타임 세션 작업에서 쉘 실행 명령을 사용합니다. 두 작업 모두 동일한 에이전트 런타임 및 세션에서 작동합니다.

에이전트를 OAuth와 통합하려는 경우 AWS SDK를 사용하여 InvokeAgentRuntime를 호출할 수 없습니다. 대신 InvokeAgentRuntime에 HTTPS를 요청합니다. 자세한 내용은 Authenticate and authorize with Inbound Auth and Outbound Auth를 참조하세요.

스트리밍 에이전트 호출

다음 예제에서는 boto3를 사용하여 에이전트 런타임을 호출하는 방법을 보여줍니다.

import boto3
import json

# Initialize the Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload
)


# Process and print the response
if "text/event-stream" in response.get("contentType", ""):

    # Handle streaming response
    content = []
    for line in response["response"].iter_lines(chunk_size=10):
        if line:
            line = line.decode("utf-8")
            if line.startswith("data: "):
                line = line[6:]
                print(line)
                content.append(line)
    print("\nComplete response:", "\n".join(content))

elif response.get("contentType") == "application/json":
    # Handle standard JSON response
    content = []
    for chunk in response.get("response", []):
        content.append(chunk.decode('utf-8'))
    print(json.loads(''.join(content)))

else:
    # Print raw response for other content types
    print(response)

다중 모달 에이전트 호출

InvokeAgentRuntime 작업을 사용하여 텍스트와 이미지를 모두 포함하는 다중 모달 요청을 보낼 수 있습니다. 다음 예제에서는 다중 모달 에이전트를 호출하는 방법을 보여줍니다.

import boto3
import json
import base64

# Read and encode image
with open("image.jpg", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode('utf-8')

# Prepare multi-modal payload
payload = json.dumps({
    "prompt": "Describe what you see in this image",
    "media": {
        "type": "image",
        "format": "jpeg",
        "data": image_data
 }
}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload
)

세션 관리

InvokeAgentRuntime 작업은 runtimeSessionId 파라미터를 통한 세션 관리를 지원합니다. 여러 요청에 동일한 세션 식별자를 제공하여 에이전트가 이전 상호 작용을 참조할 수 있도록 대화 컨텍스트를 유지할 수 있습니다.

새 대화를 시작하려면 고유한 세션 식별자를 생성합니다. 기존 대화를 계속하려면 이전 요청과 동일한 세션 식별자를 사용합니다. 이 접근 방식을 사용하면 시간이 지남에 따라 컨텍스트를 유지하는 대화형 애플리케이션을 구축할 수 있습니다.

오류 처리

InvokeAgentRuntime 작업을 사용할 때 다양한 오류가 발생할 수 있습니다. 다음은 몇 가지 일반적인 오류와 이를 처리하는 방법입니다.

애플리케이션에서 적절한 오류 처리를 구현하여 더 나은 사용자 경험을 제공하고 문제를 효과적으로 해결합니다.

모범 사례

InvokeAgentRuntime 작업을 사용할 때는 다음 모범 사례를 따르세요.