[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 calling commerce apis conclusion 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/calling-commerce-apis-conclusion/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/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/calling-commerce-apis-conclusion/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/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/calling-commerce-apis-conclusion/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/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/calling-commerce-apis-conclusion/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-service)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-on-vtex-io)

[1\. Getting the Service app boilerplate](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-1-getting-the-service-app-boilerplate)

[2\. Discovering VTEX Commerce APIs and authentication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication)

[3\. Using VTEX IO clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-3-using-vtex-io-clients)

[Calling Commerce APIs - Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-conclusion)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-service)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-on-vtex-io)

[1\. Getting the Service app boilerplate](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-1-getting-the-service-app-boilerplate)

[2\. Discovering VTEX Commerce APIs and authentication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication)

[3\. Using VTEX IO clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-3-using-vtex-io-clients)

[Calling Commerce APIs - Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-conclusion)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/app-development)

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/app-development-guides)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-on-vtex-io)

[Calling Commerce APIs - Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/docs/guides/calling-commerce-apis-conclusion)

Calling Commerce APIs - Conclusion

With what was accomplished during the course, you should be able to use VTEX Commerce APIs in your apps through the use of Clients and have access to the functionalities of VTEX Core Services. The Clients are used in middlewares and retrieved from the `clients` property of `ctx` (Context). The Clients available in the `@vtex/clients` library are ready-made and have functions that make the API calls, eliminating the need to explicit the endpoint path in the middleware.

You can do more with Clients than accessing VTEX Commerce APIs. If you wish to access external providers, you can create your own custom Clients.

Furthermore, we saw that authentication is done in a specific way on VTEX IO. You have to use the proper token to identify who is the caller of the endpoint (the app, an Admin user or a Store user) and add the necessary policies in your manifest for the resources that the app will access.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion/_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/vtex-io/Calling Commerce APIs/calling-commerce-apis-conclusion.mdx)

[3\. Using VTEX IO clients« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion//docs/guides/calling-commerce-apis-3-using-vtex-io-clients)[ClientsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-conclusion//docs/guides/vtex-io-documentation-clients)

Contributors

1

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

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/vtex-io/Calling Commerce APIs/calling-commerce-apis-conclusion.mdx)

Copy page

On this page

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] Provide a guide on guides weni by vtex understanding the core concepts 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/weni-by-vtex-understanding-the-core-concepts/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/updates/release-notes)

Guides

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

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/docs/guides/managing-your-weni-by-vtex-projects)

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

[Fetching and filtering logs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/docs/guides/using-weni-run-to-execute-tool-tests)

---

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

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/storefront-development)

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

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

---

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

Guides

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

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/docs/guides/managing-your-weni-by-vtex-projects)

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

[Fetching and filtering logs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/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/weni-by-vtex-understanding-the-core-concepts/docs/guides/using-weni-run-to-execute-tool-tests)

---

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

Weni by VTEX

Weni by VTEX CLI

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

Understanding the core concepts

Learn the core concepts of the Weni by VTEX CLI.

This article contains the core concepts of the Weni by VTEX CLI.

