Weni by VTEX

Weni by VTEX CLI

Learn how to create, configure, and deploy agents using the Weni by VTEX CLI, with some examples of agents.

Working with Agents

Learn how to create, configure, and deploy AI agents using Weni by VTEX CLI.

Agent Definition File

Agents are defined using YAML files. Here's the basic structure:


_22agents:
_22   agent_id:
_22      name: "Agent Name"
_22      description: "Agent Description"
_22      instructions:
_22         - "Instruction 1"
_22         - "Instruction 2"
_22      guardrails:
_22         - "Guardrail 1"
_22      tools:
_22         - tool_name:
_22            name: "Tool Name"
_22            source:
_22               path: "tools/tool_name"
_22               entrypoint: "main.ToolClass"
_22            description: "Tool Description"
_22            parameters:
_22               - param_name:
_22                  description: "Parameter Description"
_22                  type: "string"
_22                  required: true
_22                  contact_field: true

Key Components

Agent ID
- Unique identifier for your agent
- Used internally by the system
Basic Information
- name: Display name (max 55 characters)
- description: Brief description of the agent's purpose
Instructions
- Guide the agent's behavior
- Minimum 40 characters each
- Should be clear and specific
Guardrails
- Define boundaries and limitations
- Prevent unwanted behavior
Tools
- Custom functionalities
- Implemented as Python classes using the Weni by VTEX SDK

Tool Source Configuration

The source field is critical for locating and executing your tool:


_10source:
_10  path: "tools/tool_name"
_10  entrypoint: "main.ToolClass"

path: Points to the directory containing your tool implementation
- Example: tools/get_address refers to a folder named get_address inside a tools directory
- This folder should contain your Python modules and requirements.txt
entrypoint: Specifies which class to use in which file
- Format: filename.ClassName
- Example: main.GetAddress means:
  - Look for a file named main.py in the path directory
  - Find a class named GetAddress inside that file
  - This class must inherit from the Tool class

Your directory structure should look like:


_10project/
_10├── agents.yaml
_10└── tools/
_10    └── get_address/
_10        ├── main.py             # Contains GetAddress class
_10        └── requirements.txt    # Dependencies

Creating Tools

Tool Implementation Structure


_19from weni import Tool
_19from weni.context import Context
_19from weni.responses import TextResponse
_19
_19class ToolName(Tool):
_19    def execute(self, context: Context) -> TextResponse:
_19        # Extract parameters
_19        parameters = context.parameters
_19        param_value = parameters.get("param_name", "")
_19        
_19        # Process the request
_19        result = self.process_request(param_value)
_19        
_19        # Return response
_19        return TextResponse(data=result)
_19        
_19    def process_request(self, param_value):
_19        # Your business logic here
_19        return {"key": "value"}

Important Requirements

The class must inherit from Tool
The class must implement the execute method
The class name must match the class name in your entrypoint

Deploying Agents

Push Command

Deploy your agent using:


_10weni project push agents.yaml

The command:

Validates your YAML
Uploads tools
Creates/updates the agent

Deployment Best Practices

Version Control
- Keep agent definitions in version control
- Document changes
Testing
- Test locally when possible
- Start with staging environment
- Verify all tools work
Organization
- Use clear file names
- Keep related files together
- Document dependencies

Advanced Topics

Parameter Types

Available parameter types:

string
number
integer
boolean
array

Response Formats

Tools can return:

Text responses via TextResponse
Structured data
Error messages

Error Handling

Your tools should:

Validate inputs
Handle exceptions gracefully
Return meaningful error messages

Troubleshooting

Common Issues

Deployment Failures
- Check YAML syntax
- Verify tool paths
- Confirm project selection
Tool Errors
- Verify tool entrypoint (class name)
- Test tool class locally
- Check parameter handling in context
- Verify API endpoints
Agent Behavior
- Review instructions
- Check guardrails
- Test with various inputs

Best Practices

Development Flow
- Develop locally
- Test in staging
- Deploy to production
Monitoring
- Keep deployment logs
- Monitor tool performance
- Track user interactions
Updates
- Plan changes carefully
- Test updates thoroughly
- Document modifications

Agent Examples

Here are some examples of agents you can use.

Book Agent: Searches for book information, including title, author, description, and other details.
CEP Agent: Provides an address based on its Brazilian postal code.
Movie Agent: Searches for movie information, with automatic translation of titles and descriptions.
News Agent: Retrieves up-to-date news about various topics through a news API.

Book Agent

This example shows how to create an agent that provides detailed information about books based on the title provided by the user.

Agent Definition

Create a file called agent_definition.yaml:


