[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides working with weni by vtex agents in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/data-protection-plus)

---

Weni by VTEX

Weni by VTEX CLI

[Using the Weni by VTEX CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/using-the-weni-by-vtex-cli)

[Weni by VTEX CLI Command Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/weni-by-vtex-cli-command-reference)

[Authenticating with your Weni by VTEX account](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/authenticating-with-your-weni-by-vtex-account)

[Managing your Weni by VTEX projects](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/managing-your-weni-by-vtex-projects)

[Understanding the core concepts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/weni-by-vtex-understanding-the-core-concepts)

[Working with Weni by VTEX agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents)

[Fetching and filtering logs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/weni-by-vtex-fetching-and-filtering-logs)

[Using Weni Run to execute tool tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/using-weni-run-to-execute-tool-tests)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/data-protection-plus)

---

Weni by VTEX

Weni by VTEX CLI

[Using the Weni by VTEX CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/using-the-weni-by-vtex-cli)

[Weni by VTEX CLI Command Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/weni-by-vtex-cli-command-reference)

[Authenticating with your Weni by VTEX account](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/authenticating-with-your-weni-by-vtex-account)

[Managing your Weni by VTEX projects](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/managing-your-weni-by-vtex-projects)

[Understanding the core concepts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/weni-by-vtex-understanding-the-core-concepts)

[Working with Weni by VTEX agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents)

[Fetching and filtering logs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/weni-by-vtex-fetching-and-filtering-logs)

[Using Weni Run to execute tool tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/using-weni-run-to-execute-tool-tests)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides)

Weni by VTEX

Weni by VTEX CLI

[Working with Weni by VTEX agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents)

Working with Weni by VTEX agents

Learn how to create, configure, and deploy agents using the Weni by VTEX CLI, with some examples of 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:

`1

agents:

2

 agent_id:

3

 name: "Agent Name"

4

 description: "Agent Description"

5

 instructions:

6

 - "Instruction 1"

7

 - "Instruction 2"

8

 guardrails:

9

 - "Guardrail 1"

10

 tools:

11

 - tool_name:

12

 name: "Tool Name"

13

 source:

14

 path: "tools/tool_name"

15

 entrypoint: "main.ToolClass"

16

 description: "Tool Description"

17

 parameters:

18

 - param_name:

19

 description: "Parameter Description"

20

 type: "string"

21

 required: true

22

 contact_field: true

`

### Key Components

1. **Agent ID**
   * Unique identifier for your agent
   * Used internally by the system
2. **Basic Information**
   * `name`: Display name (max 55 characters)
   * `description`: Brief description of the agent's purpose
3. **Instructions**
   * Guide the agent's behavior
   * Minimum 40 characters each
   * Should be clear and specific
4. **Guardrails**
   * Define boundaries and limitations
   * Prevent unwanted behavior
5. **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:

`1

source:

2

 path: "tools/tool_name"

3

 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:

`1

project/

2

├── agents.yaml

3

└── tools/

4

 └── get_address/

5

 ├── main.py # Contains GetAddress class

6

 └── requirements.txt # Dependencies

`

## Creating Tools

### Tool Implementation Structure

`1

from weni import Tool

2

from weni.context import Context

3

from weni.responses import TextResponse

4

5

class ToolName(Tool):

6

 def execute(self, context: Context) -> TextResponse:

7

 # Extract parameters

8

 parameters = context.parameters

9

 param_value = parameters.get("param_name", "")

10

11

 # Process the request

12

 result = self.process_request(param_value)

13

14

 # Return response

15

 return TextResponse(data=result)

16

17

 def process_request(self, param_value):

18

 # 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:

`1

weni project push agents.yaml

`

The command:

1. Validates your YAML
2. Uploads tools
3. Creates/updates the agent

### Deployment Best Practices

1. **Version Control**
   * Keep agent definitions in version control
   * Document changes
2. **Testing**
   * Test locally when possible
   * Start with staging environment
   * Verify all tools work
3. **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

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

### Best Practices

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

# Agent Examples

Here are some examples of agents you can use.

