Integração com API

Ferramentas de Integração com API permitem que seu agente chame APIs REST externas durante conversas. Isso habilita busca de dados em tempo real, execução de ações e integração perfeita com seus sistemas de negócio existentes.

Visão Geral

Com Integração com API, seu agente pode:

Buscar dados em tempo real - Verificar status de pedido, saldos de conta, níveis de estoque
Executar ações - Criar tickets, atualizar registros, enviar notificações
Integrar sistemas - Conectar a CRMs, ERPs, backends customizados

Usuário: "Qual é o status do meu pedido #12345?"
        ↓
Agente chama: GET /api/orders/12345
        ↓
API retorna: { "status": "enviado", "tracking": "1Z999..." }
        ↓
Agente responde: "Seu pedido #12345 foi enviado!
                  Aqui está o número de rastreamento: 1Z999..."

Criando uma Ferramenta de API

Passo 1: Informações Básicas

Campo	Descrição	Exemplo
Nome	Identificador da ferramenta (usado internamente)	`verificar_status_pedido`
Descrição	Quando usar esta ferramenta (crítico!)	"Recupera o status atual de um pedido de cliente. Use quando cliente perguntar sobre pedido, envio ou entrega."

Descrição é Crítica

A descrição diz à IA quando usar esta ferramenta. Uma descrição vaga leva à ferramenta sendo usada incorretamente ou não sendo usada. Seja específico sobre os cenários onde esta ferramenta se aplica.

Passo 2: Configuração do Endpoint

Campo	Descrição	Exemplo
Método	Método HTTP	GET, POST, PUT, DELETE
URL	URL do endpoint	`https://api.suaempresa.com/orders/{order_id}`
Headers	Headers da requisição	`Authorization: Bearer`

Usando Parâmetros de Path

Inclua parâmetros na URL com chaves:

https://api.exemplo.com/customers/{customer_id}/orders/{order_id}

O agente extrairá valores da conversa para preencher estes parâmetros.

Passo 3: Configuração da Requisição

Headers

Adicione quaisquer headers necessários:

Content-Type: application/json
Authorization: Bearer {{api_key}}
X-Request-ID: {{$uuid}}

Usando Variáveis

- Referencia credenciais armazenadas com segurança
- Gera um ID de requisição único
- Timestamp Unix atual

Parâmetros de Query

Para requisições GET com query strings:

Parâmetro	Valor
`status`
`limit`	`10`

Corpo da Requisição (POST/PUT)

Para requisições com corpo, defina o schema JSON:

json

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Identificador único do cliente"
    },
    "message": {
      "type": "string",
      "description": "Conteúdo da mensagem de suporte"
    }
  },
  "required": ["customer_id", "message"]
}

Descrições do Schema Importam

O campo description no seu schema ajuda o agente a entender quais dados coletar. Escreva descrições como se estivesse explicando para um humano.

Passo 4: Tratamento de Resposta

Configure como o agente interpreta respostas da API:

Campo	Descrição
Códigos de sucesso	Códigos HTTP que indicam sucesso (ex: 200, 201)
Mapeamento de resposta	Como extrair dados úteis das respostas

Exemplo: Ferramenta de Status de Pedido

Configuração

Nome: verificar_status_pedido

Descrição:

Recupera o status atual de um pedido de cliente incluindo informações de envio e data estimada de entrega. Use quando um cliente perguntar sobre status do pedido, onde está o pacote, ou quando vai chegar.

Método: GET

URL: https://api.suaempresa.com/v1/orders/{order_id}

Headers:

Authorization: Bearer {{orders_api_key}}
Content-Type: application/json

Parâmetros de Path:

Parâmetro	Descrição
`order_id`	Número do pedido fornecido pelo cliente

Resposta Esperada

json

{
  "order_id": "PED-12345",
  "status": "enviado",
  "items": [
    { "name": "Widget Pro", "quantity": 2 }
  ],
  "shipping": {
    "carrier": "Correios",
    "tracking_number": "SS123456789BR",
    "estimated_delivery": "2025-01-20"
  }
}

Exemplo de Conversa

Cliente: "Oi, fiz um pedido semana passada. Número do pedido é 12345. Onde está?"
Agente: [Chama verificar_status_pedido com order_id="12345"]
"Encontrei seu pedido #12345! Ele está atualmente enviado e a caminho. Está sendo entregue pelos Correios com número de rastreamento SS123456789BR. A data estimada de entrega é 20 de janeiro. Gostaria que eu explicasse como rastrear?"

Exemplo: Criar Ticket de Suporte

Configuração

Nome: criar_ticket_suporte

Descrição:

Cria um novo ticket de suporte no sistema de helpdesk. Use quando um cliente reportar um problema que não pode ser resolvido imediatamente, precisa ser escalado, ou solicita um callback.

Método: POST

URL: https://api.suaempresa.com/v1/tickets

Headers:

Authorization: Bearer {{helpdesk_api_key}}
Content-Type: application/json

Schema do Corpo da Requisição:

json

{
  "type": "object",
  "properties": {
    "customer_email": {
      "type": "string",
      "description": "Endereço de email do cliente"
    },
    "subject": {
      "type": "string",
      "description": "Resumo breve do problema"
    },
    "description": {
      "type": "string",
      "description": "Descrição detalhada do problema"
    },
    "priority": {
      "type": "string",
      "enum": ["baixa", "media", "alta", "urgente"],
      "description": "Prioridade do ticket baseada na severidade do problema"
    }
  },
  "required": ["customer_email", "subject", "description"]
}