_32agents:
_32    book_agent:
_32      name: "Book Agent"
_32      description: "Expert in searching for book information"
_32      instructions:
_32        - "You are an expert in searching for detailed information about books"
_32        - "When the user asks about a book, you should search and present the most relevant information"
_32        - "The API returns information in English, and you should translate the description to Portuguese naturally and fluently"
_32        - "If you can't find the book, suggest similar titles"
_32        - "When translating the description, maintain the tone and style of the original text, adapting only to Brazilian Portuguese"
_32        - "Provide information about authors, publisher, publication date, page count, and ratings when available"
_32        - "You must translate the book description to Portuguese before presenting it to the user"
_32      guardrails:
_32        - "Maintain a professional and informative tone when presenting books"
_32        - "Don't make assumptions about book content"
_32        - "Provide accurate and verified information"
_32        - "When translating, maintain fidelity to the original text meaning"
_32        - "Mention when rating or page count information is not available"
_32      tools:
_32      - get_books:
_32          name: "Search Books"
_32          source:
_32            path: "tools/get_books"
_32            entrypoint: "books.GetBooks"
_32            path_test: "test_definition.yaml"
_32          description: "Function to search for book information"
_32          parameters:
_32            - book_title:
_32                description: "book title to search for"
_32                type: "string"
_32                required: true
_32                contact_field: true

Tool Implementation

Create a file tools/get_books/books.py:


_54from weni import Tool
_54from weni.context import Context
_54from weni.responses import TextResponse
_54import requests
_54from datetime import datetime
_54
_54
_54class GetBooks(Tool):
_54    def execute(self, context: Context) -> TextResponse:
_54        apiKey = context.credentials.get("apiKey")
_54        
_54        book_title = context.parameters.get("book_title", "")
_54        books_response = self.get_books_by_title(title=book_title)
_54
_54        # Format the response
_54        items = books_response.get("items", [])
_54        if not items:
_54            return TextResponse(data="Sorry, I couldn't find information about this book.")
_54        
_54        response_data = {
_54            "status": "success",
_54            "totalResults": len(items[:5]),
_54            "books": []
_54        }
_54        
_54        for book in items[:5]:
_54            volume_info = book.get("volumeInfo", {})
_54            book_data = {
_54                "id": book.get("id"),
_54                "title": volume_info.get("title"),
_54                "authors": volume_info.get("authors", []),
_54                "publisher": volume_info.get("publisher"),
_54                "publishedDate": volume_info.get("publishedDate"),
_54                "description": volume_info.get("description", ""),
_54                "pageCount": volume_info.get("pageCount"),
_54                "categories": volume_info.get("categories", []),
_54                "averageRating": volume_info.get("averageRating"),
_54                "ratingsCount": volume_info.get("ratingsCount"),
_54                "imageLinks": volume_info.get("imageLinks", {}),
_54                "language": volume_info.get("language"),
_54                "previewLink": volume_info.get("previewLink"),
_54                "infoLink": volume_info.get("infoLink")
_54            }
_54            response_data["books"].append(book_data)
_54            
_54        return TextResponse(data=response_data)
_54
_54    def get_books_by_title(self, title):
_54        url = "https://www.googleapis.com/books/v1/volumes"
_54        params = {
_54            "q": title
_54        }
_54        response = requests.get(url, params=params)
_54        return response.json()

Create a file tools/get_books/requirements.txt:


_10requests==2.32.3

Create a file tools/get_books/test_definition.yaml:


_10tests:
_10    test_1:
_10        parameters:
_10            book_title: "The Hobbit"

Testing the Tool Locally

Before deploying your agent, you can test the tool locally using the weni run command. This allows you to verify that your tool works correctly and debug any issues.

To test the Book Agent tool:


_10weni run agent_definition.yaml book_agent get_books

This command will execute the tests defined in the test_definition.yaml file and show you the output. You should see the book information for "The Hobbit" test case.

If you need more detailed logs for debugging, you can add the -v flag:


_10weni run agent_definition.yaml book_agent get_books -v

The verbose output will show you more details about the execution process, helping you identify and fix any issues with your tool.

Deployment Steps

Deploy the agent:


_10   weni project push agent_definition.yaml

Testing

After deployment, you can test the agent:

Open your project in the Weni by VTEX platform
Find the Book Agent in your agents list
Start a conversation
Send a book title (e.g., "Pride and Prejudice" or "Harry Potter")

The agent will respond with detailed information about the book, including title, authors, publisher, publication date, page count, and ratings when available. The book description will be automatically translated to Portuguese.

CEP Agent

