Menggunakan alat (panggilan fungsi)

Alat memperluas kemampuan Amazon Nova dengan menghubungkan model ke fungsionalitas eksternal seperti APIs, database dan lingkungan eksekusi kode. Penggunaan alat memungkinkan Amazon Nova mengakses informasi real-time, melakukan perhitungan, dan berinteraksi dengan sistem eksternal.

Memahami alur kerja penggunaan alat

Penggunaan alat dengan Amazon Nova melibatkan tiga fase utama:

Buat alat

Tentukan alat menggunakan konfigurasi alat yang mencakup berbagai alat dan secara opsional parameter pilihan alat. Setiap spesifikasi alat harus mencakup:

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"]
                    }
                }
            }
        }
    ]
}

Praktik terbaik untuk definisi alat

Output terstruktur dengan decoding terbatas

Model Amazon Nova memanfaatkan decoding terbatas untuk memastikan keandalan tinggi dalam output yang dihasilkan. Teknik ini menggunakan tata bahasa untuk membatasi kemungkinan token pada setiap langkah pembuatan, mencegah kunci yang tidak valid dan menerapkan tipe data yang benar berdasarkan skema yang Anda tentukan.

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"}
    }
}

Opsi pilihan alat

Amazon Nova mendukung tiga parameter pilihan alat:

Panggil alat

Ketika Amazon Nova memutuskan untuk memanggil alat, ia mengembalikan blok penggunaan alat sebagai bagian dari pesan asisten dengan StopReason disetel ke “tool_use”. Blok alat berisi nama alat dan inputnya.

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']}")

Panggilan alat pemrosesan

Ekstrak nama alat dan argumen dari pesan, lalu panggil alat:

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"])

Mengembalikan hasil alat

Kembalikan hasil alat menggunakan ToolResultBlock skema:

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}")

Penanganan kesalahan

Laporkan kesalahan kembali ke Amazon Nova untuk mengizinkan modifikasi permintaan dan coba lagi:

tool_result_message = {
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": tool["toolUseId"],
                "content": [{"text": "A validation exception occurred on field: sample.field"}],
                "status": "error"
            }
        }
    ]
}

Pertimbangan keamanan

Alat sistem bawaan

Model Amazon Nova 2.0 menyertakan alat bawaan yang dikelola sepenuhnya yang tidak memerlukan implementasi khusus. Aktifkan alat ini dengan sakelar sederhana di Converse API.

Penerjemah Kode

Code Interpreter memungkinkan Nova untuk menjalankan kode Python dengan aman di lingkungan kotak pasir yang terisolasi. Alat ini dirancang untuk perhitungan matematika, operasi logis, dan algoritma iteratif.

Aktifkan Code Interpreter dengan menentukan parameter 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"])

Penerjemah menjalankan kode di kotak pasir dan mengembalikan hasil dalam skema standar:

{
    "stdOut": "String",
    "stdErr": "String",
    "exitCode": "int",
    "isError": "boolean"
}

Pembumian Web

Web grounding memungkinkan Amazon Nova untuk mengakses informasi real-time dari internet, memberikan up-to-date tanggapan dan mengurangi halusinasi. Aktifkan dengan menentukan alat sistem nova_grounding:

tool_config = {
    "tools": [{
        "systemTool": {"name": "nova_grounding"}
    }]
}

Untuk informasi rinci tentang Web Grounding, lihatPembumian Web.

Protokol Konteks Model (MCP)

Model Context Protocol (MCP) adalah standar terbuka yang memungkinkan koneksi dua arah yang aman antara sumber data dan alat yang didukung AI. Alih-alih menulis adaptor khusus untuk setiap API atau layanan, jalankan server MCP dan biarkan Amazon Nova menemukan alatnya secara otomatis melalui jembatan klien.

Setelah terhubung, Amazon Nova memperlakukan alat MCP seperti integrasi eksternal lainnya: ia memutuskan kapan harus memanggil mereka, mengirim parameter yang diperlukan dan memasukkan hasil ke dalam tanggapan. Menggunakan Amazon Nova dengan Strands membuatnya lebih mudah dengan built-in MCPClient yang mengelola penemuan, koneksi, dan pemetaan hasil secara otomatis.