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á.
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. Para obter um código de exemplo, consulte Converse Exemplos de uso de ferramentas de API.
Tópicos
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 Chamada de ferramentas baseada em JSON
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
{
"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 de 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 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 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"