* [Active Agents](#active-agents)
* [Passive Agents](#passive-agents)
* [Contact Fields](#contact-fields)
* [Credentials](#credentials)
* [Tools](#tools)

## Active Agents

### Overview

Active Agents are designed to proactively engage based on predefined rules and conditions. Unlike Passive Agents, which primarily react to user input, Active Agents can initiate actions or communications when specific criteria are met, often triggered by changes in data or system events.

The command to deploy an Active Agent remains the same:`weni project push agent_definition.yaml`

However, the structure of the `agent_definition.yaml` is different to accommodate the rule-based behavior and pre-processing capabilities.

### Creating an Active Agent

An Active Agent is also defined using a YAML file. Here's an example of the structure for an Active Agent:

`1

agents:

2

 my_agent:

3

 name: "Status do Pedido"

4

 description: "Agente de exemplo"

5

 rules:

6

 status_aprovado:

7

 display_name: "Status Aprovado"

8

 template: "template_status_aprovado"

9

 start_condition: "Quando o status estiver 'aprovado'"

10

 source:

11

 entrypoint: "main.StatusAprovado"

12

 path: "rules/status_aprovado"

13

 status_invoiced:

14

 display_name: "Status Invoiced"

15

 template: "template_status_invoiced"

16

 start_condition: "Quando o status estiver 'invoiced'"

17

 source:

18

 entrypoint: "main.StatusInvoiced"

19

 path: "rules/status_invoiced"

20

 pre_processing:

21

 source:

22

 entrypoint: "processing.PreProcessor"

23

 path: "pre_processors/processor"

24

 result_examples_file: "result_example.json"

`

#### YAML Elements

Below are the key elements specific to or different for Active Agent definitions:

`agents.<agent_id>`: The unique identifier for your agent.

`name`: The display name of your agent.

> Can have up to 55 characters.

`description`: A description of the agent's purpose and capabilities.

`rules`: A dictionary defining the rules that trigger the agent's actions. Each key within `rules` is a unique rule ID.

* `rules.<rule_id>.display_name`: The human-readable name for the rule.
* `rules.<rule_id>.template`: The template to be used when this rule is triggered. (Further details on templates might be needed here or in a separate section).
* `rules.<rule_id>.start_condition`: A description of the condition that must be met for this rule to activate.
* `rules.<rule_id>.source`: Defines the code to be executed when the rule is triggered. -`entrypoint`: The specific class and method (e.g., `main.StatusAprovado`) that will be executed.
   * `path`: The directory path where the rule's code is located (e.g., `rules/status_aprovado`).

`pre_processing`: Defines a pre-processing step that can transform or prepare data before rules are evaluated.

* `pre_processing.source`: Defines the code for the pre-processing logic. -`entrypoint`: The class and method for pre-processing (e.g., `processing.PreProcessor`).
   * `path`: The directory path for the pre-processing code (e.g., `pre_processors/processor`).
* `pre_processing.result_examples_file`: Required. Path to a JSON file containing examples of the data output from pre-processing. The format is an array of objects.

#### Result Example JSON Format

The `result_example.json` file should follow this structure:

`1

[

2

 {

3

 "urn": "<identifier_for_contact>",

4

 "data": {

5

 "key1": "value1",

6

 "key2": "value2"

7

 // ... other data fields relevant to the example

8

 }

9

 },

10

 {

11

 "urn": "<another_contact_identifier>",

12

 "data": {

13

 "fieldA": "dataA",

14

 "fieldB": "dataB"

15

 }

16

 }

17

 // ... more examples

18

]

`

Each object in the array represents a test case or an example scenario.

* `urn`: A unique identifier for the contact (e.g., a phone number, user ID).
* `data`: An object containing the data relevant to this specific example. The structure of this `data` object will depend on your agent's specific needs and the information it processes.

### Basic Structure

The project structure for an Active Agent might look like this, incorporating rules and pre-processing logic:

`1

your-project-name/

2

├── rules/

3

│ ├── status_aprovado/

4

│ │ └── main.py

5

│ │ └── requirements.txt

6

│ └── status_invoiced/

7

│ └── main.py

8

│ └── requirements.txt

9

├── pre_processors/

10

│ └── processor/

11

│ └── processing.py

12

│ └── requirements.txt

13

├── agent_definition.yaml

14

└── result_example.json

`

This structure helps organize the different components of your Active Agent.

## Passive Agents

This page describes Passive Agents, which are AI-powered workers designed to operate autonomously by reacting to user input or specific triggers within a defined context.

### Overview

Passive Agents are AI-powered workers designed to operate autonomously within specific contexts, using generative AI to make decisions based on specified problems. In the context of Weni by VTEX CLI, these agents are specifically optimized for customer service operations, serving as the frontline communication interface between companies and their customers by responding to inquiries and executing tasks based on their configured skills.

Key features:

* Autonomous decision-making capabilities
* Context-specific operations
* Built-in generative AI processing
* Customer service optimization

With Weni by VTEX CLI, you can define and deploy multiple agents that work together to solve real-world problems with precision, quality, and security. These agents can be equipped with various tools that enable them to interact with the external world within defined boundaries.

### Creating a Passive Agent

A Passive Agent consists of an agent definition. In Weni by VTEX CLI, this definition is made using a YAML file, where you can specify its behavior, instructions, and skills.

Here is an example of how you can define your agent in a YAML file:

`1

agents:

2

 cep_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

`

#### YAML Elements

\=== "Agent"

`Name`: The name of your agent that will be displayed in the Weni by VTEX Platform.

> Can have up to 55 characters.

`Credentials`: The credentials used in the tools you define for your agent. For more detailed information about this definition, see [Authenticating with your Weni by VTEX account](authentication.md).

`Description`: Important information about your agent, where you can describe its purpose, capabilities, and other relevant details.

`Instructions`: Here you can define rules and guidelines that your agent should follow.

> Must have a minimum of 40 characters.

`Guardrails`: You can list boundaries and limitations for your agent, such as topics it should not discuss.

> Must have a minimum of 40 characters.

\=== "Tool"

`Name`: The name of the tool that will be associated with the agent in the Weni by VTEX Platform.

> Can have up to 40 characters.

`Source`: The location or path where the tool can be found. It contains three important elements:

* `path`: The directory path where your tool's code is located. This is typically a relative path from the root of your project.
* `entrypoint`: The specific class that will be executed when the tool is called. It follows the format "file\_name.ClassName". You can see a practical example of the tool implementation for this entrypoint in the [Tools section](#tools), where the GetAddress class from this example is implemented.
* `path_test`: The location of the test file for your tool, which contains test cases to validate the tool's functionality.

`Description`: Information about the tool, including its purpose and objectives.

`Parameters`: The parameters or variables used in your agent's tool.

* `description`: A clear explanation of what the parameter is used for and what kind of data it expects.
* `type`: The data type of the parameter (one of: string, number, integer, boolean, array).
* `required`: A boolean value (`true` or `false`) indicating whether the parameter must be provided for the tool to function properly. If set to true, the agent will ask the user for this information if it's not available before proceeding with the request.
* `contact_field`: Specifies if the parameter should be stored as a contact field in the user's profile for future reference. If set to true, the respective parameter will become information that persists for the user integrated with the Weni by VTEX Platform. This brings benefits to the user experience because in future interactions, your agent may not need to request this information from the user again. Read more about contact fields in [Contact Fields](./contact-fields.md).

### Basic Structure

The basic structure of your project should consist of your agent definition written in YAML and your agent's tools organized into directories. It is not mandatory to organize your tools in a 'tools' directory, but it is highly recommended as a best practice.

Based on the definition example below:

`1

agents:

2

 cep_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

`

Your project should have the following structure:

`1

your-project-name/

2

├── tools/

3

│ ├── get_address/main.py

4

└── agent_definition.yaml

`

## Contact Fields

### Overview

Contact fields are persistent information about contacts who interact with your agents. By enabling contact fields in your tools, you elevate the user experience to a new level, as your agents can interact with the Weni by VTEX Platform to accurately obtain information about the contact.

### How Contact Fields Work

When you mark a parameter as a contact field in your tool definition, that information becomes persistent in the user's profile within the Weni by VTEXPlatform. This creates several advantages:

1. **Improved User Experience**: Users don't need to repeatedly provide the same information in future interactions
2. **Personalized Interactions**: Agents can address users with personalized information from previous conversations
3. **Streamlined Conversations**: Reduces the number of questions agents need to ask, making interactions more efficient

### Implementing Contact Fields

To implement a contact field in your tool, you need to set the `contact_field` parameter to `true` in your agent definition YAML file:

`1

parameters:

2

 - tool_parameter:

3

 description: "User's full name"

4

 type: "string"

5

 required: true

6

 contact_field: true

`

When this parameter is processed during a conversation, the information provided by the user will be:

* Stored in the Weni by VTEX Platform associated with that specific contact
* Available for retrieval and update in future interactions
* Accessible to all agents that have permission to view this contact field

### Best Practices

When implementing contact fields, consider the following best practices:

* **Only store relevant information**: Not every parameter is necessarily a contact field; focus on information that will be useful in future interactions. Consider whether the parameter contains information important enough to be persisted for the contact.
* **Use descriptive parameter names**: This helps maintain organization when multiple contact fields are in use
* **Validate data before storing**: Ensure the information is in the correct format before saving it as a contact field

### Example Use Cases

Contact fields are particularly useful for:

* **Personal information**: Names, addresses, preferences
* **Account details**: Customer IDs, subscription types
* **Context-specific data**: Preferred language, communication preferences
* **Historical information**: Previous purchases, service history

By effectively utilizing contact fields, you can create more intelligent, context-aware agents that provide a seamless experience for your users.

## Credentials

Credentials are confidential information that your agents can use when invoking a specific tool. To fully understand how to incorporate credentials into your agents, we recommend reading this entire content and the following complementary resources: [Agents](./agents.md) and [tools](./tools.md).

Credentials are extremely important at two stages of your agents' development cycle:

* For local testing of tools during development
* For your agent to be used in production on channels integrated with the Weni by VTEX platform, such as WhatsApp or any other

### Credential Structure

In your agent definition file (YAML), credentials are defined in the `credentials` section and follow this structure:

`1

agents:

2

 my_agent:

3

 credentials:

4

 API_KEY:

5

 label: "API Key"

6

 placeholder: "your-api-key-here"

7

 is_confidential: true

8

 API_SECRET:

9

 label: "API Secret"

10

 placeholder: "your-api-secret-here"

11

 BASE_URL:

12

 label: "Base URL"

13

 placeholder: "https://api.example.com"

14

 is_confidential: false

`

Each credential has the following attributes:

* **label**: Human-readable name that will be displayed in the Weni by VTEX Platform interface
* **placeholder**: Example text or hint about what should be entered
* **is\_confidential**: Indicates whether the credential contains sensitive information (defaults to `true` if not specified)

### Credentials in Production Environment

When your agent is deployed on the Weni by VTEX Platform, credentials are securely managed by the system. This ensures that sensitive information, such as API keys and access tokens, is stored and transmitted securely.

#### How to Configure Credentials for Production

1. **Define credentials in the YAML file**: Specify all necessary credentials in the `credentials` section of your agent definition file.
2. **Deploy your agent**: When pushing your agent to the Weni by VTEX Platform using the CLI, the system will automatically detect the credentials defined in your YAML file.
3. **Configure values in the interface**: Administrators will be able to configure the actual credential values through the Weni by VTEX Platform interface, without needing to modify the code.
4. **Associate credentials with tools**: Ensure that each tool that needs credentials is correctly configured to access them through the `context.credentials` object.

> **Note**: When you assign your agent in the Weni by VTEX Platform, the credentials defined in your YAML file will be displayed in the interface for configuration. For example, if you have the following agent definition:
>
> `1
>
> agents:
>
> 2
>
> cep_agent:
>
> 3
>
> credentials:
>
> 4
>
> api_key:
>
> 5
>
> label: "API Key"
>
> 6
>
> placeholder: "Enter your API key"
>
> 7
>
> name: "CEP Agent"
>
> 8
>
> description: "Weni's CEP agent with components"
>
> 9
>
> instructions:
>
> 10
>
> - "You are an expert in providing addresses to the user based on a postal code provided by the user"
>
> 11
>
> - "The user will send a ZIP code (postal code) and you must provide the address corresponding to this code."
>
> 12
>
> guardrails:
>
> 13
>
> - "Don't talk about politics, religion or any other sensitive topic. Keep it neutral."
>
> 14
>
> tools:
>
> 15
>
> - get_address:
>
> 16
>
> name: "Get Address"
>
> 17
>
> source:
>
> 18
>
> path: "tools/get_address"
>
> 19
>
> entrypoint: "main.GetAddress"
>
> 20
>
> path_test: "test_definition.yaml"
>
> 21
>
> description: "Function to get the address from the postal code"
>
> 22
>
> parameters:
>
> 23
>
> - cep:
>
> 24
>
> description: "postal code of a place"
>
> 25
>
> type: "string"
>
> 26
>
> required: true
>
> 27
>
> contact_field: true
>
> `
>
> After running the command `weni project push agent_definition.yaml` to upload your agent to your project on the Weni by VTEX Platform, you'll find your agent in the Agent Builder gallery. When you select and assign this agent, you'll be prompted to enter the actual values for the credentials you defined (in this case, the API Key).

>> An error occurred while loading the image https://github.com/vtexdocs/dev-portal-content/main/docs/guides/Weni-by-VTEX/CLI/assets/agent-builder-gallery.png

```` 1

> ![Agents Gallery](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/main/docs/guides/Weni-by-VTEX/CLI/assets/agent-builder-gallery.png)

2

3

> Enter you credentials:

4

5

> ![Assign Agent](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/main/docs/guides/Weni-by-VTEX/CLI/assets/agent-builder-assign.png)

6

7

#### Security in Production

8

9

In the Weni by VTEX Platform, credentials are:

10

11

- Stored in encrypted form

12

- Never exposed in logs or user interfaces

13

14

### Credentials for Local Testing

15

16

During development and local testing of your tools, you'll need to provide credentials for your tools to work correctly without depending on the Weni by VTEX Platform infrastructure.

17

18

#### Configuring Credentials for Local Development

19

20

For local testing, the CLI reads a `.env` file located in the tool's `source.path` directory. Define the same credential names that are declared in your agent definition. This mirrors how credentials are injected in production.

21

22

For example, if your CEP Agent definition has the following credentials:

23

24

```yaml

25

agents:

26

 cep_agent:

27

 credentials:

28

 api_key:

29

 label: "API Key"

30

 placeholder: "Enter your API key"

31

 # Rest of the agent definition...

 ````

Create a `.env` file inside the tool folder (e.g. `tools/get_address/.env`) with:

`1

api_key=your-development-api-key

`

## Tools

### What Are Tools?

Tools are powerful tools available to your agent that enable it to interact with the external environment and the real world. Think of tools as superpowers for your agent - you can create virtually any capability your agent needs by writing Python code that implements your specific business logic!

### Why Tools Matter

Tools transform your agent from a simple conversational interface into a powerful tool that can:

* Fetch real-time data from external APIs
* Perform complex calculations and data processing
* Interact with databases and storage systems
* Execute custom business logic specific to your needs
* Integrate with third-party services and platforms
* Automate tasks and workflows

### Using Tools in Your Agent

Once you've created a tool, you can relate it to your agent by defining it in your agent's YAML configuration file, as demonstrated in the [Agents](./agents.md) documentation page. The agent will automatically detect when to use the tool based on the context of the conversation.

By creating custom tools, you can extend your agent's capabilities to handle specific tasks relevant to your use case, making your agent truly tailored to your business needs.

### Tool Example: Address Lookup

Here's an example of a tool that allows an agent to interact with the real world to precisely obtain information about a postal code (CEP in Brazil):

`1

from weni import Tool

2

from weni.context import Context

3

from weni.responses import TextResponse

4

import requests

5

6

class GetAddress(Tool):

7

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

8

9

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

10

11

 print(cep)

12

13

 address_response = self.get_address_by_cep(cep=cep)

14

15

 print(address_response)

16

17

 return TextResponse(data=address_response)

18

19

 def get_address_by_cep(self, cep):

20

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

21

22

 response = requests.get(url)

23

24

 return response.json()

`

### Code Explanation

\=== "For Beginners"

If you're new to programming, here's a simpler explanation of what this code does:

1. **Imports**: First, we bring in the tools we need:
   * `Tool`: The base class that gives our tool its core functionality
   * `Context`: Holds information about the conversation
   * `TextResponse`: Helps us send text back to the user
   * `requests`: A tool that lets us get information from websites
2. **Class Definition**: We create a new tool called `GetAddress` that can look up addresses.
3. **Execute Method**: This is the main part that runs when someone uses the tool:
   * It gets the postal code (CEP) that the user provided
   * It prints the CEP to help with debugging
   * It calls another function to find the address for that CEP
   * It returns the address information to the user
4. **Helper Method**: The `get_address_by_cep` function:
   * Takes a postal code as input
   * Creates a web address (URL) to look up that postal code
   * Sends a request to a website that knows about addresses
   * Gets back information about the address and returns it

Think of this tool like a helper that knows how to look up addresses in a phone book when you give it a postal code!

\=== "For Experienced Developers"

For those familiar with Python and API development:

1. **Imports**: We import the necessary Weni by VTEX framework classes (`Tool`, `Context`, `TextResponse`) and the `requests` library for HTTP operations.
2. **Class Definition**: We define a `GetAddress` class that inherits from the base `Tool` class, which provides the framework integration.
3. **Execute Method**: This is the entry point that the Weni by VTEX framework calls:
   * It extracts the "cep" parameter from the context object using a get() with a default empty string
   * It includes debug print statements for logging
   * It delegates the actual API call to a separate method for better separation of concerns
   * It returns a `TextResponse` object with the JSON data from the API
4. **Helper Method**: The `get_address_by_cep` method:
   * Constructs the ViaCEP API endpoint URL with string interpolation
   * Makes a GET request to the external API
   * Returns the parsed JSON response directly
   * Note that this implementation is minimal and lacks error handling for production use

This implementation follows a simple separation of concerns pattern but could be enhanced with error handling, input validation, response formatting, and proper logging for production use.

### Creating Your Own Tools

To create your own tool:

1. **Define Your Tool Class**: Create a new Python class that inherits from `Tool`
2. **Implement the Execute Method**: Override the `execute(self, context: Context)` method with your business logic
3. **Add Helper Methods**: Separate concerns by breaking down complex logic into helper methods
4. **Implement Error Handling**: Add robust error handling for API calls, data processing, and edge cases
5. **Add Logging**: Include appropriate logging for monitoring and debugging
6. **Write Tests**: Create comprehensive test cases using the test file specified in `path_test`
7. **Configure Your Tool**: Add your tool to your agent's YAML configuration with appropriate parameters and any credentials required by your tool.

### Tools with Credentials

When your tool needs to interact with external services that require authentication, you'll need to use credentials or secrets. The Weni by VTEX framework provides a secure way to manage these credentials through the `Context` object.

#### How to Access Credentials

Credentials are accessed through the `Context` object that is passed to your tool's `execute` method. This ensures that sensitive information is handled securely and isn't hardcoded in your tool's code.

Here's an example of how to modify our `GetAddress` tool to use credentials for an API that requires authentication:

`1

from weni import Tool

2

from weni.context import Context

3

from weni.responses import TextResponse

4

import requests

5

6

class GetAddressWithAuth(Tool):

7

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

8

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

9

10

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

11

12

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

13

14

 return TextResponse(data=address_response)

15

16

 def get_address_by_cep(self, cep, api_key):

17

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

18

19

 headers = {

20

 "Authorization": f"Bearer {api_key}"

21

 }

22

23

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

24

25

 return response.json()

`

#### Configuring Credentials in Your Agent Definition

To make credentials available to your tool, you need to define them in your agent's YAML configuration file. Here's an example:

`1

agents:

2

 cep_agent:

3

 credentials:

4

 api_key:

5

 label: "API Key"

6

 placeholder: "Api Key"

7

 name: "CEP Agent"

8

 description: "Weni's CEP agent"

9

 instructions:

10

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

11

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

12

 guardrails:

13

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

14

 tools:

15

 - get_address:

16

 name: "Get Address"

17

 source:

18

 path: "tools/get_address"

19

 entrypoint: "main.GetAddressWithAuth"

20

 path_test: "test_definition.yaml"

21

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

22

 parameters:

23

 - cep:

24

 description: "postal code of a place"

25

 type: "string"

26

 required: true

27

 contact_field: true

`

> **Highly Recommended**: For a comprehensive understanding of how credentials work in production environments and local testing, please read the [Credentials](./credentials.md) documentation page. This will help you properly manage sensitive information and understand the different approaches for development and production environments.

#### Best Practices for Handling Credentials

When working with credentials in your tools:

1. **Never hardcode credentials** in your tool's code.
2. **Always access credentials through the Context object**.
3. **Use environment variables** for local development and testing.
4. **Implement proper error handling** for cases where credentials might be missing or invalid.

By following these practices, you can create secure tools that interact with authenticated services while keeping sensitive information protected.

### Best Practices for Tools

When creating tools, follow these best practices:

* **Single Responsibility**: Each tool should have a clear, focused purpose
* **Comprehensive Error Handling**: Implement robust error handling for all external calls and edge cases
* **Input Validation**: Validate all input parameters before processing
* **Security Considerations**: Handle sensitive data appropriately and follow security best practices
* **Testability**: Design your tools to be easily testable with both unit and integration tests
* **Version Control**: Use a GitHub repository to version your tools, allowing you to track changes, collaborate with others, and easily roll back to previous versions if needed

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/_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/weni-by-vtex-understanding-the-core-concepts.md)

[Managing your Weni by VTEX projects« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts//docs/guides/managing-your-weni-by-vtex-projects)[Working with Weni by VTEX agentsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts//docs/guides/working-with-weni-by-vtex-agents)

Contributors

1

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

ON THIS PAGE

[Active Agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23active-agents)

[Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23overview)[Creating an Active Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23creating-an-active-agent)[Basic Structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23basic-structure)

[Passive Agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23passive-agents)

[Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23overview)[Creating a Passive Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23creating-a-passive-agent)[Basic Structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23basic-structure)

[Contact Fields](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23contact-fields)

[Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23overview)[How Contact Fields Work](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23how-contact-fields-work)[Implementing Contact Fields](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23implementing-contact-fields)[Best Practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23best-practices)[Example Use Cases](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23example-use-cases)

[Credentials](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23credentials)

[Credential Structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23credential-structure)[Credentials in Production Environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23credentials-in-production-environment)

[Tools](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23tools)

[What Are Tools?](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23what-are-tools)[Why Tools Matter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23why-tools-matter)[Using Tools in Your Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23using-tools-in-your-agent)[Tool Example: Address Lookup](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23tool-example-address-lookup)[Code Explanation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23code-explanation)[Creating Your Own Tools](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23creating-your-own-tools)[Tools with Credentials](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23tools-with-credentials)[Best Practices for Tools](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23best-practices-for-tools)

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/weni-by-vtex-understanding-the-core-concepts.md)

Copy page

On this page

ON THIS PAGE

[Active Agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23active-agents)

[Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23overview)[Creating an Active Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23creating-an-active-agent)[Basic Structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23basic-structure)

[Passive Agents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23passive-agents)

[Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23overview)[Creating a Passive Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23creating-a-passive-agent)[Basic Structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23basic-structure)

[Contact Fields](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23contact-fields)

[Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23overview)[How Contact Fields Work](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23how-contact-fields-work)[Implementing Contact Fields](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23implementing-contact-fields)[Best Practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23best-practices)[Example Use Cases](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23example-use-cases)

[Credentials](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23credentials)

[Credential Structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23credential-structure)[Credentials in Production Environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23credentials-in-production-environment)

[Tools](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23tools)

[What Are Tools?](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23what-are-tools)[Why Tools Matter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23why-tools-matter)[Using Tools in Your Agent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23using-tools-in-your-agent)[Tool Example: Address Lookup](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23tool-example-address-lookup)[Code Explanation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23code-explanation)[Creating Your Own Tools](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23creating-your-own-tools)[Tools with Credentials](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23tools-with-credentials)[Best Practices for Tools](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/weni-by-vtex-understanding-the-core-concepts/docs/guides/weni-by-vtex-understanding-the-core-concepts%23best-practices-for-tools)

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] Provide a guide on guides brands 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/brands/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/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/brands/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/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/brands/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/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/brands/updates/release-notes)

Guides

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

---

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

---

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

---

Integration Guides

---

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

[Categories](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/categories)

[Brands](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands)

[Products](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/products)

[Specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/specifications)

[Product specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/product-specifications)

[SKU specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/sku-specifications)

[Updating SKU Specifications with Catalog API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/updating-sku-specifications-with-catalog-api)

[SKUs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/skus)

[Images](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/images)

[Alternative API requests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/alternative-api-requests)

[How to implement product color variation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/how-to-implement-product-color-variation)

---

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

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/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/brands/docs/guides/activity-flow)

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides)

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

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

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

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

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/troubleshooting)

---

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

[Categories](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/categories)

[Brands](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands)

[Products](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/products)

[Specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/specifications)

[Product specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/product-specifications)

[SKU specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/sku-specifications)

[Updating SKU Specifications with Catalog API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/updating-sku-specifications-with-catalog-api)

[SKUs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/skus)

[Images](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/images)

[Alternative API requests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/alternative-api-requests)

[How to implement product color variation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/how-to-implement-product-color-variation)

---

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

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/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/brands/docs/guides/activity-flow)

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides)

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

[Brands](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands)

Brands

[Brands](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/7i3sB8fgkqUp5NoH5yJtfh) work as product attributes that help end customers to identify a product and the business behind it.

A product can only be associated with a single brand. Each product needs to be associated with a brand to exist. Therefore, creating a Brand is a mandatory step when configuring your Catalog. Usually, it is the second step for catalog integration, after creating categories. For more information on Catalog structure and integration flow at VTEX, check our [Catalog overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/catalog-overview).

## Create a brand

To create a brand, use the [Create Brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-post-brand) endpoint. In this endpoint, the request and the response follow the same structure. See the example below:

**Request and response body example**

`1

{

2

 "Id": 2000013,

3

 "Name": "Orma Carbon",

4

 "Text": "Orma Carbon",

5

 "Keywords": "orma",

6

 "SiteTitle": "Orma Carbon",

7

 "Active": true,

8

 "MenuHome": true,

9

 "AdWordsRemarketingCode": "",

10

 "LomadeeCampaignCode": "",

11

 "Score": null,

12

 "LinkId": "orma-carbon"

13

}

`

> Do not insert empty spaces at the end of the brand name. VTEX interprets that as a new brand, causing duplication.

> You must activate the brand, otherwise the associated products will not be indexed and thereafter will not be displayed on the website.

## Edit a brand

You can edit an existing brand by using the [Update Brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-put-brand) endpoint with the same request body structure as to create a brand. The only non-editable information is the Brand ID.

## Get brand list

You can get information about all the brands configured in your store by placing a request to one of the following endpoints:

* [Get Brand List](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-brand-list): Full list of brands in your store. This route's response is limited to 20k results. If you need to obtain more results, please use the [Get Brand List per page](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/brandlistperpage)endpoint instead to get a paginated response.
* [Get Brand List per page](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/brandlistperpage): Paginated list of brands in your store.

## Get brand

You can retrieve information about a specific brand by making a request to [Get Brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-brand).

## Delete a brand

To delete a brand, use the [Delete Brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-delete-brand) endpoint. This action is permanent and cannot be undone.

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/_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/brands/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

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/Integration-Guides/catalog-integration/brands.md)

[Categories« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands//docs/guides/categories)[ProductsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands//docs/guides/products)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/_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/brands/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

ON THIS PAGE

[Create a brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23create-a-brand)

[Edit a brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23edit-a-brand)

[Get brand list](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23get-brand-list)

[Get brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23get-brand)

[Delete a brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23delete-a-brand)

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/Integration-Guides/catalog-integration/brands.md)

Copy page

On this page

ON THIS PAGE

[Create a brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23create-a-brand)

[Edit a brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23edit-a-brand)

[Get brand list](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23get-brand-list)

[Get brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23get-brand)

[Delete a brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/brands/docs/guides/brands%23delete-a-brand)

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