This example shows how to create an agent that can provide address information based on Brazilian postal codes (CEP).

Agent Definition

Create a file named agents.yaml:


_23agents:
_23  sample_agent:
_23    name: "CEP Agent"
_23    description: "Weni's CEP agent"
_23    instructions:
_23      - "You are an expert in providing addresses to the user based on a postal code provided by the user"
_23      - "The user will send a ZIP code (postal code) and you must provide the address corresponding to this code."
_23    guardrails:
_23      - "Don't talk about politics, religion or any other sensitive topic. Keep it neutral."
_23    tools:
_23      - get_address:
_23          name: "Get Address"
_23          source: 
_23            path: "tools/get_address"
_23            entrypoint: "main.GetAddress"
_23            path_test: "test_definition.yaml"
_23          description: "Function to get the address from the postal code"
_23          parameters:
_23            - cep:
_23                description: "postal code of a place"
_23                type: "string"
_23                required: true
_23                contact_field: true

Tool Implementation

Create a file tools/get_address/main.py:


_16from weni import Tool
_16from weni.context import Context
_16from weni.responses import TextResponse
_16import requests
_16
_16
_16class GetAddress(Tool):
_16    def execute(self, context: Context) -> TextResponse:
_16        cep = context.parameters.get("cep", "")
_16        address_response = self.get_address_by_cep(cep=cep)
_16        return TextResponse(data=address_response)
_16
_16    def get_address_by_cep(self, cep):
_16        url = f"https://viacep.com.br/ws/{cep}/json/"
_16        response = requests.get(url)
_16        return response.json()

Create a file tools/get_address/requirements.txt:


_10requests==2.31.0

Create a file tools/get_address/test_definition.yaml:


_10tests:
_10    test_1:
_10        parameters:
_10            cep: "01311-000"
_10    test_2:
_10        parameters:
_10            cep: "70150-900"
_10    test_3:
_10        parameters:
_10            cep: "20050-090"

Testing the Tool Locally

Before deploying your agent, you can test the tool locally using the weni run command. This allows you to verify that your tool works correctly and debug any issues.

To test the CEP Agent tool:


_10weni run agent_definition.yaml cep_agent get_address

This command will execute the tests defined in the test_definition.yaml file and show you the output. You should see the address information for the Brazilian postal codes specified in the test cases.

If you need more detailed logs for debugging, you can add the -v flag:


_10weni run agent_definition.yaml cep_agent get_address -v

This will run the test cases defined in test_definition.yaml and show you the output, helping you identify and fix any issues with your tool.

Deployment Steps

Deploy the agent:


_10   weni project push agents.yaml

Testing

After deployment, you can test the agent by:

Opening your project in the Weni by VTEX platform
Finding the CEP Agent in your agents list
Starting a conversation
Sending a valid Brazilian postal code (e.g., "01311-000")

Movie Agent

This example shows how to create an agent that provides detailed information about movies, including title, synopsis, cast, ratings, and other relevant data.

Agent Definition

Create a file called agent_definition.yaml:


_38agents:
_38  movie_agent:
_38    credentials:
_38      movies_api_key:
_38        label: "api movies"
_38        placeholder: "movies_api_key"
_38    name: "Movie Agent"
_38    description: "Expert in searching for movie information"
_38    instructions:
_38        - "You are an expert in searching for detailed information about movies"
_38        - "When the user asks about a movie, you should search and present the most relevant information"
_38        - "If the user provides the movie title in Portuguese, you should translate it to English before searching"
_38        - "The API returns information in English, and you should translate the overview to Portuguese naturally and fluently"
_38        - "Keep original titles in English, but you can provide an informal translation in parentheses when relevant"
_38        - "If you can't find the movie, suggest similar titles"
_38        - "Remember that the search must be done in English, even if the user asks in Portuguese"
_38        - "When translating the overview, maintain the tone and style of the original text, adapting only to Brazilian Portuguese"
_38        - "When translating the movie title to English, use the most common and internationally recognizable name"
_38    guardrails:
_38        - "Maintain a professional and informative tone when presenting movies"
_38        - "Don't make assumptions about movie content"
_38        - "Provide accurate and verified information"
_38        - "When translating, maintain fidelity to the original text meaning"
_38        - "If there's doubt in title translation, use the most internationally known name"
_38    tools:
_38    - get_movies:
_38        name: "Get Movies"
_38        source: 
_38          path: "tools/get_movies"
_38          entrypoint: "main.GetMovies"
_38          path_test: "test_definition.yaml"
_38        description: "Function to get movie information from TMDB API"
_38        parameters:
_38            - movie_title:
_38                description: "movie title to search for (will be translated to English if in Portuguese)"
_38                type: "string"
_38                required: true
_38                contact_field: true

