Client-side uso de ferramentas

Se você usar a API de respostas, a API de conclusão de bate-papo, a API Converse ou a InvokeModel API para enviar a solicitação, o modelo usará a chamada de ferramentas do lado do cliente. Isso significa que, em seu código, você chama a ferramenta em nome do modelo. Nesse cenário, suponha que a implementação da ferramenta seja uma API. A ferramenta poderia facilmente ser um banco de dados, uma função do Lambda ou algum outro software. Você decide como deseja implementar a ferramenta. Você continua a conversa com o modelo fornecendo uma mensagem com o resultado da ferramenta. Por fim, o modelo gera uma resposta para a mensagem original que inclui os resultados da ferramenta que você enviou ao modelo.

Vamos definir a ferramenta que usaremos para uso da ferramenta. Os exemplos de Python a seguir mostram como usar uma ferramenta que retorna a música mais popular em uma estação de rádio fictícia.


def get_most_popular_song(station_name: str) -> str:
    stations = {
        "Radio Free Mars": "Starman – David Bowie",
        "Neo Tokyo FM": "Plastic Love – Mariya Takeuchi",
        "Cloud Nine Radio": "Blinding Lights – The Weeknd",
    }
    return stations.get(station_name, "Unknown Station – No chart data available")

Usando a API de respostas para ferramentas do lado do cliente

Você pode usar o recurso de chamada de função fornecido pela OpenAI para chamar essa ferramenta. A API de respostas é a API preferida da OpenAI. Aqui está o código Python para a API de respostas para ferramentas do lado do cliente:


from openai import OpenAI
import json

client = OpenAI()

response = client.responses.create(
    model="oss-gpt-120b",
    input="What is the most popular song on Radio Free Mars?",
    tools=[
        {
            "type": "function",
            "name": "get_most_popular_song",
            "description": "Returns the most popular song on a radio station",
            "parameters": {
                "type": "object",
                "properties": {
                    "station_name": {
                        "type": "string",
                        "description": "Name of the radio station"
                    }
                },
                "required": ["station_name"]
            }
        }
    ]
)

if response.output and response.output[0].content:
    tool_call = response.output[0].content[0]
    args = json.loads(tool_call["arguments"])
    result = get_most_popular_song(args["station_name"])
    
    final_response = client.responses.create(
        model="oss-gpt-120b",
        input=[
            {
                "role": "tool",
                "tool_call_id": tool_call["id"],
                "content": result
            }
        ]
    )
    
    print(final_response.output_text)

Usando a API Chat Completions para ferramentas do lado do cliente

Você também pode usar a API Chat Completions. Aqui está o código Python para usar o Chat Completions:



    from openai import OpenAI
import json

client = OpenAI()

completion = client.chat.completions.create(
    model="oss-gpt-120b",
    messages=[{"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_most_popular_song",
            "description": "Returns the most popular song on a radio station",
            "parameters": {
                "type": "object",
                "properties": {
                   "station_name": {"type": "string", "description": "Name of the radio station"}
                },
                "required": ["station_name"]
            }
        }
    }]
)

message = completion.choices[0].message

if message.tool_calls:
    tool_call = message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    result = get_most_popular_song(args["station_name"])

    followup = client.chat.completions.create(
        model="oss-gpt-120b",
        messages=[
            {"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"},
            message,
            {"role": "tool", "tool_call_id": tool_call.id, "content": result}
        ]
    )

    print(followup.choices[0].message.content)

Para obter mais detalhes sobre o uso da Function Calling na API Responses e da API Chat Completions, consulte Function Calling na OpenAI.

Usando a API Converse para ferramentas do lado do cliente

É possível usar a API Converse para permitir que um modelo use uma ferramenta em uma conversa. Os exemplos de Python a seguir mostram como usar uma ferramenta que retorna a música mais popular em uma estação de rádio fictícia.


# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""Shows how to use tools with the Converse API and the Cohere Command R model."""

import logging
import json
import boto3
from botocore.exceptions import ClientError


class StationNotFoundError(Exception):
    """Raised when a radio station isn't found."""
    pass


logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)


def get_top_song(call_sign):
    """Returns the most popular song for the requested station.

    Args:
        call_sign (str): The call sign for the station for which you want
            the most popular song.

    Returns:
        response (json): The most popular song and artist.
    """
    song = ""
    artist = ""

    if call_sign == 'WZPZ':
        song = "Elemental Hotel"
        artist = "8 Storey Hike"
    else:
        raise StationNotFoundError(f"Station {call_sign} not found.")

    return song, artist


def generate_text(bedrock_client, model_id, tool_config, input_text):
    """Generates text using the supplied Amazon Bedrock model. If necessary,
    the function handles tool use requests and sends the result to the model.

    Args:
        bedrock_client: The Boto3 Bedrock runtime client.
        model_id (str): The Amazon Bedrock model ID.
        tool_config (dict): The tool configuration.
        input_text (str): The input text.

    Returns:
        Nothing.
    """
    logger.info("Generating text with model %s", model_id)

    # Create the initial message from the user input.
    messages = [{"role": "user",
                 "content": [{"text": input_text}]}]

    response = bedrock_client.converse(modelId=model_id,
                                       messages=messages,
                                       toolConfig=tool_config)

    output_message = response['output']['message']
    messages.append(output_message)

    stop_reason = response['stopReason']

    if stop_reason == 'tool_use':
        # Tool use requested. Call the tool and send the result to the model.
        tool_requests = response['output']['message']['content']

        for tool_request in tool_requests:
            if 'toolUse' in tool_request:
                tool = tool_request['toolUse']
                logger.info("Requesting tool %s. Request: %s",
                            tool['name'], tool['toolUseId'])

                if tool['name'] == 'top_song':
                    tool_result = {}
                    try:
                        song, artist = get_top_song(tool['input']['sign'])
                        tool_result = {"toolUseId": tool['toolUseId'],
                                       "content": [{"json": {"song": song, "artist": artist}}]}
                    except StationNotFoundError as err:
                        tool_result = {"toolUseId": tool['toolUseId'],
                                       "content": [{"text": err.args[0]}],
                                       "status": 'error'}

                    tool_result_message = {"role": "user",
                                           "content": [{"toolResult": tool_result}]}
                    messages.append(tool_result_message)

        # Send the tool result to the model.
        response = bedrock_client.converse(modelId=model_id,
                                           messages=messages,
                                           toolConfig=tool_config)

        output_message = response['output']['message']

    # print the final response from the model.
    for content in output_message['content']:
        print(json.dumps(content, indent=4))


def main():
    """Entrypoint for tool use example."""
    logging.basicConfig(level=logging.INFO,
                        format="%(levelname)s: %(message)s")

    model_id = "cohere.command-r-v1:0"
    input_text = "What is the most popular song on WZPZ?"

    tool_config = {
        "tools": [
            {
                "toolSpec": {
                    "name": "top_song",
                    "description": "Get the most popular song played on a radio station.",
                    "inputSchema": {
                        "json": {
                            "type": "object",
                            "properties": {
                                "sign": {
                                    "type": "string",
                                    "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ, and WKRP."
                                }
                            },
                            "required": ["sign"]
                        }
                    }
                }
            }
        ]
    }

    bedrock_client = boto3.client(service_name='bedrock-runtime')

    try:
        print(f"Question: {input_text}")
        generate_text(bedrock_client, model_id, tool_config, input_text)
    except ClientError as err:
        message = err.response['Error']['Message']
        logger.error("A client error occurred: %s", message)
        print(f"A client error occured: {message}")
    else:
        print(f"Finished generating text with model {model_id}.")


if __name__ == "__main__":
    main()

Escolher qual ferramenta o modelo solicita

O toolChoice campo opcional em toolConfig controla se o modelo precisa solicitar uma ferramenta. As configurações que você pode usar dependem do modelo individual que você chama, não do fornecedor do modelo ou da família de modelos:

auto(o padrão) é compatível com todos os modelos que oferecem suporte ao uso de ferramentas. O modelo decide se deseja solicitar uma ferramenta ou gerar texto em vez disso.
any, que exige que o modelo solicite pelo menos uma ferramenta etool, que exige que o modelo solicite uma ferramenta que você nomeie, são compatíveis com alguns modelos, mas não em outros. Um modelo pode suportar um dos dois e não o outro.

Se um modelo não suportar a configuração que você envia, a solicitação falhará com a, ValidationException em vez de voltar para auto a. A mensagem identifica o campo a ser removido, por exemplo, This model doesn't support the toolConfig.toolChoice.tool field. Remove toolConfig.toolChoice.tool and try again. alguns modelos retornam o erro que o provedor do modelo relata, como The model returned the following errors: tool_choice: type "tool" and "any" are not supported for this model. Para os modelos Anthropic Claude que não oferecem suporte any outool, consulte Uso forçado de ferramentas.

Um modelo que não suporta o uso de ferramentas falha em todas This model doesn't support tool use. as toolChoice configurações, inclusiveauto.

Uso da ferramenta com streaming de resposta

O suporte para o uso de ferramentas e o suporte para streaming de respostas são recursos independentes. A maioria dos modelos que oferecem suporte ao uso de ferramentas também aceita um toolConfig campo ativadoConverseStream, mas os modelos a seguir aceitam ferramentas somente na Converse operação sem streaming e as rejeitam ConverseStream comThis model doesn't support tool use in streaming mode.:

Llama 3.1 8B Instruct, Llama 3.1 70B Instruct, e Llama 3.3 70B Instruct
Llama 4 Scout 17B Instruct e Llama 4 Maverick 17B Instruct
Mistral Large 1 (24.02), Mistral Large 2 (24.07), e Pixtral Large (25.02)
Writer Palmyra X4 e Writer Palmyra X5

O streaming de resposta em si funciona com todos esses modelos. Somente a combinação de streaming e uso de ferramentas não é suportada. Se você precisar usar uma ferramenta com um deles, ligue Converse em vez disso.

Sobre a ID de uso da ferramenta

Cada solicitação de ferramenta em uma resposta carrega um toolUseId que identifica essa solicitação. Você repete o mesmo valor no toolResult bloco correspondente para que o modelo possa combinar o resultado com a solicitação. A forma como o Amazon Bedrock produz esse valor depende do tipo de ferramenta e do modelo:

Para ferramentas que você define emtoolConfig, o Amazon Bedrock gera o valor. É um identificador gerado aleatoriamente prefixado comtooluse_, e não é produzido ou derivado da saída do modelo.
Para ferramentas do lado do servidor e ferramentas MCP do Amazon Bedrock, o Amazon Bedrock calcula o valor de forma determinística a partir da solicitação da ferramenta, em vez de gerá-lo aleatoriamente. O valor ainda carrega o tooluse_ prefixo.
Para alguns modelos, o identificador que o provedor do modelo retorna é passado inalterado. Esse valor usa o formato do próprio provedor, não carrega o tooluse_ prefixo e pode conter texto derivado de sua solicitação, como o nome da ferramenta.

Para diferenciar os dois em tempo de execução, verifique o prefixo. Cada identificador que o Amazon Bedrock gera começa com, tooluse_ seguido por 22 caracteres. Um identificador que não começa com tooluse_ veio do fornecedor do modelo. Esse comportamento pode ser diferente entre modelos da mesma família, então teste o modelo específico que você chama.

Importante

Se seu aplicativo redige conteúdo gerado pelo modelo, por exemplo, para atender às obrigações de conformidade de informações de saúde protegidas, não presuma que isso toolUseId é gerado pelo Amazon Bedrock para cada modelo. Trate o valor como derivado do modelo, a menos que você tenha confirmado o comportamento do modelo específico que você chama.

Usando APIs Invoke para uso de ferramentas do lado do cliente

É possível usar ferramentas com as operações de inferência de base (InvokeModelou InvokeModelWithResponseStream). Para encontrar os parâmetros de inferência que você passa no corpo da solicitação, consulte os parâmetros de inferência do modelo que deseja usar.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Uso de ferramentas

Server-side