As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Chame uma ferramenta com a Converse API

Para permitir que um modelo use uma ferramenta para concluir uma resposta a uma mensagem, envie a mensagem e as definições de uma ou mais ferramentas ao modelo. Se o modelo determinar que uma das ferramentas pode ajudar a gerar uma resposta, ele retornará uma solicitação para que você use a ferramenta e retorne os resultados da ferramenta ao modelo. O modelo usa os resultados para gerar uma resposta para a mensagem original.

As etapas a seguir mostram como usar uma ferramenta com a Converse API. Para obter um código de exemplo, consulte ConverseExemplos de uso de ferramentas de API.

Etapa 1: enviar a mensagem e a definição da ferramenta

Para enviar a mensagem e a definição da ferramenta, você usa as operações Converse ou ConverseStream(para respostas de streaming).

A definição da ferramenta é um esquema JSON que você passa no parâmetro de solicitação toolConfig (ToolConfiguration) para a Converse operação. Para obter mais informações sobre o esquema, consulte Esquema JSON. O exemplo a seguir é de uma ferramenta que obtém as músicas mais tocadas em uma estação de rádio.

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

Na mesma solicitação, você também passa uma mensagem de usuário no parâmetro de solicitação messages (Message).

[
    {
        "role": "user",
        "content": [
            {
                "text": "What is the most popular song on WZPZ?"
            }
        ]
    }
]

Se você estiver usando um modelo Anthropic Claude 3, poderá forçar o uso de uma ferramenta especificando o campo toolChoice (ToolChoice) no parâmetro de toolConfig solicitação. Forçar o uso de uma ferramenta é útil para testar a ferramenta durante o desenvolvimento. O exemplo a seguir mostra como forçar o uso de uma ferramenta chamada top_song.

{"tool" : {"name" : "top_song"}}

Para obter mais informações sobre outros parâmetros que você pode passar, consulte Converse com as operações da Converse API.

Etapa 2: obter a solicitação da ferramenta do modelo

Quando invoca a operação Converse com a mensagem e a definição da ferramenta, o modelo usa a definição da ferramenta para determinar se a ela é necessária para responder à mensagem. Por exemplo, se o usuário da aplicação de chat enviar a mensagem Qual é a música mais tocada na WZPZ?, o modelo fará a comparação da mensagem com o esquema na definição da ferramenta top_song e determinará que a ferramenta pode ajudar a gerar uma resposta.

Quando o modelo decide que precisa de uma ferramenta para gerar uma resposta, ele define o campo de resposta stopReason como tool_use. A resposta também identifica a ferramenta (top_song) que o modelo deseja que você execute e a estação de rádio (WZPZ) que ele deseja que você consulte com a ferramenta. As informações sobre a ferramenta solicitada estão na mensagem que o modelo retorna no campo output (ConverseOutput). Especificamente, o campo toolUse (ToolUseBlock). Use o campo toolUseId para identificar a solicitação da ferramenta em chamadas posteriores.

O exemplo a seguir mostra a resposta de Converse quando você passa a mensagem discutida em Etapa 1: enviar a mensagem e a definição da ferramenta.

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                        "name": "top_song",
                        "input": {
                            "sign": "WZPZ"
                        }
                    }
                }
            ]
        }
    },
    "stopReason": "tool_use"
}

Etapa 3: fazer a solicitação da ferramenta do modelo

No campo toolUse na resposta do modelo, use o campo name para identificar o nome da ferramenta. Chame a implementação da ferramenta e passe os parâmetros de entrada do campo input.

Em seguida, crie uma mensagem de usuário que inclua um bloco de conteúdo toolResult (ToolResultBlock). No bloco de conteúdo, inclua a resposta da ferramenta e o ID da solicitação da ferramenta que você recebeu na etapa anterior.

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "json": {
                            "song": "Elemental Hotel",
                            "artist": "8 Storey Hike"
                        }
                    }
                ]
            }
        }
    ]
}

Caso ocorra um erro na ferramenta, como uma solicitação de uma estação de rádio inexistente, você poderá enviar informações de erro para o modelo no campo. toolResult Para indicar um erro, especifique error no campo status. O exemplo de erro a seguir é para quando a ferramenta não pode encontrar a estação de rádio.

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "text": "Station WZPA not found."
                    }
                ],
                "status": "error"
            }
        }
    ]
}

Etapa 4: obter a resposta do modelo

Continue a conversa com o modelo incluindo a mensagem do usuário criada na etapa anterior em uma chamada para Converse. O modelo gera uma resposta que responde à mensagem original (Qual é a música mais tocada na WZPZ?) com as informações que você forneceu no campo toolResult da mensagem.

{
     "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
                }
            ]
        }
    },
    "stopReason": "end_turn"