---
title: Agente de suporte ao cliente
url: https://platform.claude.com/docs/pt-BR/about-claude/use-case-guides/customer-support-chat
description: Crie um chatbot de suporte ao cliente com Claude que responde a perguntas sobre produtos, mantém-se no assunto e gera cotações por meio do uso de ferramentas.
---
## Pré-requisitos
Para seguir este guia, você precisa de:
* Uma chave de API do Claude (definida como a variável de ambiente `ANTHROPIC_API_KEY`)
* Python 3.10 ou posterior
Instale os pacotes necessários:
```bash
pip install anthropic streamlit python-dotenv
```
## Antes de construir com Claude
### Decida se deve usar Claude para chat de suporte
Aqui estão alguns indicadores-chave de que você deve empregar um "large language model" (modelo de linguagem grande), ou LLM, como Claude para automatizar partes do seu processo de suporte ao cliente:
Claude se destaca em lidar com um grande número de perguntas semelhantes de forma eficiente, liberando os agentes humanos para questões mais complexas.
Claude pode recuperar, processar e combinar rapidamente informações de vastas bases de conhecimento, enquanto agentes humanos podem precisar de tempo para pesquisar ou consultar múltiplas fontes.
Claude pode fornecer suporte ininterrupto sem fadiga, enquanto manter agentes humanos para cobertura contínua pode ser caro e desafiador.
Claude pode lidar com aumentos repentinos no volume de consultas sem a necessidade de contratar e treinar pessoal adicional.
Você pode instruir Claude a representar consistentemente o tom e os valores da sua marca, enquanto agentes humanos podem variar em seus estilos de comunicação.
Algumas considerações para escolher Claude em vez de outros LLMs:
* Você prioriza conversas naturais e com nuances: a compreensão sofisticada de linguagem do Claude permite conversas mais naturais e conscientes do contexto, que parecem mais humanas do que chats com outros LLMs.
* Você frequentemente recebe consultas complexas e abertas: Claude pode lidar com uma ampla gama de tópicos e perguntas sem gerar respostas prontas ou exigir programação extensiva de permutações de enunciados do usuário.
* Você precisa de suporte multilíngue escalável: as capacidades multilíngues do Claude permitem que ele participe de conversas em mais de 200 idiomas sem a necessidade de chatbots separados ou processos extensivos de tradução para cada idioma suportado.
### Defina sua interação de chat ideal
Esboce uma interação ideal com o cliente para definir como e quando você espera que o cliente interaja com Claude. Esse esboço ajudará a determinar os requisitos técnicos da sua solução.
Aqui está um exemplo de interação de chat para suporte ao cliente de seguro de automóveis:
* **Cliente:** Inicia a experiência de chat de suporte
* **Claude:** Cumprimenta calorosamente o cliente e inicia a conversa
* **Cliente:** Pergunta sobre seguro para seu novo carro elétrico
* **Claude:** Fornece informações relevantes sobre cobertura de veículos elétricos
* **Cliente:** Faz perguntas relacionadas a necessidades específicas de seguros para veículos elétricos
* **Claude:** Responde com respostas precisas e informativas e fornece links para as fontes
* **Cliente:** Faz perguntas fora do assunto, não relacionadas a seguros ou carros
* **Claude:** Esclarece que não discute tópicos não relacionados e conduz o usuário de volta ao seguro de automóveis
* **Cliente:** Expressa interesse em uma cotação de seguro
* **Claude:** Faz um conjunto de perguntas para determinar a cotação apropriada, adaptando-se às respostas
* **Claude:** Envia uma solicitação para usar a ferramenta de API de geração de cotações junto com as informações necessárias coletadas do usuário
* **Claude:** Recebe as informações de resposta do uso de ferramentas da API, sintetiza as informações em uma resposta natural e apresenta a cotação fornecida ao usuário
* **Cliente:** Faz perguntas de acompanhamento
* **Claude:** Responde às perguntas de acompanhamento conforme necessário
* **Claude:** Orienta o cliente para os próximos passos no processo de seguro e encerra a conversa
No exemplo real que você escrever para seu próprio caso de uso, pode ser útil escrever as palavras reais dessa interação para que você também tenha uma noção do tom ideal, do comprimento da resposta e do nível de detalhe que deseja que Claude tenha.
### Divida a interação em tarefas distintas
O chat de suporte ao cliente é uma coleção de várias tarefas diferentes, desde responder perguntas até recuperar informações e agir sobre solicitações, reunidas em uma única interação com o cliente. Antes de começar a construir, divida sua interação ideal com o cliente em cada tarefa que você deseja que Claude seja capaz de executar. Isso garante que você possa criar prompts e avaliar Claude para cada tarefa, e lhe dá uma boa noção da variedade de interações que você precisa considerar ao escrever casos de teste.
Os clientes às vezes acham útil visualizar isso como um fluxograma de interação dos possíveis pontos de inflexão da conversa, dependendo das solicitações do usuário.
Aqui estão as principais tarefas associadas ao exemplo de interação de seguro:
1. Saudação e orientação geral
* Cumprimentar calorosamente o cliente e iniciar a conversa
* Fornecer informações gerais sobre a empresa e a interação
2. Informações sobre o produto
* Fornecer informações sobre cobertura de veículos elétricos
Isso exigirá que Claude tenha as informações necessárias em seu contexto e pode implicar que uma
[integração RAG](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide)
seja necessária.
* Responder a perguntas relacionadas a necessidades específicas de seguro para veículos elétricos
* Responder a perguntas de acompanhamento sobre a cotação ou detalhes do seguro
* Oferecer links para fontes quando apropriado
3. Gerenciamento da conversa
* Manter-se no assunto (seguro de automóveis)
* Redirecionar perguntas fora do assunto de volta para temas relevantes
4. Geração de cotações
* Fazer perguntas apropriadas para determinar a elegibilidade para cotação
* Adaptar as perguntas com base nas respostas do cliente
* Enviar as informações coletadas para a API de geração de cotações
* Apresentar a cotação fornecida ao cliente
### Estabeleça critérios de sucesso
Trabalhe com sua equipe de suporte para [definir critérios de sucesso e escrever avaliações detalhadas](https://platform.claude.com/docs/pt-BR/test-and-evaluate/develop-tests) com benchmarks e metas mensuráveis.
Aqui estão critérios e benchmarks que podem ser usados para avaliar com que sucesso Claude executa as tarefas definidas:
Esta métrica avalia com que precisão Claude entende as consultas dos clientes em vários tópicos. Meça isso revisando uma amostra de conversas e avaliando se Claude tem a interpretação correta da intenção do cliente, dos próximos passos críticos, de como é uma resolução bem-sucedida e mais. Busque uma precisão de compreensão de 95% ou superior.
Isso avalia quão bem a resposta do Claude aborda a pergunta ou problema específico do cliente. Avalie um conjunto de conversas e classifique a relevância de cada resposta (usando avaliação baseada em LLM para escala). Busque uma pontuação de relevância de 90% ou superior.
Avalie a correção das informações gerais sobre a empresa e o produto fornecidas ao usuário, com base nas informações fornecidas ao Claude no contexto. Busque 100% de precisão nessas informações introdutórias.
Acompanhe a frequência e a relevância dos links ou fontes oferecidos. Busque fornecer fontes relevantes em 80% das interações em que informações adicionais poderiam ser benéficas.
Meça quão bem Claude se mantém no assunto, como o tópico de seguro de automóveis na implementação de exemplo. Busque que 95% das respostas estejam diretamente relacionadas a seguro de automóveis ou à consulta específica do cliente.
Meça o sucesso do Claude em determinar quando gerar conteúdo informativo e quão relevante esse conteúdo é. Por exemplo, nesta implementação, você estaria determinando quão bem Claude entende quando gerar uma cotação e quão precisa é essa cotação. Busque 100% de precisão, pois essa é uma informação vital para uma interação bem-sucedida com o cliente.
Isso mede a capacidade do Claude de reconhecer quando uma consulta precisa de intervenção humana e escalonar adequadamente. Acompanhe a porcentagem de conversas escalonadas corretamente em comparação com aquelas que deveriam ter sido escalonadas, mas não foram. Busque uma precisão de escalonamento de 95% ou superior.
Aqui estão critérios e benchmarks que podem ser usados para avaliar o impacto nos negócios de empregar Claude para suporte:
Isso avalia a capacidade do Claude de manter ou melhorar o sentimento do cliente ao longo da conversa. Use ferramentas de análise de sentimento para medir o sentimento no início e no final de cada conversa. Busque sentimento mantido ou melhorado em 90% das interações.
A porcentagem de consultas de clientes tratadas com sucesso pelo chatbot sem intervenção humana. Normalmente, busque uma taxa de deflexão de 70-80%, dependendo da complexidade das consultas.
Uma medida de quão satisfeitos os clientes estão com sua interação com o chatbot. Geralmente feita por meio de pesquisas pós-interação. Busque uma pontuação CSAT de 4 em 5 ou superior.
O tempo médio que o chatbot leva para resolver uma consulta. Isso varia muito com base na complexidade dos problemas, mas, em geral, busque um AHT menor em comparação com agentes humanos.
## Como implementar Claude como agente de atendimento ao cliente
### Escolha o modelo Claude certo
A escolha do modelo depende dos trade-offs entre custo, precisão e tempo de resposta.
Para chat de suporte ao cliente, Claude Opus 5.5 é bem adequado para equilibrar inteligência, "latency" (latência) e custo, incluindo os cenários de suporte mais complexos que exigem raciocínio profundo em conversas longas e com várias etapas. No entanto, para casos em que você tem um fluxo de conversa com vários prompts, incluindo RAG, uso de ferramentas ou prompts de contexto longo, Claude Haiku 5.5 pode ser mais adequado para otimizar a latência. O ["effort" (esforço)](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) é o principal controle de velocidade desse modelo: `low` é o nível mais rápido, adequado para chat e tarefas curtas com ferramentas.
### Construa um prompt forte
Usar Claude para suporte ao cliente requer que Claude tenha direção e contexto suficientes para responder adequadamente, ao mesmo tempo que tenha flexibilidade suficiente para lidar com uma ampla gama de consultas de clientes.
Comece escrevendo os elementos de um prompt forte, começando com um "system prompt" (prompt do sistema). Crie um arquivo chamado `config.py` e adicione cada um dos seguintes blocos a ele:
```python
IDENTITY = """You are Eva, a friendly and knowledgeable AI assistant for Acme Insurance
Company. Your role is to warmly welcome customers and provide information on
Acme's insurance offerings, which include car insurance and electric car
insurance. You can also help customers get quotes for their insurance needs."""
```
Embora você possa ficar tentado a colocar todas as suas informações dentro de um prompt do sistema como forma de separar as instruções da conversa do usuário, Claude na verdade funciona melhor com a maior parte do conteúdo do prompt escrita dentro do primeiro turno de
`User`
(com a única exceção sendo o prompting de papel). Leia mais em
[Dando um papel ao Claude com um prompt do sistema](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role)
.
É melhor dividir prompts complexos em subseções e escrever uma parte de cada vez. Para cada tarefa, você pode ter mais sucesso seguindo um processo passo a passo para definir as partes do prompt de que Claude precisaria para executar bem a tarefa. Para este exemplo de suporte ao cliente de seguro de automóveis, você escreverá por partes todos os componentes de um prompt, começando com a tarefa "Saudação e orientação geral". Isso também facilita a depuração do seu prompt, pois você pode ajustar mais rapidamente partes individuais do prompt geral.
```python
STATIC_GREETINGS_AND_GENERAL = """
Acme Auto Insurance: Your Trusted Companion on the Road
About:
At Acme Insurance, we understand that your vehicle is more than just a mode of transportation—it's your ticket to life's adventures.
Since 1985, we've been crafting auto insurance policies that give drivers the confidence to explore, commute, and travel with peace of mind.
Whether you're navigating city streets or embarking on cross-country road trips, Acme is there to protect you and your vehicle.
Our innovative auto insurance policies are designed to adapt to your unique needs, covering everything from fender benders to major collisions.
With Acme's award-winning customer service and swift claim resolution, you can focus on the joy of driving while we handle the rest.
We're not just an insurance provider—we're your co-pilot in life's journeys.
Choose Acme Auto Insurance and experience the assurance that comes with superior coverage and genuine care. Because at Acme, we don't just
insure your car—we fuel your adventures on the open road.
Note: We also offer specialized coverage for electric vehicles, ensuring that drivers of all car types can benefit from our protection.
Acme Insurance offers the following products:
- Car insurance
- Electric car insurance
- Two-wheeler insurance
Business hours: Monday-Friday, 9 AM - 5 PM EST
Customer service number: 1-800-123-4567
"""
```
Em seguida, faça o mesmo para suas informações sobre seguro de automóveis e seguro de carros elétricos.
```python
STATIC_CAR_INSURANCE = """
Car Insurance Coverage:
Acme's car insurance policies typically cover:
1. Liability coverage: Pays for bodily injury and property damage you cause to others.
2. Collision coverage: Pays for damage to your car in an accident.
3. Comprehensive coverage: Pays for damage to your car from non-collision incidents.
4. Medical payments coverage: Pays for medical expenses after an accident.
5. Uninsured/underinsured motorist coverage: Protects you if you're hit by a driver with insufficient insurance.
Optional coverages include:
- Rental car reimbursement
- Roadside assistance
- New car replacement
"""
STATIC_ELECTRIC_CAR_INSURANCE = """
Electric Car Insurance:
Our specialized electric car insurance goes beyond traditional auto coverage,
offering tailored protection for your high-tech investment. In addition to standard coverages, we offer:
- Safeguarding expensive battery systems
- Covering home charging equipment
- Adapting to the rapidly evolving world of electric vehicles
Whether you're driving a Rivian, Nissan Leaf, Chevrolet Bolt,
or any other electric vehicle, our knowledgeable agents are ready to craft a policy
that gives you the confidence to enjoy every electron-powered mile.
"""
```
Agora que você tem seu conteúdo estático, adicione pelo menos 4-5 exemplos de interações "boas" para orientar as respostas do Claude. Esses exemplos devem ser representativos da sua interação ideal com o cliente e podem incluir elementos como guardrails e chamadas de ferramentas.
```python
EXAMPLES = """
Here are a few examples of how you can interact with customers:
H: Hi, do you offer commercial insurance for small businesses?
A: Ah! Unfortunately, we don't offer commercial insurance at this time.
However, we do provide a range of personal insurance products including car insurance and electric car insurance.
Would you like to know more about these offerings?
H: Hi, what are your business hours?
A: Our business hours are Monday to Friday, 9 AM to 5 PM EST.
If you have any questions or need assistance, feel free to reach out during those times.
How else can I assist you today?
H: I'm shopping for car insurance. What does Acme offer?
A: Great choice! Acme's car insurance policies typically include:
- Liability coverage: Protects you if you're at fault in an accident
- Collision coverage: Pays for damage to your car in an accident
- Comprehensive coverage: Covers non-collision incidents like theft or vandalism
- Medical payments coverage: Pays for medical expenses after an accident
- Uninsured/underinsured motorist coverage: Protects you from drivers with insufficient insurance
We also offer optional coverages like rental car reimbursement, roadside assistance, and new car replacement.
Would you like more details on any of these coverages, or do you have specific questions about insuring your vehicle?
H: I'd like to hear about your electric car insurance.
A: Certainly! Our electric car insurance is specially designed to meet the unique needs of electric vehicle owners.
In addition to all the standard coverages we offer for regular cars, our electric car policies include:
- Battery coverage: Protection against damage or degradation of your vehicle's expensive battery system
- Tech package: Covers repairs or replacement of advanced electronics and onboard computer systems
- Charging station coverage: Protects both home and portable charging equipment
- Cybersecurity protection: Coverage against hacking or digital threats
- Specialized roadside assistance: Includes flatbed towing to protect the vehicle's undercarriage
We cover a wide range of electric vehicles, including popular models from Tesla, Rivian, Nissan, Chevrolet, and more.
Is there a specific electric vehicle you're looking to insure, or would you like more details on any of these coverages?
H: I'd like to get a quote for my car insurance.
A: Certainly! I'd be happy to help you get a quote for your car insurance.
To provide you with an accurate quote, I'll need to collect some information about your vehicle and the primary driver.
Let's start with the basics:
1. What is the make and model of your vehicle?
2. What year was it manufactured?
3. Approximately how many miles have you driven?
4. What is the age of the primary driver?
Once you provide this information, I'll use our quoting tool to generate a personalized insurance quote for you.
"""
```
Você também vai querer incluir quaisquer instruções importantes descrevendo o que fazer e o que não fazer sobre como Claude deve interagir com o cliente. Isso pode se basear em guardrails da marca ou políticas de suporte.
```python
ADDITIONAL_GUARDRAILS = """Please adhere to the following guardrails:
1. Only provide information about insurance types listed in our offerings.
2. If asked about an insurance type we don't offer, politely state
that we don't provide that service.
3. Do not speculate about future product offerings or company plans.
4. Don't make promises or enter into agreements it's not authorized to make.
You only provide information and guidance.
5. Do not mention any competitor's products or services.
"""
```
Agora combine todas essas seções em uma única string para usar como seu prompt.
```python
TASK_SPECIFIC_INSTRUCTIONS = " ".join(
[
STATIC_GREETINGS_AND_GENERAL,
STATIC_CAR_INSURANCE,
STATIC_ELECTRIC_CAR_INSURANCE,
EXAMPLES,
ADDITIONAL_GUARDRAILS,
]
)
```
### Adicione capacidades dinâmicas e agênticas com uso de ferramentas
Claude é capaz de realizar ações e recuperar informações dinamicamente usando a funcionalidade de "tool use" (uso de ferramentas) do lado do cliente. Comece listando quaisquer ferramentas externas ou APIs que o prompt deve usar.
Para este exemplo, comece com uma ferramenta para calcular a cotação.
Como lembrete, esta ferramenta não realizará o cálculo real; ela apenas sinalizará à aplicação que uma ferramenta deve ser usada com os argumentos especificados.
Adicione o nome do modelo, a definição da ferramenta e uma implementação stub ao `config.py`:
```python
import time
MODEL = "claude-opus-5-5"
TOOLS = [
{
"name": "get_quote",
"description": "Calculate the insurance quote based on user input. Returned value is per month premium.",
"input_schema": {
"type": "object",
"properties": {
"make": {"type": "string", "description": "The make of the vehicle."},
"model": {"type": "string", "description": "The model of the vehicle."},
"year": {
"type": "integer",
"description": "The year the vehicle was manufactured.",
},
"mileage": {
"type": "integer",
"description": "The mileage on the vehicle.",
},
"driver_age": {
"type": "integer",
"description": "The age of the primary driver.",
},
},
"required": ["make", "model", "year", "mileage", "driver_age"],
},
}
]
def get_quote(make, model, year, mileage, driver_age):
"""Returns the premium per month in USD"""
# Você pode chamar um endpoint HTTP ou um banco de dados para obter a cotação.
# Aqui, simulamos um atraso de 1 segundo e retornamos uma cotação fixa de 100.
time.sleep(1)
return 100
```
### Implante seus prompts
É difícil saber quão bem seu prompt funciona sem implantá-lo em um ambiente de teste de produção e [executar avaliações](https://platform.claude.com/docs/pt-BR/test-and-evaluate/develop-tests). Construa uma pequena aplicação usando o prompt, o Anthropic SDK e o Streamlit para uma interface de usuário.
Em um arquivo chamado `chatbot.py` (ou o módulo equivalente na sua linguagem), configure a classe ChatBot, que encapsulará as interações com o Anthropic SDK.
A classe deve ter dois métodos principais: um que chama a API para gerar uma mensagem e outro que processa cada entrada do usuário recebida.
```python Python
# No seu chatbot.py, importe estes do config.py que você escreveu acima:
# from config import IDENTITY, TOOLS, MODEL, get_quote
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv()
class ChatBot:
def __init__(self, session_state):
self.anthropic = Anthropic()
self.session_state = session_state
def generate_message(
self,
messages,
max_tokens,
):
try:
response = self.anthropic.messages.create(
model=MODEL,
system=IDENTITY,
max_tokens=max_tokens,
messages=messages,
tools=TOOLS,
)
return response
except Exception as e:
return {"error": str(e)}
def process_user_input(self, user_input):
self.session_state.messages.append({"role": "user", "content": user_input})
response_message = self.generate_message(
messages=self.session_state.messages,
max_tokens=2048,
)
if "error" in response_message:
return f"An error occurred: {response_message['error']}"
if response_message.content[-1].type == "tool_use":
tool_use = response_message.content[-1]
func_name = tool_use.name
func_params = tool_use.input
tool_use_id = tool_use.id
result = self.handle_tool_use(func_name, func_params)
self.session_state.messages.append(
{"role": "assistant", "content": response_message.content}
)
self.session_state.messages.append(
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": f"{result}",
}
],
}
)
follow_up_response = self.generate_message(
messages=self.session_state.messages,
max_tokens=2048,
)
if "error" in follow_up_response:
return f"An error occurred: {follow_up_response['error']}"
response_text = next(
(
block.text
for block in follow_up_response.content
if block.type == "text"
),
None,
)
if response_text is None:
raise Exception("An error occurred: Unexpected response type")
self.session_state.messages.append(
{"role": "assistant", "content": response_text}
)
return response_text
text_block = next(
(block for block in response_message.content if block.type == "text"), None
)
if text_block is not None:
response_text = text_block.text
self.session_state.messages.append(
{"role": "assistant", "content": response_text}
)
return response_text
raise Exception("An error occurred: Unexpected response type")
def handle_tool_use(self, func_name, func_params):
if func_name == "get_quote":
premium = get_quote(**func_params)
return f"Quote generated: ${premium:.2f} per month"
raise Exception("An unexpected tool was used")
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
class ChatBot {
// IDENTITY, MODEL, TOOLS e getQuote espelham os valores de config.py definidos
// anteriormente neste guia (mostrados em Python).
readonly anthropic = new Anthropic();
readonly messages: Anthropic.MessageParam[] = [];
async generateMessage(
messages: Anthropic.MessageParam[],
maxTokens: number
): Promise {
return this.anthropic.messages.create({
model: MODEL,
system: IDENTITY,
max_tokens: maxTokens,
messages,
tools: TOOLS
});
}
async processUserInput(userInput: string): Promise {
this.messages.push({ role: "user", content: userInput });
const responseMessage = await this.generateMessage(this.messages, 2048);
const lastBlock = responseMessage.content.at(-1);
if (lastBlock?.type === "tool_use") {
const toolResult = this.handleToolUse(lastBlock.name, lastBlock.input);
this.messages.push({ role: "assistant", content: responseMessage.content });
this.messages.push({
role: "user",
content: [{ type: "tool_result", tool_use_id: lastBlock.id, content: toolResult }]
});
const followUpResponse = await this.generateMessage(this.messages, 2048);
const followUpBlock = followUpResponse.content.find((block) => block.type === "text");
if (!followUpBlock) {
throw new Error("An error occurred: Unexpected response type");
}
this.messages.push({ role: "assistant", content: followUpBlock.text });
return followUpBlock.text;
}
const firstBlock = responseMessage.content.find((block) => block.type === "text");
if (firstBlock) {
this.messages.push({ role: "assistant", content: firstBlock.text });
return firstBlock.text;
}
throw new Error("An error occurred: Unexpected response type");
}
handleToolUse(toolName: string, toolInput: unknown): string {
if (toolName === "get_quote") {
// O SDK tipa tool_use.input como unknown; restrinja-o ao schema de get_quote.
if (
toolInput === null ||
typeof toolInput !== "object" ||
!("make" in toolInput) ||
typeof toolInput.make !== "string" ||
!("model" in toolInput) ||
typeof toolInput.model !== "string" ||
!("year" in toolInput) ||
typeof toolInput.year !== "number" ||
!("mileage" in toolInput) ||
typeof toolInput.mileage !== "number" ||
!("driver_age" in toolInput) ||
typeof toolInput.driver_age !== "number"
) {
throw new Error("An error occurred: Unexpected tool input");
}
const { make, model: vehicleModel, year, mileage, driver_age: driverAge } = toolInput;
const premium = getQuote(make, vehicleModel, year, mileage, driverAge);
return `Quote generated: $${premium.toFixed(2)} per month`;
}
throw new Error("An unexpected tool was used");
}
}
```
```csharp C#
using System.Text.Json;
using Anthropic;
using Anthropic.Models.Messages;
// Config.Model, Config.Identity, Config.Tools e Config.GetQuote espelham
// os valores de config.py definidos anteriormente neste guia (mostrados em Python).
public class ChatBot
{
private readonly AnthropicClient _anthropic = new();
public List Messages { get; } = [];
public async Task GenerateMessage(List messages, long maxTokens) =>
await _anthropic.Messages.Create(
new MessageCreateParams
{
Model = Config.Model,
System = Config.Identity,
MaxTokens = maxTokens,
Messages = messages,
Tools = Config.Tools,
}
);
public async Task ProcessUserInput(string userInput)
{
Messages.Add(new() { Role = Role.User, Content = userInput });
var responseMessage = await GenerateMessage(Messages, maxTokens: 2048);
if (responseMessage.Content[^1].TryPickToolUse(out var toolUse))
{
var toolResult = HandleToolUse(toolUse.Name, toolUse.Input);
Messages.Add(new()
{
Role = Role.Assistant,
Content = responseMessage.Content
.Select(contentBlock => new ContentBlockParam(contentBlock.Json))
.ToList(),
});
Messages.Add(new()
{
Role = Role.User,
Content = new List
{
new ToolResultBlockParam { ToolUseID = toolUse.ID, Content = toolResult },
},
});
var followUpResponse = await GenerateMessage(Messages, maxTokens: 2048);
foreach (var block in followUpResponse.Content)
{
if (block.TryPickText(out var followUpText))
{
Messages.Add(new() { Role = Role.Assistant, Content = followUpText.Text });
return followUpText.Text;
}
}
throw new InvalidOperationException("An error occurred: Unexpected response type");
}
foreach (var block in responseMessage.Content)
{
if (block.TryPickText(out var textBlock))
{
Messages.Add(new() { Role = Role.Assistant, Content = textBlock.Text });
return textBlock.Text;
}
}
throw new InvalidOperationException("An error occurred: Unexpected response type");
}
public string HandleToolUse(string funcName, IReadOnlyDictionary funcParams)
{
if (funcName == "get_quote")
{
var premium = Config.GetQuote(
funcParams["make"].GetString()!,
funcParams["model"].GetString()!,
funcParams["year"].GetInt64(),
funcParams["mileage"].GetInt64(),
funcParams["driver_age"].GetInt64()
);
return $"Quote generated: ${premium:F2} per month";
}
throw new ArgumentException("An unexpected tool was used");
}
}
```
```go Go
import (
"context"
"encoding/json"
"fmt"
"github.com/anthropics/anthropic-sdk-go"
)
// ChatBot encapsula o cliente Anthropic e o histórico da conversa. Os
// valores de identity, model, tools e getQuote que ele usa espelham as definições
// de config.py mostradas anteriormente neste guia (em Python).
type ChatBot struct {
client anthropic.Client
messages []anthropic.MessageParam
}
func NewChatBot() *ChatBot {
return &ChatBot{client: anthropic.NewClient()}
}
func (bot *ChatBot) GenerateMessage(ctx context.Context, messages []anthropic.MessageParam, maxTokens int64) (*anthropic.Message, error) {
return bot.client.Messages.New(ctx, anthropic.MessageNewParams{
Model: model,
System: []anthropic.TextBlockParam{{Text: identity}},
MaxTokens: maxTokens,
Messages: messages,
Tools: tools,
})
}
func (bot *ChatBot) ProcessUserInput(ctx context.Context, userInput string) (string, error) {
bot.messages = append(bot.messages, anthropic.NewUserMessage(anthropic.NewTextBlock(userInput)))
response, err := bot.GenerateMessage(ctx, bot.messages, 2048)
if err != nil {
return "", err
}
lastBlock := response.Content[len(response.Content)-1]
if toolUse, ok := lastBlock.AsAny().(anthropic.ToolUseBlock); ok {
result, err := bot.HandleToolUse(toolUse.Name, toolUse.Input)
if err != nil {
return "", err
}
bot.messages = append(bot.messages,
response.ToParam(),
anthropic.NewUserMessage(anthropic.NewToolResultBlock(toolUse.ID, result, false)),
)
followUp, err := bot.GenerateMessage(ctx, bot.messages, 2048)
if err != nil {
return "", err
}
for _, block := range followUp.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
bot.messages = append(bot.messages, anthropic.NewAssistantMessage(anthropic.NewTextBlock(textBlock.Text)))
return textBlock.Text, nil
}
}
return "", fmt.Errorf("an error occurred: unexpected response type")
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
bot.messages = append(bot.messages, anthropic.NewAssistantMessage(anthropic.NewTextBlock(textBlock.Text)))
return textBlock.Text, nil
}
}
return "", fmt.Errorf("an error occurred: unexpected response type")
}
func (bot *ChatBot) HandleToolUse(toolName string, toolInput json.RawMessage) (string, error) {
if toolName != "get_quote" {
return "", fmt.Errorf("an unexpected tool was used: %s", toolName)
}
var input struct {
Make string `json:"make"`
Model string `json:"model"`
Year int `json:"year"`
Mileage int `json:"mileage"`
DriverAge int `json:"driver_age"`
}
if err := json.Unmarshal(toolInput, &input); err != nil {
return "", err
}
premium := getQuote(input.Make, input.Model, input.Year, input.Mileage, input.DriverAge)
return fmt.Sprintf("Quote generated: $%.2f per month", premium), nil
}
```
```java Java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.ContentBlock;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.MessageParam;
import com.anthropic.models.messages.ToolResultBlockParam;
import com.anthropic.models.messages.ToolUseBlock;
// IDENTITY, MODEL, TOOLS e getQuote espelham os valores do config.py definidos
// anteriormente neste guia (mostrados em Python).
class ChatBot {
final AnthropicClient anthropic;
final List messages;
ChatBot() {
// Lê a chave de API da variável de ambiente ANTHROPIC_API_KEY
this.anthropic = AnthropicOkHttpClient.fromEnv();
this.messages = new ArrayList<>();
}
Message generateMessage(List messages, long maxTokens) {
return anthropic.messages().create(MessageCreateParams.builder()
.model(MODEL)
.system(IDENTITY)
.maxTokens(maxTokens)
.messages(messages)
.tools(TOOLS)
.build());
}
String processUserInput(String userInput) {
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.content(userInput)
.build());
Message responseMessage = generateMessage(messages, 2048);
List content = responseMessage.content();
ContentBlock lastBlock = content.getLast();
if (lastBlock.isToolUse()) {
ToolUseBlock toolUse = lastBlock.asToolUse();
Map toolInput =
(Map) toolUse._input().asObject().orElseThrow();
String result = handleToolUse(toolUse.name(), toolInput);
messages.add(MessageParam.builder()
.role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(content.stream().map(ContentBlock::toParam).toList())
.build());
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(List.of(ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.content(result)
.build())))
.build());
Message followUpResponse = generateMessage(messages, 2048);
ContentBlock followUpBlock = followUpResponse.content().stream()
.filter(ContentBlock::isText)
.findFirst()
.orElseThrow(() -> new IllegalStateException("An error occurred: Unexpected response type"));
String responseText = followUpBlock.asText().text();
messages.add(MessageParam.builder()
.role(MessageParam.Role.ASSISTANT)
.content(responseText)
.build());
return responseText;
} else {
ContentBlock textBlock = content.stream()
.filter(ContentBlock::isText)
.findFirst()
.orElseThrow(() -> new IllegalStateException("An error occurred: Unexpected response type"));
String responseText = textBlock.asText().text();
messages.add(MessageParam.builder()
.role(MessageParam.Role.ASSISTANT)
.content(responseText)
.build());
return responseText;
}
}
String handleToolUse(String funcName, Map funcParams) {
return switch (funcName) {
case "get_quote" -> {
double premium = getQuote(
funcParams.get("make").asStringOrThrow(),
funcParams.get("model").asStringOrThrow(),
((Number) funcParams.get("year").asNumber().orElseThrow()).longValue(),
((Number) funcParams.get("mileage").asNumber().orElseThrow()).longValue(),
((Number) funcParams.get("driver_age").asNumber().orElseThrow()).longValue());
yield "Quote generated: $%.2f per month".formatted(premium);
}
default -> throw new IllegalArgumentException("An unexpected tool was used");
};
}
}
```
```php PHP
use Anthropic\Client;
use Anthropic\Messages\Message;
use Anthropic\Messages\MessageParam;
use Anthropic\Messages\TextBlock;
use Anthropic\Messages\ToolResultBlockParam;
use Anthropic\Messages\ToolUseBlock;
class ChatBot
{
// MODEL, IDENTITY, TOOLS e get_quote() espelham os valores de config.py
// definidos anteriormente neste guia (mostrados em Python).
/** @var list */
public private(set) array $messages = [];
public function __construct(
private readonly Client $anthropic = new Client(),
) {}
/**
* @param list $messages
*/
public function generateMessage(array $messages, int $maxTokens): Message
{
return $this->anthropic->messages->create(
model: MODEL,
system: IDENTITY,
maxTokens: $maxTokens,
messages: $messages,
tools: TOOLS,
);
}
public function processUserInput(string $userInput): string
{
$this->messages[] = MessageParam::with(role: 'user', content: $userInput);
$responseMessage = $this->generateMessage($this->messages, maxTokens: 2048);
$content = $responseMessage->content;
$lastBlock = array_last($content);
if ($lastBlock instanceof ToolUseBlock) {
$toolResult = $this->handleToolUse($lastBlock->name, $lastBlock->input);
$this->messages[] = MessageParam::with(role: 'assistant', content: $content);
$this->messages[] = MessageParam::with(
role: 'user',
content: [
ToolResultBlockParam::with(toolUseID: $lastBlock->id, content: $toolResult),
],
);
$followUpResponse = $this->generateMessage($this->messages, maxTokens: 2048);
$firstBlock = array_find(
$followUpResponse->content,
static fn ($block): bool => $block instanceof TextBlock,
);
if (!$firstBlock instanceof TextBlock) {
throw new \RuntimeException('An error occurred: Unexpected response type');
}
$this->messages[] = MessageParam::with(role: 'assistant', content: $firstBlock->text);
return $firstBlock->text;
}
$firstBlock = array_find($content, static fn ($block): bool => $block instanceof TextBlock);
if ($firstBlock instanceof TextBlock) {
$this->messages[] = MessageParam::with(role: 'assistant', content: $firstBlock->text);
return $firstBlock->text;
}
throw new \RuntimeException('An error occurred: Unexpected response type');
}
/**
* @param array $funcParams
*/
private function handleToolUse(string $funcName, array $funcParams): string
{
if ($funcName === 'get_quote') {
$premium = get_quote(...$funcParams);
return sprintf('Quote generated: $%.2f per month', $premium);
}
throw new \RuntimeException('An unexpected tool was used');
}
}
```
```ruby Ruby
# IDENTITY, MODEL, TOOLS e get_quote espelham os valores de config.py definidos
# anteriormente neste guia (mostrados em Python).
require "anthropic"
class ChatBot
attr_reader :messages
def initialize
@anthropic = Anthropic::Client.new
@messages = []
end
def generate_message(messages, max_tokens)
@anthropic.messages.create(
model: MODEL,
system_: IDENTITY,
max_tokens:,
messages:,
tools: TOOLS
)
end
def process_user_input(user_input)
@messages << {role: "user", content: user_input}
response_message = generate_message(@messages, 2048)
case response_message.content
in [*, Anthropic::ToolUseBlock => tool_use]
result = handle_tool_use(tool_use.name, tool_use.input)
@messages << {role: "assistant", content: response_message.content}
@messages << {
role: "user",
content: [{type: "tool_result", tool_use_id: tool_use.id, content: result}]
}
follow_up_response = generate_message(@messages, 2048)
case follow_up_response.content
in [*, Anthropic::TextBlock => text_block, *]
@messages << {role: "assistant", content: text_block.text}
text_block.text
else
raise "An error occurred: Unexpected response type"
end
in [*, Anthropic::TextBlock => text_block, *]
@messages << {role: "assistant", content: text_block.text}
text_block.text
else
raise "An error occurred: Unexpected response type"
end
end
def handle_tool_use(tool_name, tool_input)
raise "An unexpected tool was used" unless tool_name == "get_quote"
premium = get_quote(**tool_input)
format("Quote generated: $%.2f per month", premium)
end
end
```
### Construa sua interface de usuário
Teste a implantação deste código com Streamlit usando um método main. Esta função `main()` configura uma interface de chat baseada em Streamlit. Streamlit é um framework Python, portanto esta parte do passo a passo é mostrada apenas em Python; a classe ChatBot acima é a parte que você pode portar para qualquer linguagem.
Faça isso em um arquivo chamado `app.py`
```python
import streamlit as st
from chatbot import ChatBot
from config import TASK_SPECIFIC_INSTRUCTIONS
def main():
st.title("Chat with Eva, Acme Insurance Company's Assistant🤖")
if "messages" not in st.session_state:
st.session_state.messages = [
{"role": "user", "content": TASK_SPECIFIC_INSTRUCTIONS},
{"role": "assistant", "content": "Understood"},
]
chatbot = ChatBot(st.session_state)
# Exibe mensagens do usuário e do assistente, pulando as duas primeiras
for message in st.session_state.messages[2:]:
# ignora blocos de uso de ferramentas
if isinstance(message["content"], str):
with st.chat_message(message["role"]):
st.markdown(message["content"])
if user_msg := st.chat_input("Type your message here..."):
st.chat_message("user").markdown(user_msg)
with st.chat_message("assistant"):
with st.spinner("Eva is thinking..."):
response_placeholder = st.empty()
full_response = chatbot.process_user_input(user_msg)
response_placeholder.markdown(full_response)
if __name__ == "__main__":
main()
```
Execute o programa com:
```bash
streamlit run app.py
```
### Avalie seus prompts
O prompting frequentemente requer testes e otimização para estar pronto para produção. Para determinar a prontidão da sua solução, avalie o desempenho do chatbot usando um processo sistemático que combine métodos quantitativos e qualitativos. Criar uma [avaliação empírica forte](https://platform.claude.com/docs/pt-BR/test-and-evaluate/develop-tests#build-evaluations) com base nos seus critérios de sucesso definidos permitirá que você otimize seus prompts.
### Melhore o desempenho
Em cenários complexos, pode ser útil considerar estratégias adicionais para melhorar o desempenho além das [técnicas de engenharia de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/overview) padrão e das [estratégias de implementação de guardrails](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Aqui estão alguns cenários comuns:
#### Reduza a latência de contexto longo com RAG
Ao lidar com grandes quantidades de contexto estático e dinâmico, incluir todas as informações no prompt pode levar a custos altos, tempos de resposta mais lentos e ao atingimento dos limites da "context window" (janela de contexto). Nesse cenário, implementar técnicas de "Retrieval Augmented Generation" (geração aumentada por recuperação), ou RAG, pode melhorar o desempenho e a eficiência.
Você pode criar um sistema mais escalável e responsivo convertendo informações em representações vetoriais com [modelos de embedding](https://platform.claude.com/docs/pt-BR/build-with-claude/embeddings), como os da Voyage AI by MongoDB. Essa abordagem permite a recuperação dinâmica de informações relevantes com base na consulta atual, em vez de incluir todo o contexto possível em cada prompt.
A implementação de RAG para casos de uso de suporte demonstrou aumentar a precisão, reduzir os tempos de resposta e reduzir os custos de API em sistemas com requisitos extensos de contexto. Consulte a [receita de RAG](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide) para um exemplo prático.
#### Integre dados em tempo real com uso de ferramentas
Ao lidar com consultas que exigem informações em tempo real, como saldos de contas ou detalhes de apólices, abordagens de RAG baseadas em embeddings não são suficientes. Em vez disso, o uso de ferramentas pode aprimorar a capacidade do seu chatbot de fornecer respostas precisas e em tempo real. Por exemplo, você pode usar o uso de ferramentas para consultar informações do cliente, recuperar detalhes de pedidos e cancelar pedidos em nome do cliente.
Essa abordagem, [descrita na receita de uso de ferramentas: agente de atendimento ao cliente](https://platform.claude.com/cookbook/tool-use-customer-service-agent), permite integrar dados ao vivo nas respostas do Claude e fornecer uma experiência do cliente mais personalizada e eficiente.
#### Fortaleça os guardrails de entrada e saída
Ao implantar um chatbot, especialmente em cenários de atendimento ao cliente, é importante prevenir riscos associados a uso indevido, consultas fora do escopo e respostas inadequadas. Embora Claude seja inerentemente resiliente a tais cenários, aqui estão etapas adicionais para fortalecer os guardrails do seu chatbot:
* [Reduzir alucinações](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/reduce-hallucinations): Implemente mecanismos de verificação de fatos e [citações](https://platform.claude.com/cookbook/misc-using-citations) para fundamentar as respostas nas informações fornecidas.
* Verificar informações de forma cruzada: Verifique se as respostas do agente estão alinhadas com as políticas da sua empresa e fatos conhecidos.
* Evitar compromissos contratuais: Garanta que o agente não faça promessas ou firme acordos que não está autorizado a fazer.
* [Mitigar jailbreaks](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks): Use métodos como filtros de inofensividade e validação de entrada para impedir que usuários explorem vulnerabilidades do modelo com o objetivo de gerar conteúdo inadequado.
* Evitar mencionar concorrentes: Implemente um filtro de menção a concorrentes para manter o foco na marca e não mencionar produtos ou serviços de nenhum concorrente.
* [Aumentar a consistência da saída](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/increase-consistency): Impeça que Claude mude de estilo ou saia do personagem, mesmo durante interações longas e complexas.
* Remover Informações de Identificação Pessoal (PII): A menos que explicitamente exigido e autorizado, remova qualquer PII das respostas.
#### Reduza o tempo de resposta percebido com streaming
Ao lidar com respostas potencialmente longas, implementar "streaming" (streaming) pode melhorar o engajamento e a satisfação do usuário. Nesse cenário, os usuários recebem a resposta progressivamente em vez de esperar que toda a resposta seja gerada.
Veja como implementar streaming:
1. Use a [API de Streaming da Anthropic](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming) para suportar respostas em streaming.
2. Configure seu frontend para lidar com os fragmentos de texto recebidos.
3. Exiba cada fragmento à medida que chega, simulando digitação em tempo real.
4. Implemente um mecanismo para salvar a resposta completa, permitindo que os usuários a visualizem se saírem e retornarem.
Em alguns casos, o streaming permite o uso de modelos mais avançados com latências base mais altas, pois a exibição progressiva mitiga o impacto de tempos de processamento mais longos.
#### Escale seu chatbot
À medida que a complexidade do seu chatbot cresce, a arquitetura da sua aplicação pode evoluir para acompanhar. Antes de adicionar mais camadas à sua arquitetura, considere as seguintes opções menos exaustivas:
* Certifique-se de que está aproveitando ao máximo seus prompts e otimizando por meio de engenharia de prompt. Use os [guias de engenharia de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/overview) para escrever os prompts mais eficazes.
* Adicione [ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview) adicionais ao prompt (que podem incluir [cadeias de prompts](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices#chain-complex-prompts)) e veja se consegue alcançar a funcionalidade necessária.
Se o seu chatbot lida com tarefas incrivelmente variadas, você pode considerar adicionar um [classificador de intenção separado](https://platform.claude.com/cookbook/capabilities-classification-guide) para rotear a consulta inicial do cliente. Para a aplicação existente, isso envolveria criar uma árvore de decisão que rotearia as consultas dos clientes pelo classificador e depois para conversas especializadas (com seu próprio conjunto de ferramentas e prompts do sistema). Observe que esse método requer uma chamada adicional ao Claude, o que pode aumentar a latência.
### Integre Claude ao seu fluxo de trabalho de suporte
Embora esses exemplos tenham se concentrado em funções Python que podem ser chamadas dentro de um ambiente Streamlit, implantar Claude para um chatbot de suporte em tempo real requer um serviço de API.
Veja como você pode abordar isso:
1. Crie um wrapper de API: Desenvolva um wrapper de API simples em torno da sua função de classificação. Por exemplo, você pode usar Flask API ou Fast API para encapsular seu código em um serviço HTTP. Seu serviço HTTP poderia aceitar a entrada do usuário e retornar a resposta do Assistant em sua totalidade. Assim, seu serviço poderia ter as seguintes características:
* Server-Sent Events (SSE): SSE permite o streaming em tempo real de respostas do servidor para o cliente. Isso proporciona uma experiência fluida e interativa ao trabalhar com LLMs.
* Cache: Implementar cache pode melhorar os tempos de resposta e reduzir chamadas de API desnecessárias.
* Retenção de contexto: Manter o contexto quando um usuário sai e retorna é importante para a continuidade das conversas.
2. Construa uma interface web: Implemente uma UI web amigável para interagir com o agente baseado em Claude.
## Próximos passos
Dê ao Claude acesso às suas APIs para que ele possa agir em nome dos clientes.
Crie avaliações para medir seu agente de suporte em relação aos critérios de sucesso que você definiu.
Transmita respostas em streaming para que os clientes vejam as respostas à medida que são geradas.
Refine seu prompt do sistema e exemplos para um melhor desempenho nas tarefas.