Credential Management

José David Updated by José David

Credentials are confidential information (such as API keys, tokens, or passwords) that your tools need to securely connect to external services.

Proper credential management is essential at two key moments in your agent’s lifecycle:

  1. During development, to perform local testing of your tools.
  2. In production, to ensure your agent operates securely in the channels integrated with the Weni Platform.

Structure in agent_definition.yaml

First, you must declare all the credentials your agent will need in the credentials section of your definition file.

agents:
  mi_agente:
    credentials:
      API_KEY:
        label: "Service API Key"
        placeholder: "Enter your API Key here"
        is_confidential: true
      API_SECRET:
        label: "Service API Secret"
        placeholder: "your-api-secret-here"
      BASE_URL:
        label: "API Base URL"
        placeholder: "https://api.example.com"
        is_confidential: false

Each credential has the following attributes:

  • label: The readable name displayed in the Weni Platform interface.
  • placeholder: Helper text shown in the input field to guide the user.
  • is_confidential: A boolean (true/false) that indicates whether the credential contains sensitive information. Default is true.

Credentials in Production

When you deploy your agent to the Weni Platform, credentials are managed through the user interface to ensure maximum security.

Production Workflow
  1. Definition in YAML: Declare credentials in your agent_definition.yaml. For example, using the CEP agent, you might configure credentials like this:
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:
      # Rest of the agent definition...
  1. Deploy Your Agent: Run weni project push agent_definition.yaml. The platform will automatically detect the credentials you defined.
  2. Configure in the Interface: An administrator can configure the actual credential values through the Weni Platform interface, without modifying the code.

When assigning your agent from the “Custom Agents” gallery, the platform will prompt you to enter values for each defined credential.

On the Weni Platform, credentials are: Stored encrypted, never exposed in logs or user interfaces, securely injected into your tool’s context during execution.

Accessing Credentials in Code

Credentials are always accessed from within your tool’s code using the context object.

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

class GetAddressWithAuth(Tool):
    def execute(self, context: Context) -> TextResponse:
        # Get parameters from context
        cep = context.parameters.get("cep", "")

        # Securely get credentials from context
        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)

    # ... Rest of the code ...

The key line is api_key = context.credentials.get("api_key"). This retrieves the credential value defined in your YAML and provided either through the Weni Platform or your local test files.

Never hardcode credentials directly in your tool’s code. Always access them through the Context object to ensure your code remains secure and consistent across environments.

Credentials for Local Testing

During development, you need a way to provide test values to your tools so you can run them locally with weni run.

Using .env

Create a file called .env inside your tool’s directory (the one defined in source.path).

The variable names in the .env file must exactly match the keys declared in the credentials section of your YAML file.

For example, if your CEP agent has the following credentials:

agents:
  cep_agent:
    credentials:
      api_key:
        label: "API Key"
        placeholder: "Enter your API key"
    # Rest of the agent_definition...

Your .env file should be located at: tools/get_address/.env and have the following structure:

api_key=your-development-api-key

The CLI will automatically read this file and make these values available in context.credentials during weni run.

Using test_definition.yaml

For quick tests or when using different credentials for each test case, you can define them directly within your test_definition.yaml.

This method allows you to nest a credentials block inside a specific test:

tests:
  test_with_specific_credential:
    parameters:
      cep: "57160000"
    credentials:
      API_KEY: "test_value_for_this_case"

For more information on local testing, refer to the Local Testing ### section.

This approach is less recommended than using .env. If you choose to use it, be very careful with repository management, uploading your test_definition.yaml could expose sensitive data.

Although it can be useful, this method is less secure than using a .env file.

The main risk is that you might accidentally leak your credentials if you upload this file to a public repository like GitHub. A .env file is usually ignored by default, but that’s not always the case for test files.

Pro Tip: If you decide to use this approach, make sure your test_definition.yaml file is added to your .gitignore to prevent security leaks.

How did we do?

Tools

Contact