Chame uma ferramenta com o Converse API

Para permitir que um modelo use uma ferramenta para concluir uma resposta para uma mensagem, você envia a mensagem e as definições de uma ou mais ferramentas para o 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 envie os resultados da ferramenta de volta ao modelo. O modelo então usa os resultados para gerar uma resposta à mensagem original.

As etapas a seguir mostram como usar uma ferramenta com o Converse. API Para ver um código demonstrativo, consulte Exemplos de uso da API ferramenta Converse.

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).

nota

Meta tem recomendações específicas para criar prompts que usam ferramentas com Llama Modelos 3.1 (ou posteriores). Para obter mais informações, consulte a chamada de ferramentas JSON com base no Meta documentação.

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. Veja a seguir um exemplo de esquema para uma ferramenta que faz com que a música mais popular seja reproduzida 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 (Mensagem).

[
    {
        "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 sua 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 informações sobre outros parâmetros que você pode passar, consulteConverse com as operações da Converse API.

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

Quando você invoca a Converse operação com a mensagem e a definição da ferramenta, o modelo usa a definição da ferramenta para determinar se a ferramenta é 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, o modelo define o campo de stopReason resposta comotool_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). Você usa o toolUseId campo 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 emEtapa 1: enviar a mensagem e a definição da ferramenta.

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

Etapa 3: Faça a solicitação da ferramenta para o modelo

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

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 de 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 toolResult campo. Para indicar um erro, especifique error no status campo. O exemplo de erro a seguir é para quando a ferramenta não consegue 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 a modelo incluindo a mensagem do usuário que você criou na etapa anterior em uma chamada paraConverse. 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"