Exemplo de Conversa

Cliente: "Minha conta está bloqueada há dois dias e não consigo acessar meus dados. Isso está afetando meu negócio!"
Agente: "Entendo que isso é urgente—deixe-me criar um ticket de suporte prioritário para você agora mesmo. Poderia confirmar seu endereço de email?"
Cliente: "É joao@empresa.com"
Agente: [Cria ticket com priority="urgente"]
"Criei um ticket de suporte urgente para você. Seu número de ticket é #45678. Nossa equipe vai priorizar isso e entrar em contato nas próximas 2 horas. Há algo mais em que eu possa ajudar enquanto você aguarda?"

Melhores Práticas

1. Valide Antes de Chamar

Instrua seu agente a confirmar informações necessárias antes de fazer chamadas de API:

markdown

Antes de chamar APIs externas:
- Confirme que você tem todas as informações necessárias
- Verifique identificadores com o cliente: "Só para confirmar, seu número de pedido é 12345?"
- Não adivinhe ou assuma valores

2. Trate Erros Graciosamente

Configure respostas de erro nas suas instruções:

markdown

## Tratamento de Erros de API
Se uma chamada de API falhar:
- Não exponha detalhes técnicos
- Peça desculpas: "Estou tendo dificuldade para acessar essa informação agora."
- Ofereça alternativas: "Gostaria que eu conectasse você com um membro da equipe?"
- Registre o problema (o sistema trata isso automaticamente)

3. Rate Limiting

Esteja atento a limites de taxa de API:

Configure timeouts apropriados
Evite chamar a mesma API repetidamente em uma conversa
Use cache de resultados quando possível (tratado pela plataforma)

4. Considerações de Segurança

Nunca coloque chaves de API diretamente na URL ou corpo
Use o sistema de credenciais seguras para valores sensíveis
Considere quais dados devem ser expostos aos usuários finais
Use chaves de API somente leitura quando possível

Solução de Problemas

Ferramenta Não Está Sendo Usada

Verifique a descrição—está claro quando usar esta ferramenta?
Verifique se as instruções do agente não contradizem o uso da ferramenta
Teste no Playground com solicitações explícitas

Parâmetros Incorretos

Revise descrições do schema—estão claras?
Adicione exemplos para ajudar o agente a entender formatos esperados
Use enum para campos com valores válidos limitados

Erros de API

Verifique credenciais de autenticação
Verifique se a URL do endpoint está correta
Teste a API independentemente com os mesmos parâmetros
Verifique problemas de CORS se chamando de deploys baseados em browser

Documentação Relacionada

Visão Geral de Ferramentas - Entendendo ferramentas de agentes
Ferramentas Manuais - Para integrações complexas
Base de Conhecimento - Q&A baseado em documentos

Agentes

Configuração

Ferramentas

Avançado

Implantando Agentes

Configurações

Integração com API

Visão Geral

Criando uma Ferramenta de API

Passo 1: Informações Básicas

Passo 2: Configuração do Endpoint

Usando Parâmetros de Path

Passo 3: Configuração da Requisição

Headers

Parâmetros de Query

Corpo da Requisição (POST/PUT)

Passo 4: Tratamento de Resposta

Exemplo: Ferramenta de Status de Pedido

Configuração

Resposta Esperada

Exemplo de Conversa

Exemplo: Criar Ticket de Suporte

Configuração

Exemplo de Conversa

Melhores Práticas

1. Valide Antes de Chamar

2. Trate Erros Graciosamente

3. Rate Limiting

4. Considerações de Segurança

Solução de Problemas

Ferramenta Não Está Sendo Usada

Parâmetros Incorretos

Erros de API

Documentação Relacionada

Configuração

Ferramentas

Avançado

Implantando Agentes

Integração com API ​

Visão Geral ​

Criando uma Ferramenta de API ​

Passo 1: Informações Básicas ​

Passo 2: Configuração do Endpoint ​

Usando Parâmetros de Path ​

Passo 3: Configuração da Requisição ​

Headers ​

Parâmetros de Query ​

Corpo da Requisição (POST/PUT) ​

Passo 4: Tratamento de Resposta ​

Exemplo: Ferramenta de Status de Pedido ​

Configuração ​

Resposta Esperada ​

Exemplo de Conversa ​

Exemplo: Criar Ticket de Suporte ​

Configuração ​

Exemplo de Conversa ​

Melhores Práticas ​

1. Valide Antes de Chamar ​

2. Trate Erros Graciosamente ​

3. Rate Limiting ​

4. Considerações de Segurança ​

Solução de Problemas ​

Ferramenta Não Está Sendo Usada ​

Parâmetros Incorretos ​

Erros de API ​

Documentação Relacionada ​

Integração com API

Visão Geral

Criando uma Ferramenta de API

Passo 1: Informações Básicas

Passo 2: Configuração do Endpoint

Usando Parâmetros de Path

Passo 3: Configuração da Requisição

Headers

Parâmetros de Query

Corpo da Requisição (POST/PUT)

Passo 4: Tratamento de Resposta

Exemplo: Ferramenta de Status de Pedido

Configuração

Resposta Esperada

Exemplo de Conversa

Exemplo: Criar Ticket de Suporte

Configuração

Exemplo de Conversa

Melhores Práticas

1. Valide Antes de Chamar

2. Trate Erros Graciosamente

3. Rate Limiting

4. Considerações de Segurança

Solução de Problemas

Ferramenta Não Está Sendo Usada

Parâmetros Incorretos

Erros de API

Documentação Relacionada