# 도구 사용(함수 직접 호출)
도구는 모델을 API, 데이터베이스 및 코드 실행 환경과 같은 외부 기능에 연결하여 Amazon Nova 기능을 확장합니다. 도구를 사용하면 Amazon Nova에서 실시간 정보에 액세스하고, 계산을 수행하며, 외부 시스템과 상호 작용할 수 있습니다.
## 도구 사용 워크플로 이해
Amazon Nova에서 도구를 사용하는 경우 세 가지 주요 단계가 포함됩니다.
사용자 쿼리 및 도구 정의
각 도구의 기능과 입력 요구 사항을 설명하는 JSON 스키마를 제공하여 도구를 정의합니다. 도구 구성에는 각 도구를 사용하는 경우와 방법에 대한 명시적 세부 정보가 포함되어야 합니다.
도구 선택
사용자가 메시지를 전송하면 Amazon Nova에서 이를 분석하여 도구가 필요한지 결정합니다. 이 자동 도구 선택에서는 컨텍스트를 살펴보고 간접 호출할 도구(있는 경우)를 결정합니다. Amazon Nova에서 적절한 도구를 식별하면 도구 이름과 필요한 파라미터를 반환합니다.
모델의 요청에 따라 도구를 실행할 책임이 사용자에게 있습니다. 즉, 도구의 기능을 간접 호출하고 모델에서 제공하는 입력 파라미터를 처리하는 코드를 작성합니다.
결과 반환
도구를 실행한 후 JSON 또는 텍스트와 이미지 조합을 사용하여 결과를 구조화된 형식으로 Amazon Nova에 다시 보냅니다. Amazon Nova는 도구의 출력을 최종 응답에 통합합니다. 실행 중에 오류가 발생하면 Amazon Nova에서 적절히 조정할 수 있도록 도구 응답에 이를 표시합니다.
## 도구 생성
도구 배열과 선택적으로 도구 선택 파라미터를 포함하는 도구 구성을 사용하여 도구를 정의합니다. 각 도구 사양에는 다음이 포함되어야 합니다.
+ **이름**: 도구의 고유한 식별자
+ **설명:** 도구 기능에 대한 간결한 설명
+ **입력 스키마:** 필수 및 선택적 파라미터를 정의하는 JSON 스키마
**Example 도구 구성 예제**
```
tool_config = {
"tools": [
{
"toolSpec": {
"name": "calculator",
"description": "A calculator tool that can execute a math equation",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"equation": {
"type": "string",
"description": "The full equation to evaluate"
}
},
"required": ["equation"]
}
}
}
}
]
}
```
### 도구 정의 모범 사례
+ 이름과 설명이 도구의 정확한 기능을 명시적으로 전달하는지 확인하고, 지나치게 의미적으로 유사한 도구는 피함
+ 모델이 유사한 도구를 구별하는 데 도움이 되도록 설명에 주요 차별화 요소 포함
+ 최상의 성능을 위해 JSON 스키마를 중첩 계층 2개로 제한
+ 일반 텍스트로 구조를 설명하는 대신 스키마 유형(예: enum, int, float)을 사용하여 입력 제한
+ JSON 스키마 표기법을 사용하는 필수 파라미터와 선택적 파라미터 비교(예: "required": ["param1", "param2"]) 표시
+ 제출하기 전에 표준 검사기를 사용하여 JSON 스키마 검증
+ 스키마에서 긴 문자열 인수를 마지막에 배치하고 중첩하지 않도록 함
### 제한된 디코딩을 포함하는 구조화된 출력
Amazon Nova 모델은 제한된 디코딩을 활용하여 생성된 출력에서 높은 신뢰성을 보장합니다. 이 기법은 문법을 사용하여 각 생성 단계에서 가능한 토큰을 제한해 유효하지 않은 키를 방지하고 정의된 스키마를 기반으로 올바른 데이터 유형을 적용합니다.
**Example 구조화된 출력 예제**
```
tool_config = {
"tools": [
{
"toolSpec": {
"name": "ProductAnalysis",
"description": "Analyze product information from text.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Product name"
},
"rating": {
"maximum": 5,
"description": "Customer rating 1-5",
"type": ["number", "null"],
"minimum": 1
},
"features": {
"description": "Key product features",
"type": "array",
"items": {"type": "string"}
},
"category": {
"type": "string",
"description": "Product category"
},
"price": {
"type": "number",
"description": "Price in USD"
}
},
"required": ["name", "category", "price", "features"]
}
}
}
}
],
"toolChoice": {
"tool": {"name": "ProductAnalysis"}
}
}
```
### 도구 선택 옵션
Amazon Nova는 세 가지 도구 선택 파라미터를 지원합니다.
도구
지정된 도구가 한 번 직접 호출되며, 구조화된 출력 사용 사례에 적합함
임의
제공된 도구 중 하나가 한 번 이상 직접 호출되며, API 선택 시나리오에 유용함
자동
모델에서 도구의 직접 호출 여부와 직접 호출할 도구 수(기본 동작)를 결정함
## 도구 직접 호출
Amazon Nova에서 도구를 직접 호출하기로 결정하면 도구 사용 블록이 어시스턴트 메시지의 일부로 반환하며 이때 stopReason은 'tool\$1use'로 설정됩니다. 도구 블록에는 도구의 이름과 해당 입력이 포함됩니다.
**참고**
단일 Python 세션에서 다음 코드 섹션을 순차적으로 실행합니다(도구 직접 호출 → 도구 결과 반환). 예제를 다시 실행하려면 Python 세션을 다시 시작합니다.
**Example 도구 직접 호출**
```
import boto3
import json
# Create Bedrock client
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
# Complex calculation that benefits from precise computation
messages = [{
"role": "user",
"content": [{
"text": "Calculate the compound interest on $10,000 invested at 4.75% annual rate for 7 years, compounded quarterly. Use the formula A = P(1 + r/n)^(nt) where P=10000, r=0.0475, n=4, t=7"
}]
}]
# Define tool configuration with calculator
tool_config = {
"tools": [{
"toolSpec": {
"name": "calculator",
"description": "Perform mathematical calculations",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Mathematical expression to evaluate"
}
},
"required": ["expression"]
}
}
}
}]
}
# Invoke Model
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=messages,
toolConfig=tool_config
)
# Extract tool use from response
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
print(f"Tool: {tool['name']}")
print(f"Expression: {tool['input']['expression']}")
```
### 도구 직접 호출 처리
메시지에서 도구 이름과 인수를 추출하고 도구를 간접 호출합니다.
```
def calculate(expression):
"""Evaluate mathematical expression"""
print(f"Calculating: {expression}")
P = 10000
r = 0.0475
n = 4
t = 7
result = P * (1 + r/n) ** (n*t)
return result
stop_reason = response["stopReason"]
if stop_reason == "tool_use":
if tool["name"] == "calculator":
result = calculate(tool["input"]["expression"])
```
### 도구 결과 반환
ToolResultBlock 스키마를 사용하여 도구 결과를 반환합니다.
```
messages.append(response["output"]["message"])
# Add the tool result
messages.append({
"role": "user",
"content": [{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"result": result}}],
"status": "success"
}
}]
})
# Send the tool result to the model
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=messages,
toolConfig=tool_config
)
# Extract and display final response
final_text = next(
block["text"]
for block in response["output"]["message"]["content"]
if "text" in block
)
print(f"\nFinal Response:\n{final_text}")
```
### 오류 처리
Amazon Nova에 오류를 다시 보고하여 요청 수정 및 재시도를 허용합니다.
```
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool["toolUseId"],
"content": [{"text": "A validation exception occurred on field: sample.field"}],
"status": "error"
}
}
]
}
```
### 보안 고려 사항
+ 도구를 간접 호출하기 전에 도구가 존재하는지 검증
+ 입력의 형식이 올바른지 확인
+ 도구 실행 전에 적절한 권한이 있는지 확인
+ Amazon Nova에서 사용자 정보를 도구 직접 호출에 주입하도록 허용하는 대신 세션 세부 정보에 의존
+ LLM에서 도구 직접 호출을 할루시네이션할 수 있으므로, 실행 전에 항상 검증
## 기본 제공 시스템 도구
Amazon Nova 2.0 모델에는 사용자 지정 구현이 필요하지 않은 완전관리형 기본 제공 도구가 포함되어 있습니다. Converse API에서 간단하게 토글하여 이러한 도구를 활성화합니다.
### 코드 인터프리터
코드 인터프리터를 사용하면 Nova가 격리된 샌드박스 환경에서 Python 코드를 안전하게 실행할 수 있습니다. 이 도구는 수학 계산, 논리 연산 및 반복 알고리즘을 위해 설계되었습니다.
**참고**
코드 인터프리터는 IAD, PDX 및 NRT AWS 리전에서 사용할 수 있습니다. 요청이 지원되는 리전으로 라우팅되도록 하려면 글로벌 CRIS를 사용합니다. Bedrock API 키를 사용하는 경우 정책 정의에 `InvokeTool` 권한을 수동으로 추가해야 합니다. 기본 Bedrock 역할에서는 `InvokeTool` 작업을 허용하지 않습니다.
systemTool 파라미터를 지정하여 코드 인터프리터를 활성화합니다.
```
import boto3
import json
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
tool_config = {
"tools": [{
"systemTool": {
"name": "nova_code_interpreter"
}
}]
}
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=[{
"role": "user",
"content": [{
"text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82"
}]
}],
toolConfig=tool_config,
inferenceConfig={"maxTokens": 10000, "temperature": 0}
)
# Pretty print the response
for block in response["output"]["message"]["content"]:
if "toolUse" in block:
print("=== Tool Use ===")
print(f"Tool: {block['toolUse']['name']}")
print(f"Code:\n{block['toolUse']['input']['snippet']}\n")
elif "toolResult" in block:
print("=== Tool Result ===")
result = block['toolResult']['content'][0]['json']
print(f"Output: {result['stdOut']}")
if result['stdErr']:
print(f"Error: {result['stdErr']}")
print(f"Exit Code: {result['exitCode']}\n")
elif "text" in block:
print("=== Final Answer ===")
print(block["text"])
```
인터프리터는 샌드박스에서 코드를 실행하고 표준 스키마에서 결과를 반환합니다.
```
{
"stdOut": "String",
"stdErr": "String",
"exitCode": "int",
"isError": "boolean"
}
```
### Web Grounding
Amazon Nova는 웹 그라운딩을 통해 인터넷에서 실시간 정보에 액세스하여 최신 응답을 제공하고 할루시네이션을 줄입니다. nova\$1grounding 시스템 도구를 지정하여 활성화합니다.
```
tool_config = {
"tools": [{
"systemTool": {"name": "nova_grounding"}
}]
}
```
웹 그라운딩에 대한 자세한 내용은 [Web Grounding](web-grounding.md) 섹션을 참조하세요.
### Model Context Protocol(MCP)
Model Context Protocol(MCP)은 데이터 소스와 AI 기반 도구 간에 안전한 양방향 연결을 구축할 수 있는 개방형 표준입니다. 각 API 또는 서비스에 대한 사용자 지정 어댑터를 작성하는 대신, MCP 서버를 실행하고 Amazon Nova에서 클라이언트 브리지를 통해 도구를 자동으로 검색하도록 할 수 있습니다.
연결되면 Amazon Nova는 이러한 도구를 다른 외부 통합과 같이 처리합니다. 즉, 직접 호출 시점을 결정하고, 필요한 파라미터를 전송하며, 결과를 응답에 통합합니다. Amazon Nova를 Strands와 함께 사용하면 검색, 연결 및 결과 매핑을 자동으로 관리하는 기본 제공 MCPClient를 통해 작업을 더 쉽게 수행할 수 있습니다.