* [Book Agent](#book-agent): Searches for book information, including title, author, description, and other details.
* [CEP Agent](#cep-agent): Provides an address based on its Brazilian postal code.
* [Movie Agent](#movie-agent): Searches for movie information, with automatic translation of titles and descriptions.
* [News Agent](#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`:

`1

agents:

2

 book_agent:

3

 name: "Book Agent"

4

 description: "Expert in searching for book information"

5

 instructions:

6

 - "You are an expert in searching for detailed information about books"

7

 - "When the user asks about a book, you should search and present the most relevant information"

8

 - "The API returns information in English, and you should translate the description to Portuguese naturally and fluently"

9

 - "If you can't find the book, suggest similar titles"

10

 - "When translating the description, maintain the tone and style of the original text, adapting only to Brazilian Portuguese"

11

 - "Provide information about authors, publisher, publication date, page count, and ratings when available"

12

 - "You must translate the book description to Portuguese before presenting it to the user"

13

 guardrails:

14

 - "Maintain a professional and informative tone when presenting books"

15

 - "Don't make assumptions about book content"

16

 - "Provide accurate and verified information"

17

 - "When translating, maintain fidelity to the original text meaning"

18

 - "Mention when rating or page count information is not available"

19

 tools:

20

 - get_books:

21

 name: "Search Books"

22

 source:

23

 path: "tools/get_books"

24

 entrypoint: "books.GetBooks"

25

 path_test: "test_definition.yaml"

26

 description: "Function to search for book information"

27

 parameters:

28

 - book_title:

29

 description: "book title to search for"

30

 type: "string"

31

 required: true

32

 contact_field: true

`

### Tool Implementation

Create a file `tools/get_books/books.py`:

`1

from weni import Tool

2

from weni.context import Context

3

from weni.responses import TextResponse

4

import requests

5

from datetime import datetime

6

7

8

class GetBooks(Tool):

9

 def execute(self, context: Context) -> TextResponse:

10

 apiKey = context.credentials.get("apiKey")

11

12

 book_title = context.parameters.get("book_title", "")

13

 books_response = self.get_books_by_title(title=book_title)

14

15

 # Format the response

16

 items = books_response.get("items", [])

17

 if not items:

18

 return TextResponse(data="Sorry, I couldn't find information about this book.")

19

20

 response_data = {

21

 "status": "success",

22

 "totalResults": len(items[:5]),

23

 "books": []

24

 }

25

26

 for book in items[:5]:

27

 volume_info = book.get("volumeInfo", {})

28

 book_data = {

29

 "id": book.get("id"),

30

 "title": volume_info.get("title"),

31

 "authors": volume_info.get("authors", []),

32

 "publisher": volume_info.get("publisher"),

33

 "publishedDate": volume_info.get("publishedDate"),

34

 "description": volume_info.get("description", ""),

35

 "pageCount": volume_info.get("pageCount"),

36

 "categories": volume_info.get("categories", []),

37

 "averageRating": volume_info.get("averageRating"),

38

 "ratingsCount": volume_info.get("ratingsCount"),

39

 "imageLinks": volume_info.get("imageLinks", {}),

40

 "language": volume_info.get("language"),

41

 "previewLink": volume_info.get("previewLink"),

42

 "infoLink": volume_info.get("infoLink")

43

 }

44

 response_data["books"].append(book_data)

45

46

 return TextResponse(data=response_data)

47

48

 def get_books_by_title(self, title):

49

 url = "https://www.googleapis.com/books/v1/volumes"

50

 params = {

51

 "q": title

52

 }

53

 response = requests.get(url, params=params)

54

 return response.json()

`

Create a file `tools/get_books/requirements.txt`:

`1

requests==2.32.3

`

Create a file `tools/get_books/test_definition.yaml`:

`1

tests:

2

 test_1:

3

 parameters:

4

 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:

`1

weni 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:

`1

weni 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

1. Deploy the agent:

`1

 weni project push agent_definition.yaml

`

### Testing

After deployment, you can test the agent:

1. Open your project in the Weni by VTEX platform
2. Find the Book Agent in your agents list
3. Start a conversation
4. 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`:

`1

agents:

2

 sample_agent:

3

 name: "CEP Agent"

4

 description: "Weni's CEP agent"

5

 instructions:

6

 - "You are an expert in providing addresses to the user based on a postal code provided by the user"

7

 - "The user will send a ZIP code (postal code) and you must provide the address corresponding to this code."

8

 guardrails:

9

 - "Don't talk about politics, religion or any other sensitive topic. Keep it neutral."

10

 tools:

11

 - get_address:

12

 name: "Get Address"

13

 source:

14

 path: "tools/get_address"

15

 entrypoint: "main.GetAddress"

16

 path_test: "test_definition.yaml"

17

 description: "Function to get the address from the postal code"

18

 parameters:

19

 - cep:

20

 description: "postal code of a place"

21

 type: "string"

22

 required: true

23

 contact_field: true

`

### Tool Implementation

Create a file `tools/get_address/main.py`:

`1

from weni import Tool

2

from weni.context import Context

3

from weni.responses import TextResponse

4

import requests

5

6

7

class GetAddress(Tool):

8

 def execute(self, context: Context) -> TextResponse:

9

 cep = context.parameters.get("cep", "")

10

 address_response = self.get_address_by_cep(cep=cep)

11

 return TextResponse(data=address_response)

12

13

 def get_address_by_cep(self, cep):

14

 url = f"https://viacep.com.br/ws/{cep}/json/"

15

 response = requests.get(url)

16

 return response.json()

`

Create a file `tools/get_address/requirements.txt`:

`1

requests==2.31.0

`

Create a file `tools/get_address/test_definition.yaml`:

`1

tests:

2

 test_1:

3

 parameters:

4

 cep: "01311-000"

5

 test_2:

6

 parameters:

7

 cep: "70150-900"

8

 test_3:

9

 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:

`1

weni 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:

`1

weni 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

1. Deploy the agent:

`1

 weni project push agents.yaml

`

### Testing

After deployment, you can test the agent by:

1. Opening your project in the Weni by VTEX platform
2. Finding the CEP Agent in your agents list
3. Starting a conversation
4. 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`:

`1

agents:

2

 movie_agent:

3

 credentials:

4

 movies_api_key:

5

 label: "api movies"

6

 placeholder: "movies_api_key"

7

 name: "Movie Agent"

8

 description: "Expert in searching for movie information"

9

 instructions:

10

 - "You are an expert in searching for detailed information about movies"

11

 - "When the user asks about a movie, you should search and present the most relevant information"

12

 - "If the user provides the movie title in Portuguese, you should translate it to English before searching"

13

 - "The API returns information in English, and you should translate the overview to Portuguese naturally and fluently"

14

 - "Keep original titles in English, but you can provide an informal translation in parentheses when relevant"

15

 - "If you can't find the movie, suggest similar titles"

16

 - "Remember that the search must be done in English, even if the user asks in Portuguese"

17

 - "When translating the overview, maintain the tone and style of the original text, adapting only to Brazilian Portuguese"

18

 - "When translating the movie title to English, use the most common and internationally recognizable name"

19

 guardrails:

20

 - "Maintain a professional and informative tone when presenting movies"

21

 - "Don't make assumptions about movie content"

22

 - "Provide accurate and verified information"

23

 - "When translating, maintain fidelity to the original text meaning"

24

 - "If there's doubt in title translation, use the most internationally known name"

25

 tools:

26

 - get_movies:

27

 name: "Get Movies"

28

 source:

29

 path: "tools/get_movies"

30

 entrypoint: "main.GetMovies"

31

 path_test: "test_definition.yaml"

32

 description: "Function to get movie information from TMDB API"

33

 parameters:

34

 - movie_title:

35

 description: "movie title to search for (will be translated to English if in Portuguese)"

36

 type: "string"

37

 required: true

38

 contact_field: true

`

### Tool Implementation

Create a file `tools/get_movies/main.py`:

`1

from weni import Tool

2

from weni.context import Context

3

from weni.responses import TextResponse

4

import requests

5

from datetime import datetime

6

7

class GetMovies(Tool):

8

 def execute(self, context: Context) -> TextResponse:

9

 movie_title = context.parameters.get("movie_title", "")

10

 api_key = context.credentials.get("movies_api_key")

11

12

 # Search for movies by title

13

 movies_response = self.search_movies_by_title(title=movie_title, api_key=api_key)

14

15

 # Format the response

16

 results = movies_response.get("results", [])

17

 if not results:

18

 return TextResponse(data="Sorry, I couldn't find information about this movie.")

19

20

 # Get the first (most relevant) movie

21

 movie_id = results[0].get("id")

22

23

 # Get detailed information about the movie

24

 movie_details = self.get_movie_details(movie_id=movie_id, api_key=api_key)

25

26

 response_data = {

27

 "id": movie_details.get("id"),

28

 "title": movie_details.get("title"),

29

 "original_title": movie_details.get("original_title"),

30

 "tagline": movie_details.get("tagline"),

31

 "overview": movie_details.get("overview"),

32

 "release_date": movie_details.get("release_date"),

33

 "runtime": movie_details.get("runtime"),

34

 "vote_average": movie_details.get("vote_average"),

35

 "vote_count": movie_details.get("vote_count"),

36

 "genres": movie_details.get("genres", []),

37

 "poster_path": f"https://image.tmdb.org/t/p/w500{movie_details.get('poster_path')}" if movie_details.get("poster_path") else None,

38

 "backdrop_path": f"https://image.tmdb.org/t/p/original{movie_details.get('backdrop_path')}" if movie_details.get("backdrop_path") else None

39

 }

40

41

 return TextResponse(data=response_data)

42

43

 def search_movies_by_title(self, title, api_key):

44

 url = "https://api.themoviedb.org/3/search/movie"

45

 params = {

46

 "api_key": api_key,

47

 "query": title,

48

 "language": "en-US",

49

 "page": 1

50

 }

51

 response = requests.get(url, params=params)

52

 return response.json()

53

54

 def get_movie_details(self, movie_id, api_key):

55

 url = f"https://api.themoviedb.org/3/movie/{movie_id}"

56

 params = {

57

 "api_key": api_key,

58

 "language": "en-US",

59

 "append_to_response": "credits,similar"

60

 }

61

 response = requests.get(url, params=params)

62

 return response.json()

`

Create a file `tools/get_movies/requirements.txt`:

`1

requests==2.32.3

`

Create a file `tools/get_movies/test_definition.yaml`:

`1

tests:

2

 test_1:

3

 credentials:

4

 movies_api_key: "your_api_key_here"

5

 parameters:

6

 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):

1. Visit the [TMDB](https://read.calvincode.net/reader?url=https://www.themoviedb.org/) website
2. Register for a free account
3. Access the API section in your account and request an API key
4. Copy your API key
5. 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`):

`1

movies_api_key=your_actual_tmdb_api_key_here

`

To test the Movie Agent tool:

`1

weni 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:

`1

weni 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

1. Deploy the agent:

`1

 weni project push agent_definition.yaml

`

### Testing

After deployment, you can test the agent:

1. Open your project in the Weni by VTEX platform
2. Find the Movie Agent in your agents list
3. Provide the TMDB API key in the credential settings
4. Start a conversation
5. 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`:

`1

agents:

2

 news_agent:

3

 credentials:

4

 apiKey:

5

 label: "API Key"

6

 placeholder: "apiKey"

7

 name: "News Agent"

8

 description: "Expert in searching and providing news about any topic"

9

 instructions:

10

 - "You are an expert in searching and providing updated news about any topic"

11

 - "When the user asks about a topic, you should search and present the most relevant news"

12

 - "Always be helpful and provide brief context about the news found"

13

 - "If you can't find news about the topic, suggest related topics"

14

 - "Always use english to answer the user and be polite"

15

 guardrails:

16

 - "Maintain a professional and impartial tone when presenting news"

17

 - "Don't make assumptions or speculations about the news"

18

 - "Avoid sharing sensationalist or unverified news"

19

 tools:

20

 - get_news:

21

 name: "Get News"

22

 source:

23

 path: "tools/get_news"

24

 entrypoint: "main.GetNews"

25

 path_test: "test_definition.yaml"

26

 description: "Function to get the latest news from NewsAPI"

27

 parameters:

28

 - topic:

29

 description: "Topic to search for news"

30

 type: "string"

31

 required: true

32

 contact_field: true

`

### Tool Implementation

Create a file `tools/get_news/main.py`:

`1

from weni import Tool

2

from weni.context import Context

3

from weni.responses import TextResponse

4

import requests

5

from datetime import datetime

6

7

8

class GetNews(Tool):

9

 def execute(self, context: Context) -> TextResponse:

10

 apiKey = context.credentials.get("apiKey")

11

12

 topic = context.parameters.get("topic", "")

13

 news_response = self.get_news_by_topic(topic=topic, apiKey=apiKey)

14

15

 # Format the response

16

 articles = news_response.get("articles", [])

17

 if not articles:

18

 return TextResponse(data="Sorry, I couldn't find any news on this topic.")

19

20

 response_data = {

21

 "status": news_response.get("status"),

22

 "totalResults": len(articles[:10]),

23

 "articles": []

24

 }

25

26

 # Get only the first 10 articles

27

 for article in articles[:10]:

28

 article_data = {

29

 "source": article.get("source", {}),

30

 "author": article.get("author"),

31

 "title": article.get("title"),

32

 "description": article.get("description"),

33

 "url": article.get("url"),

34

 "urlToImage": article.get("urlToImage"),

35

 "publishedAt": article.get("publishedAt"),

36

 "content": article.get("content")

37

 }

38

 response_data["articles"].append(article_data)

39

40

 return TextResponse(data=response_data)

41

42

 def get_news_by_topic(self, topic, apiKey):

43

 url = f"https://newsapi.org/v2/everything"

44

 params = {

45

 "q": topic,

46

 "sortBy": "popularity",

47

 "apiKey": apiKey,

48

 "language": "en"

49

 }

50

 response = requests.get(url, params=params)

51

 return response.json()

`

Create a file `tools/get_news/requirements.txt`:

`1

requests==2.32.3

`

Create a file `tools/get_news/test_definition.yaml`:

`1

tests:

2

 test_1:

3

 credentials:

4

 apiKey: "your_api_key_here"

5

 parameters:

6

 topic: "technology"

`

### Getting Credentials

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

1. Visit the [News API](https://read.calvincode.net/reader?url=https://newsapi.org/) website
2. Register for a free account
3. Copy your API key from your account
4. 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`):

`1

apiKey=your_actual_news_api_key_here

`

To test the News Agent tool:

`1

weni run agent_definition.yaml news_agent get_news

`

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:

`1

weni 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

1. Deploy the agent:

`1

 weni project push agent_definition.yaml

`

### Testing

After deployment, you can test the agent:

1. Open your project in the Weni by VTEX platform
2. Find the News Agent in your agents list
3. Provide the News API key in the credential settings
4. Start a conversation
5. 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.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F170467615%3Fv%3D4%26w=64%26q=75)](https://github.com/mariananantua)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Weni-by-VTEX/CLI/working-with-weni-by-vtex-agents.md)

[Understanding the core concepts« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents//docs/guides/weni-by-vtex-understanding-the-core-concepts)[Fetching and filtering logsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents//docs/guides/weni-by-vtex-fetching-and-filtering-logs)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F170467615%3Fv%3D4%26w=64%26q=75)](https://github.com/mariananantua)

ON THIS PAGE

[Agent Definition File](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition-file)

[Key Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23key-components)[Tool Source Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-source-configuration)

[Creating Tools](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23creating-tools)

[Tool Implementation Structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation-structure)

[Deploying Agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deploying-agents)

[Push Command](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23push-command)[Deployment Best Practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-best-practices)

[Advanced Topics](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23advanced-topics)

[Parameter Types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23parameter-types)[Response Formats](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23response-formats)[Error Handling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23error-handling)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23troubleshooting)

[Common Issues](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23common-issues)[Best Practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23best-practices)

[Agent Examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-examples)

[Book Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23book-agent)

[Agent Definition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition)[Tool Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation)[Testing the Tool Locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing-the-tool-locally)[Deployment Steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-steps)[Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing)

[CEP Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23cep-agent)

[Agent Definition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition)[Tool Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation)[Testing the Tool Locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing-the-tool-locally)[Deployment Steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-steps)[Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing)

[Movie Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23movie-agent)

[Agent Definition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition)[Tool Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation)[Getting Credentials](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23getting-credentials)[Testing the Tool Locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing-the-tool-locally)[Deployment Steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-steps)[Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing)

[News Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23news-agent)

[Agent Definition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition)[Tool Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation)[Getting Credentials](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23getting-credentials)[Testing the Tool Locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing-the-tool-locally)[Deployment Steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-steps)[Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Weni-by-VTEX/CLI/working-with-weni-by-vtex-agents.md)

Copy page

On this page

ON THIS PAGE

[Agent Definition File](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition-file)

[Key Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23key-components)[Tool Source Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-source-configuration)

[Creating Tools](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23creating-tools)

[Tool Implementation Structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation-structure)

[Deploying Agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deploying-agents)

[Push Command](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23push-command)[Deployment Best Practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-best-practices)

[Advanced Topics](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23advanced-topics)

[Parameter Types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23parameter-types)[Response Formats](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23response-formats)[Error Handling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23error-handling)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23troubleshooting)

[Common Issues](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23common-issues)[Best Practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23best-practices)

[Agent Examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-examples)

[Book Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23book-agent)

[Agent Definition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition)[Tool Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation)[Testing the Tool Locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing-the-tool-locally)[Deployment Steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-steps)[Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing)

[CEP Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23cep-agent)

[Agent Definition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition)[Tool Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation)[Testing the Tool Locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing-the-tool-locally)[Deployment Steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-steps)[Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing)

[Movie Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23movie-agent)

[Agent Definition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition)[Tool Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation)[Getting Credentials](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23getting-credentials)[Testing the Tool Locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing-the-tool-locally)[Deployment Steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-steps)[Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing)

[News Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23news-agent)

[Agent Definition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23agent-definition)[Tool Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23tool-implementation)[Getting Credentials](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23getting-credentials)[Testing the Tool Locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing-the-tool-locally)[Deployment Steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23deployment-steps)[Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/working-with-weni-by-vtex-agents/docs/guides/working-with-weni-by-vtex-agents%23testing)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] How do I use the VTEX search 1.0.8 Banner app? Provide documentation and configuration details.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/guides/vtex-io-deprecated-apps)

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/vtex-io-apps)

Banner

[vtex.search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search)

Version: 1.0.8

Latest version: 2.18.8

> This page is about version **1.0.8** of the app, which is not the most recent version. The latest stable version is **2.18.8**.

A simple banner with that can configured to appear depending on the context of the search.

## Configuration

The banner entity is composed by the following fields:

| Field            | Description                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| Active           | Indicates if banner is active or not.                                                                            |
| Banner name      | Field used as an id.                                                                                |
| Type banner      | Indicates the banner type. It can be HTML or IMAGE.                                                              |
| HTML / Image URL | Html or image to be inserted.                                                                                |
| Area             | Indicates which area the banner should appear. It is importante when there is multiple banners in the same page. |
| Terms            | List of terms for this banner.                                                                                |
| Period           | The period that this banner will be active.                                                                      |
| Attributes       | List of selected attributes for this banner.                                                                     |

## Usage

Add the `search-banner` block to the `search-result-layout.desktop` or `search-result-layout.mobile`. For example:

`1

"search-result-layout.desktop": {

2

 "children": [

3

 "flex-layout.row#banner-one",

4

 ],

5

 "search-banner#one": {

6

 "props": {

7

 "area": "one",

8

 "blockClass": "myBanner",

9

 "horizontalAlignment": "center"

10

 }

11

 },

12

 "flex-layout.row#banner-one": {

13

 "children": ["search-banner#one"]

14

 },

15

}

`

## Props

| Prop name           | Type   | Description                                                             | Default value |
| ------------------- | ------ | ----------------------------------------------------------------------- | ------------- |
| area                | String | Idicates the area. It needs to match the area configured in the banner. | \-            |
| blockClass          | String | Defines a custom class for the banner div.                              | \-            |
| horizontalAlignment | String | Defines the horizontal alignment for the banner.                        | "center"      |

The possible values for `horizontalAlignment` are:

| Values   |
| -------- |
| "left"   |
| "right"  |
| "center" |

## Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://read.calvincode.net/reader?url=https://vtex.io/docs/recipes/style/using-css-handles-for-store-customization).

| CSS Handles  |
| ------------ |
| searchBanner |

See also

[Vtex.searchVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.search)[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.search@1.0.8/Banner%23configuration)

[Usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.search@1.0.8/Banner%23usage)

[Props](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.search@1.0.8/Banner%23props)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search@1.0.8/Banner/docs/apps/vtex.search@1.0.8/Banner%23customization)

Was this helpful?

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides delivery promise for headless stores in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

[How search parameters work](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/how-search-parameters-work)

[Search Control – fulltextSearchBox](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/search-control-fulltextsearchbox)

[Consult store search terms information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/consult-store-search-terms-information)

[Consult product search information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/consult-product-search-information)

[Get banner list for a specific search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/get-banner-list-for-a-specific-search)

[Get a list of the possible facets for a specific search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/get-a-list-of-the-possible-facets-for-a-specific-search)

[Segmenting the search result](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/vtex-io-documentation-segmenting-the-search-result)

[Access Control List](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/access-control-list)

[Delivery promise for headless stores (Beta)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores)

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

[How search parameters work](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/how-search-parameters-work)

[Search Control – fulltextSearchBox](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/search-control-fulltextsearchbox)

[Consult store search terms information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/consult-store-search-terms-information)

[Consult product search information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/consult-product-search-information)

[Get banner list for a specific search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/get-banner-list-for-a-specific-search)

[Get a list of the possible facets for a specific search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/get-a-list-of-the-possible-facets-for-a-specific-search)

[Segmenting the search result](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/vtex-io-documentation-segmenting-the-search-result)

[Access Control List](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/access-control-list)

[Delivery promise for headless stores (Beta)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores)

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides)

Search

[Delivery promise for headless stores (Beta)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores)

Delivery promise for headless stores (Beta)

Learn how to implement the delivery promise feature in headless stores.

> This feature is in closed beta, which means that only selected customers can access it for now. If you are interested in implementing it in the future, please contact our [Support](https://read.calvincode.net/reader?url=https://support.vtex.com/hc/en-us) team.

This guide details how to use the [Delivery Promise](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/delivery-promise-beta--p9EJH9GgxL0JceA6dBswd) feature on headless stores, using [Intelligent Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/intelligent-search-api) with additional facets for this purpose.

Only products that can be delivered to the provided address or picked up at pickup points are displayed, following these rules:

* The system displays all available pickup points within the 50 km radius configured in Checkout. This applies when the customer selects pickup in the header or a specific pickup point. There’s no limit to the number of pickup points displayed. To enable this functionality, you must fetch the complete list of pickup points using the [Checkout API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/checkout-api%23get-/api/checkout/pub/pickup-points). Retrieving this list is a mandatory dependency for the Delivery Promise feature in headless stores.
* For the nearby pickup filter, pickup points within a 10 km radius of the buyer's location are shown, with a maximum of 40 pickup points.

## Before you begin

* Make sure you have Intelligent Search installed, namely admin-search and search-resolver. Learn more at [Installing Intelligent Search](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4mwZGH252R3CCPRim8v0F3).
* Complete Catalog integration with Intelligent Search. Learn more at [Starting the integration with Catalog](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/2wBsO1AKTQZ04idbTKszI4).

## Using Delivery Promise parameters

The `GET` [Get list of products for a query](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/intelligent-search-api%23get-/product%5Fsearch/-facets-) endpoint from Intelligent Search API accepts path parameters referred to as facets:

`1

https://{accountName}.{environment}.com.br/api/io/_v/api/intelligent-search/product_search/{facets}

`

To enable the Delivery Promise functionality, you should use the following additional query strings and facets on this request. When possible, using query strings is recommended for better performance.

| Query string / Facet                     | Description                                                                                | Example                                                               |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| zip-code **\[required\]** (query string) | Postal code.                                                                                | **?zip-code=22250040**                                                |
| shipping (facet)                         | Shipping method. It must always be combined with zip-code. Possible values: pickup-in-point, delivery, pickup-all, pickup-nearby                                                                                | /shipping/pickup-in-point/?zip-code=22250040                          |
| pickupPoint (query string)               | Pickup point ID to filter by a specific pickup point. This is used only with the shipping/pickup-in-point facet, besides the required parameters.                                                                                | /shipping/pickup-in-point?zip-code=22250040&pickupPoint=vtex-botafogo |
| delivery-options (facet)                 | [Delivery Option](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/delivery-options-beta--1fRDJFcHCtpTnk7GNyaRDY) ID or IDs to be filtered. The ID can be obtained in the VTEX Admin, at **Shipping > Delivery Options**. It must always be combined with zip-code. Multiple entries of this filter can be used in the request to search for multiple Delivery Options.                                                                                | **/delivery-options/express-option-id**?zip-code=22250040             |
| dynamic-estimate (facet)                 | The Dynamic Estimate filter selects Delivery Options that can meet the requested delivery or pickup timeframe. It must always be used together with zip-code and shipping. Possible values: same-day, next-day. It dynamically identifies which Delivery Options for the given zip-code and shipping facet can meet the requested timeframe, and then filters the search as if those Delivery Options had been manually passed as filters.                                                                                | /shipping/delivery/dynamic-estimate/same-day?zip-code=22250040        |
| hideUnavailableItems (query string)      | Controls whether the search returns only available products or both available and unavailable ones. When set to true, only products with stock are returned; when set to false, the API includes unavailable products as well. A product is considered unavailable when availableQuantity = 0, while availableQuantity = 10000 indicates that the product is available. Retailers may choose to show unavailable items for commercial reasons (for example, to signal that they carry those products even if temporarily out of stock), while the recommended default is true. This facet also allows merchants to expose a shopper-facing filter such as "show only in-stock products." If hideUnavailableItems is omitted, products with the ShowIfNotAvailable property set to true in the Catalog may appear even if unavailable. Learn more about the ShowIfNotAvailable property in the [Catalog API reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/catalog-api?endpoint=get-/api/catalog%5Fsystem/pvt/sku/stockkeepingunitbyid/-skuId-). | ?hideUnavailableItems=true                                            |

> `zip-code` is **required** to filter product availability according to the shopper’s location and is integral to any request using Delivery Promise functionality. This means you must use it when filtering by shipping method and pickup point.

> To ensure only products that are available for delivery or pickup are returned, you must include the `hideUnavailableItems=true` query parameter in your requests. If this parameter is omitted, the search engine will include products with the `ShowIfNotAvailable` property set to `true` in the Catalog module even if they are not available for delivery or pickup. For example, product `649553` may appear in results if it has `ShowIfNotAvailable` enabled, unless you explicitly set `hideUnavailableItems=true`. Learn more about the `ShowIfNotAvailable` property in the [Catalog API reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/catalog-api?endpoint=get-/api/catalog%5Fsystem/pvt/sku/stockkeepingunitbyid/-skuId-).

For more information on facet options apart from the ones directly related to Delivery Promise, go to `GET` [Get list of products for a query](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/intelligent-search-api%23get-/product%5Fsearch/-facets-).

### Filter combinations

When shoppers apply filters, the API combines them according to the following rules:

* **Facets of the same type → OR (union):** when multiple values of the same facet are applied, the API returns the union of all products matching any of those values.
* **Facets of different types → AND (intersection):** when different facet types are combined, the API returns only the products that satisfy all selected facet conditions simultaneously.

This results in the following behavior when using Delivery Options and Dynamic Estimates:

* **Multiple Delivery Options → OR (union):** the API returns all products that match any of the delivery options selected by the shopper.
* **Dynamic Estimate + Delivery Option → AND (intersection):** the API returns only the products that satisfy both the selected dynamic estimate and the chosen delivery option.

### Filtering by location

Here is an example of a basic Delivery Promise search using only postal code:

`1

https://{{accountName}}.myvtex.com/api/io/_v/api/intelligent-search/product_search?zip-code=22250040

`

### Filtering by shipping method

To filter the search by a shipping method, you must use the `shipping` parameter and some additional optional parameters, depending on the type of filter you want to implement.

The possible filters are:

* [Delivery to the shopper’s ZIP code](#delivery-to-the-shopper's-zip-code)
* [Pickup at a specific location](#pickup-at-a-specific-location)
* [Pickup at a nearby location](#pickup-at-a-nearby-location)

Learn more about each of them in the following sections.

#### Delivery to the shopper’s ZIP code

Filters the search for products that can be delivered to the zip code entered by the buyer.

Parameters: `/shipping/delivery`

Example:

`1

https://{{accountName}}.myvtex.com.br/api/io/_v/api/intelligent-search/product_search/shipping/delivery?zip-code=22250040

`

#### Pickup at a specific location

Filters the search for products that can be picked up at a specific pickup point selected by the buyer.

Parameters: `/shipping/pickup-in-point/pickupPoint/{pickupPointId}`

> We are working on an endpoint that will simplify retrieving pickup points directly. For now, to fetch the list of pickup points for the store and their IDs, follow the [List pickup points by location](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-pickup-points-by-location) guide and [API reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/checkout-api%23get-/api/checkout/pub/pickup-points).

Example:

`1

https://{{accountName}}.myvtex.com/api/io/_v/api/intelligent-search/product_search/shipping/pickup-in-point/pickupPoint/vtex-botafogo?zip-code=22250040

`

#### Pickup at a nearby location

Filters the search for products that can be picked up at pickup points located within a radius of up to 50 km from the shopper, within the same pickup radius limit as the Checkout.

Parameters: `/shipping/pickup-in-point/pickup-nearby`

Example:

`1

https://{{accountName}}.myvtex.com/api/io/_v/api/intelligent-search/product_search/shipping/pickup-in-point/pickup-nearby?zip-code=22250040

`

### Filtering by Delivery Options

Delivery Options are the set of choices a merchant provides to shoppers, describing how and when an order can be delivered, along with relevant metadata such as estimated delivery time.

Before you can display Delivery Option filters, it is necessary to:

* Enable the Delivery Options feature by contacting [our Support](https://read.calvincode.net/reader?url=https://help.vtex.com/en/support).
* Create the Delivery Options for your store in the VTEX Admin following the instructions in the [Delivery Options](https://read.calvincode.net/reader?url=https://help.vtex.com/docs/tutorials/delivery-options-beta) guide.

To filter by a Delivery Option, use the `delivery-options` parameter. Its value must be the ID for one of the Delivery Options configured on your store.

Example:

`1

https://{{accountName}}.myvtex.com/api/io/_v/api/intelligent-search/product_search/delivery-options/express-option-id?zip-code=22250040

`

You can also filter for multiple Delivery Options by including multiple entries for the `delivery-options` parameter on the request.

Example:

`1

https://{{accountName}}.myvtex.com/api/io/_v/api/intelligent-search/product_search/delivery-options/one-week-option-id/delivery-options/one-day-option-id?zip-code=22250040

`

### Filtering by Dynamic Estimates

Dynamic Estimates for the delivery or pickup of a product are computed in real-time when searching. They are based on the store’s logistics operations, time of day and any product properties that might affect them. The possible values are _Same-day Delivery_ and _Next-day Delivery_.

To filter by a Dynamic Estimate, you must use the `dynamic-estimate` parameter.

#### Same-day Delivery

Filters the search for products that can be delivered or picked up at the provided `zip-code` on the **same day**.

Example:

`1

https://{{accountName}}.myvtex.com/api/io/_v/api/intelligent-search/product_search/dynamic-estimate/same-day?zip-code=22250040

`

#### Next-day Delivery

Filters the search for products that can be delivered or picked up at the provided `zip-code` on the **next day**.

Example:

`1

https://{{accountName}}.myvtex.com/api/io/_v/api/intelligent-search/product_search/dynamic-estimate/next-day?zip-code=22250040

`

## Implementing sidebar filters

> The delivery promise filters are part of a beta feature and may be subject to breaking changes. If you choose to customize this functionality, ensure your implementation can adapt to updates.

In headless implementations, you must manually retrieve and render filters using VTEX Intelligent Search APIs. For example, inside a filter sidebar, where you want users to refine results based on shipping method or pickup location.

You can retrieve available filters using the `GET` [Get facets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/intelligent-search-api%23get-/facets/-facets-) endpoint and use the response to build a custom filter UI in your headless storefront. For example, mapping `name: "pickup-in-point"` to a checkbox labeled **Pickup in store**.

> Delivery-related filters (e.g. delivery, pickup-in-point) are included in the `facets` response. These are tied to the user's session and shipping context ([segment token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/session-manager-api%23post-/api/sessions)). Make sure the segment and shipping data are initialized correctly for this to work.

**Example request:**

`1

GET https://{{accountName}}.myvtex.com/_v/api/intelligent-search/facets/?query=moisturizer

`

**Example response:**

`1

{

2

 "facets": [

3

 {

4

 "name": "Shipping Method",

5

 "values": [

6

 { "id": "delivery", "name": "Delivery", "quantity": 142 },

7

 { "id": "pickup-in-point", "name": "Pickup in Store", "quantity": 37 }

8

 ]

9

 },

10

 {

11

 "name": "Pickup Location",

12

 "values": [

13

 { "id": "vtex-botafogo", "name": "VTEX Botafogo", "quantity": 12 },

14

 { "id": "vtex-sp", "name": "VTEX Sao Paulo", "quantity": 8 }

15

 ]

16

 }

17

 ]

18

}

`

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Search/delivery-promise-for-headless-stores.md)

[Access Control List« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores//docs/guides/access-control-list)[Storefront Permissions OverviewNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores//docs/guides/storefront-permissions)

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23before-you-begin)

[Using Delivery Promise parameters](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23using-delivery-promise-parameters)

[Filter combinations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filter-combinations)[Filtering by location](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filtering-by-location)[Filtering by shipping method](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filtering-by-shipping-method)[Filtering by Delivery Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filtering-by-delivery-options)[Filtering by Dynamic Estimates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filtering-by-dynamic-estimates)

[Implementing sidebar filters](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23implementing-sidebar-filters)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Search/delivery-promise-for-headless-stores.md)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23before-you-begin)

[Using Delivery Promise parameters](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23using-delivery-promise-parameters)

[Filter combinations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filter-combinations)[Filtering by location](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filtering-by-location)[Filtering by shipping method](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filtering-by-shipping-method)[Filtering by Delivery Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filtering-by-delivery-options)[Filtering by Dynamic Estimates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23filtering-by-dynamic-estimates)

[Implementing sidebar filters](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores/docs/guides/delivery-promise-for-headless-stores%23implementing-sidebar-filters)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)