Tool Implementation

Create a file tools/get_movies/main.py:


_62from weni import Tool
_62from weni.context import Context
_62from weni.responses import TextResponse
_62import requests
_62from datetime import datetime
_62
_62class GetMovies(Tool):
_62    def execute(self, context: Context) -> TextResponse:
_62        movie_title = context.parameters.get("movie_title", "")
_62        api_key = context.credentials.get("movies_api_key")
_62        
_62        # Search for movies by title
_62        movies_response = self.search_movies_by_title(title=movie_title, api_key=api_key)
_62        
_62        # Format the response
_62        results = movies_response.get("results", [])
_62        if not results:
_62            return TextResponse(data="Sorry, I couldn't find information about this movie.")
_62        
_62        # Get the first (most relevant) movie
_62        movie_id = results[0].get("id")
_62        
_62        # Get detailed information about the movie
_62        movie_details = self.get_movie_details(movie_id=movie_id, api_key=api_key)
_62        
_62        response_data = {
_62            "id": movie_details.get("id"),
_62            "title": movie_details.get("title"),
_62            "original_title": movie_details.get("original_title"),
_62            "tagline": movie_details.get("tagline"),
_62            "overview": movie_details.get("overview"),
_62            "release_date": movie_details.get("release_date"),
_62            "runtime": movie_details.get("runtime"),
_62            "vote_average": movie_details.get("vote_average"),
_62            "vote_count": movie_details.get("vote_count"),
_62            "genres": movie_details.get("genres", []),
_62            "poster_path": f"https://image.tmdb.org/t/p/w500{movie_details.get('poster_path')}" if movie_details.get("poster_path") else None,
_62            "backdrop_path": f"https://image.tmdb.org/t/p/original{movie_details.get('backdrop_path')}" if movie_details.get("backdrop_path") else None
_62        }
_62        
_62        return TextResponse(data=response_data)
_62
_62    def search_movies_by_title(self, title, api_key):
_62        url = "https://api.themoviedb.org/3/search/movie"
_62        params = {
_62            "api_key": api_key,
_62            "query": title,
_62            "language": "en-US",
_62            "page": 1
_62        }
_62        response = requests.get(url, params=params)
_62        return response.json()
_62        
_62    def get_movie_details(self, movie_id, api_key):
_62        url = f"https://api.themoviedb.org/3/movie/{movie_id}"
_62        params = {
_62            "api_key": api_key,
_62            "language": "en-US",
_62            "append_to_response": "credits,similar"
_62        }
_62        response = requests.get(url, params=params)
_62        return response.json()

Create a file tools/get_movies/requirements.txt:


_10requests==2.32.3

Create a file tools/get_movies/test_definition.yaml:


_10tests:
_10    test_1:
_10        credentials:
_10            movies_api_key: "your_api_key_here"
_10        parameters:
_10            movie_title: "The Matrix"

Getting Credentials

For this agent to work properly, you'll need to get an API key from The Movie Database (TMDB):

Visit the TMDB website
Register for a free account
Access the API section in your account and request an API key
Copy your API key
When deploying the agent, you'll need to provide this key as a credential

Testing the Tool Locally

Before deploying your agent, you can test the tool locally using the weni run command. This allows you to verify that your tool works correctly and debug any issues.

Since this tool requires credentials, create a .env file in the tool folder with your TMDB API key (e.g., tools/get_movies/.env):


_10movies_api_key=your_actual_tmdb_api_key_here

To test the Movie Agent tool:


_10weni run agent_definition.yaml movie_agent get_movies

This command will execute the tests defined in the test_definition.yaml file and show you the output. The CLI will automatically pick up the credentials from the tool folder .env file and make them available to your tool during execution.

If you need more detailed logs for debugging, you can add the -v flag:


_10weni run agent_definition.yaml movie_agent get_movies -v

The verbose output will show you more details about the execution process, including API requests and responses, helping you identify and fix any issues with your tool.

Deployment Steps

Deploy the agent:


_10   weni project push agent_definition.yaml

Testing

After deployment, you can test the agent:

Open your project in the Weni by VTEX platform
Find the Movie Agent in your agents list
Provide the TMDB API key in the credential settings
Start a conversation
Send a movie title in Portuguese or English (e.g., "The Godfather" or "Pulp Fiction")

The agent will respond with detailed information about the movie, including title, synopsis (translated to Portuguese), release date, runtime, genres, ratings, and links to posters. If the title is provided in Portuguese, the agent will automatically translate it to perform the search.

