Gerenciamento de Credenciais

José David Atualizado por José David

As credenciais são informações confidenciais (como chaves de API, tokens ou senhas) que suas ferramentas precisam para se conectar com segurança a serviços externos.

O gerenciamento adequado das credenciais é fundamental em dois momentos-chave do ciclo de vida do seu agente:

  1. Durante o desenvolvimento, para realizar testes locais das suas ferramentas.
  2. Em produção, para garantir que seu agente funcione de forma segura nos canais integrados à Plataforma Weni.

Estrutura no agent_definition.yaml

Primeiro, você deve declarar todas as credenciais que seu agente precisará na seção credentials do seu arquivo de definição.

agents:
  mi_agente:
    credentials:
      API_KEY:
        label: "API Key do Serviço"
        placeholder: "Insira sua API Key aqui"
        is_confidential: true
      API_SECRET:
        label: "API Secret do Serviço"
        placeholder: "your-api-secret-here"
      BASE_URL:
        label: "URL Base da API"
        placeholder: "https://api.example.com"
        is_confidential: false

Cada credencial possui os seguintes atributos:

  • label: Nome legível exibido na interface da Plataforma Weni.
  • placeholder: Texto de ajuda exibido no campo de entrada para orientar o usuário.
  • is_confidential: Booleano (true/false) que indica se a credencial contém informações sensíveis. O padrão é true.

Credenciais em Produção

Quando você implanta seu agente na Plataforma Weni, as credenciais são gerenciadas pela interface do usuário para garantir o máximo de segurança.

Fluxo de Trabalho em Produção
  1. Definição no YAML: Declare as credenciais no seu agent_definition.yaml. Por exemplo, usando o agente CEP, você pode configurá-las assim:
agents:
  cep_agent:
    credentials:
      api_key:
        label: "API Key"
        placeholder: "Enter your API key"
    name: "CEP Agent"
    description: "Weni's CEP agent with components"
    instructions:
      # Resto da definição do agente...
  1. Implante seu Agente: Execute weni project push agent_definition.yaml. A plataforma detectará automaticamente as credenciais definidas.
  2. Configure na Interface: Um administrador poderá configurar os valores reais das credenciais diretamente pela interface da Plataforma Weni, sem precisar alterar o código.

Ao atribuir seu agente na galeria de Agentes Personalizados, a plataforma solicitará que você preencha os valores de cada credencial definida.

Nota Na Plataforma Weni, as credenciais são: armazenadas de forma criptografada, nunca exibidas em logs ou interfaces de usuário, injetadas com segurança no context das suas ferramentas durante a execução.

Acesso às Credenciais no Código

O acesso às credenciais dentro do código da sua ferramenta é sempre feito por meio do objeto context.

from weni import Tool, Context
from weni.responses import TextResponse
import requests

class GetAddressWithAuth(Tool):
    def execute(self, context: Context) -> TextResponse:
        # Obtém parâmetros do contexto
        cep = context.parameters.get("cep", "")

        # Obtém credenciais do contexto de forma segura
        api_key = context.credentials.get("api_key")

        address_response = self.get_address_by_cep(cep=cep, api_key=api_key)

        return TextResponse(data=address_response)

    # ... Resto do código ...

A linha essencial é api_key = context.credentials.get("api_key"). Ela recupera o valor da credencial definida no YAML e fornecida pela Plataforma Weni ou pelos arquivos de teste locais.

Nota Importante: Nunca escreva credenciais diretamente no código da sua ferramenta. Acesse-as sempre através do objeto Context para garantir segurança e consistência entre ambientes.

Credenciais para Testes Locais

Durante o desenvolvimento, você precisará fornecer valores de teste para suas ferramentas e executá-las localmente com weni run.

Usando .env

Crie um arquivo chamado .env dentro do diretório da sua ferramenta (o especificado em source.path).

Os nomes das variáveis no arquivo .env devem coincidir exatamente com as chaves declaradas na seção credentials do seu arquivo YAML.

Por exemplo, se o seu agente CEP tiver as seguintes credenciais:

agents:
  cep_agent:
    credentials:
      api_key:
        label: "API Key"
        placeholder: "Enter your API key"
    # Resto do agent_definition...

O arquivo .env deve estar em: tools/get_address/.env e conter:

api_key=your-development-api-key

A CLI lerá esse arquivo automaticamente e tornará os valores disponíveis em context.credentials durante o weni run.

Usando test_definition.yaml

Para testes rápidos ou para usar credenciais diferentes em cada caso, é possível defini-las diretamente dentro do test_definition.yaml.

Esse método permite aninhar um bloco credentials dentro de um teste específico:

tests:
  teste_com_credencial_especifica:
    parameters:
      cep: "57160000"
    credentials:
      API_KEY: "valor_de_teste_apenas_para_este_caso"

Para mais informações sobre testes locais, consulte a seção Testes Locais #####.

Este método é menos recomendado do que o uso de .env. Se optar por utilizá-lo, tenha extremo cuidado com o gerenciamento de repositórios, pois fazer upload do test_definition.yaml pode expor dados sensíveis.

Embora útil em alguns casos, este método é menos seguro que o uso de .env.

O principal risco é a exposição acidental das credenciais ao enviar este arquivo para um repositório público (como GitHub). Um .env geralmente está no .gitignore por padrão, mas nem sempre é o caso dos arquivos de teste.

Dica Profissional: Se decidir usar este método, certifique-se de adicionar o arquivo test_definition.yaml ao seu .gitignore para evitar vazamentos de segurança.

Como a gente se saiu?

Ferramentas (Tools)

untitled article

Contato