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 o 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 o Converse API. Por exemplo, código, consulteConverse APIexemplos de uso de ferramentas.

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 JSON esquema que você passa no parâmetro de solicitação toolConfig (ToolConfiguration) para a Converse operação. Para obter informações sobre o esquema, consulte JSONesquema. 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 Anthropic Claude Modelo 3, você pode 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 Conduza uma conversa com o Converse Operações do 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 do seu aplicativo de bate-papo enviar a mensagem Qual é a música mais popularWZPZ? , o modelo combina a mensagem com o esquema na definição da ferramenta top_song e determina 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 ao 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 então gera uma resposta que responde à mensagem original (Qual é a música mais popularWZPZ? ) com as informações que você forneceu no toolResult campo da mensagem.

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