News Agent

This example shows how to create an agent that provides up-to-date news on various topics through a news API.

Agent Definition

Create a file called agent_definition.yaml:


_32agents:
_32    news_agent:
_32        credentials:
_32            apiKey:
_32                label: "API Key"
_32                placeholder: "apiKey"
_32        name: "News Agent"
_32        description: "Expert in searching and providing news about any topic"
_32        instructions:
_32            - "You are an expert in searching and providing updated news about any topic"
_32            - "When the user asks about a topic, you should search and present the most relevant news"
_32            - "Always be helpful and provide brief context about the news found"
_32            - "If you can't find news about the topic, suggest related topics"
_32            - "Always use english to answer the user and be polite"
_32        guardrails:
_32            - "Maintain a professional and impartial tone when presenting news"
_32            - "Don't make assumptions or speculations about the news"
_32            - "Avoid sharing sensationalist or unverified news"
_32        tools:
_32        - get_news:
_32            name: "Get News"
_32            source:
_32                path: "tools/get_news"
_32                entrypoint: "main.GetNews"
_32                path_test: "test_definition.yaml"
_32            description: "Function to get the latest news from NewsAPI"
_32            parameters:
_32                - topic:
_32                    description: "Topic to search for news"
_32                    type: "string"
_32                    required: true
_32                    contact_field: true

Tool Implementation

Create a file tools/get_news/main.py:


_51from weni import Tool
_51from weni.context import Context
_51from weni.responses import TextResponse
_51import requests
_51from datetime import datetime
_51
_51
_51class GetNews(Tool):
_51    def execute(self, context: Context) -> TextResponse:
_51        apiKey = context.credentials.get("apiKey")
_51        
_51        topic = context.parameters.get("topic", "")
_51        news_response = self.get_news_by_topic(topic=topic, apiKey=apiKey)
_51        
_51        # Format the response
_51        articles = news_response.get("articles", [])
_51        if not articles:
_51            return TextResponse(data="Sorry, I couldn't find any news on this topic.")
_51        
_51        response_data = {
_51            "status": news_response.get("status"),
_51            "totalResults": len(articles[:10]),
_51            "articles": []
_51        }
_51        
_51        # Get only the first 10 articles
_51        for article in articles[:10]:
_51            article_data = {
_51                "source": article.get("source", {}),
_51                "author": article.get("author"),
_51                "title": article.get("title"),
_51                "description": article.get("description"),
_51                "url": article.get("url"),
_51                "urlToImage": article.get("urlToImage"),
_51                "publishedAt": article.get("publishedAt"),
_51                "content": article.get("content")
_51            }
_51            response_data["articles"].append(article_data)
_51            
_51        return TextResponse(data=response_data)
_51
_51    def get_news_by_topic(self, topic, apiKey):
_51        url = f"https://newsapi.org/v2/everything"
_51        params = {
_51            "q": topic,
_51            "sortBy": "popularity",
_51            "apiKey": apiKey,
_51            "language": "en"
_51        }
_51        response = requests.get(url, params=params)
_51        return response.json()

Create a file tools/get_news/requirements.txt:


_10requests==2.32.3

Create a file tools/get_news/test_definition.yaml:


_10tests:
_10    test_1:
_10        credentials:
_10            apiKey: "your_api_key_here"
_10        parameters:
_10            topic: "technology"

Getting Credentials

For this agent to work properly, you'll need to get an API key from News API:

Visit the News API website
Register for a free account
Copy your API key from your account
When deploying the agent, you'll need to provide this key as a credential

Testing the Tool Locally

Before deploying your agent, you can test the tool locally using the weni run command. This allows you to verify that your tool works correctly and debug any issues.

Since this tool requires credentials, create a .env file in the tool folder with your API key (e.g., tools/get_news/.env):


_10apiKey=your_actual_news_api_key_here

To test the News Agent tool:


_10weni run agent_definition.yaml news_agent get_news

If you need more detailed logs for debugging, you can add the -v flag:


_10weni run agent_definition.yaml news_agent get_news -v

The verbose output will show you more details about the execution process, helping you identify and fix any issues with your tool.

Deployment Steps

Deploy the agent:


_10   weni project push agent_definition.yaml

Testing

After deployment, you can test the agent:

Open your project in the Weni by VTEX platform
Find the News Agent in your agents list
Provide the News API key in the credential settings
Start a conversation
Send a topic to search for news (e.g., "technology", "sports", "business")

The agent will respond with the most relevant news about the requested topic, including title, description, source, author, publication date, and links to the full article.