Skip to content

The agent engineering platform.

docs: Integration Update - ADS4GPTs (#30153)

Ioannis Bakagiannis3444e587eee1
diff --git a/docs/docs/integrations/providers/ads4gpts.mdx b/docs/docs/integrations/providers/ads4gpts.mdx
new file mode 100644
index 0000000000..fd82f96f8e
--- /dev/null
+++ b/docs/docs/integrations/providers/ads4gpts.mdx
@@ -0,0 +1,82 @@
+# ADS4GPTs
+
+> [ADS4GPTs](https://www.ads4gpts.com/) is building the open monetization backbone of the AI-Native internet. It helps AI applications monetize through advertising with a UX and Privacy first approach.
+
+## Installation and Setup
+
+### Using pip
+You can install the package directly from PyPI:
+
+```bash
+pip install ads4gpts-langchain
+```
+
+### From Source
+Alternatively, install from source:
+
+```bash
+git clone https://github.com/ADS4GPTs/ads4gpts.git
+cd ads4gpts/libs/python-sdk/ads4gpts-langchain
+pip install .
+```
+
+## Prerequisites
+
+- Python 3.11+
+- ADS4GPTs API Key ([Obtain API Key](https://www.ads4gpts.com))
+
+## Environment Variables
+Set the following environment variables for API authentication:
+
+```bash
+export ADS4GPTS_API_KEY='your-ads4gpts-api-key'
+```
+
+Alternatively, API keys can be passed directly when initializing classes or stored in a `.env` file.
+
+## Tools
+
+ADS4GPTs provides two main tools for monetization:
+
+### Ads4gptsInlineSponsoredResponseTool
+This tool fetches native, sponsored responses that can be seamlessly integrated within your AI application's outputs.
+
+```python
+from ads4gpts_langchain import Ads4gptsInlineSponsoredResponseTool
+```
+
+### Ads4gptsSuggestedPromptTool
+Generates sponsored prompt suggestions to enhance user engagement and provide monetization opportunities.
+
+```python
+from ads4gpts_langchain import Ads4gptsSuggestedPromptTool
+```
+### Ads4gptsInlineConversationalTool
+Delivers conversational sponsored content that naturally fits within chat interfaces and dialogs.
+
+```python
+from ads4gpts_langchain import Ads4gptsInlineConversationalTool
+```
+
+### Ads4gptsInlineBannerTool
+Provides inline banner advertisements that can be displayed within your AI application's response.
+
+```python
+from ads4gpts_langchain import Ads4gptsInlineBannerTool
+```
+
+### Ads4gptsSuggestedBannerTool
+Generates banner advertisement suggestions that can be presented to users as recommended content.
+
+```python
+from ads4gpts_langchain import Ads4gptsSuggestedBannerTool
+```
+
+## Toolkit
+
+The `Ads4gptsToolkit` combines these tools for convenient access in LangChain applications.
+
+```python
+from ads4gpts_langchain import Ads4gptsToolkit
+```
+
diff --git a/docs/docs/integrations/tools/ads4gpts.ipynb b/docs/docs/integrations/tools/ads4gpts.ipynb
new file mode 100644
index 0000000000..b04fdd5195
--- /dev/null
+++ b/docs/docs/integrations/tools/ads4gpts.ipynb
@@ -0,0 +1,365 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# ADS4GPTs\n",
+ "\n",
+ "Integrate AI native advertising into your Agentic application.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Overview"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "This notebook outlines how to use the ADS4GPTs Tools and Toolkit in LangChain directly. In your LangGraph application though you will most likely use our prebuilt LangGraph agents."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Setup"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Install ADS4GPTs Package\n",
+ "Install the ADS4GPTs package using pip."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Install ADS4GPTs Package\n",
+ "# Install the ADS4GPTs package using pip\n",
+ "!pip install ads4gpts-langchain"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Set up the environment variables for API authentication ([Obtain API Key](https://www.ads4gpts.com))."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Setup Environment Variables\n",
+ "# Prompt the user to enter their ADS4GPTs API key securely\n",
+ "if not os.environ.get(\"ADS4GPTS_API_KEY\"):\n",
+ " os.environ[\"ADS4GPTS_API_KEY\"] = getpass(\"Enter your ADS4GPTS API key: \")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Instantiation"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Import the necessary libraries, including ADS4GPTs tools and toolkit.\n",
+ "\n",
+ "Initialize the ADS4GPTs tools such as Ads4gptsInlineSponsoredResponseTool. We are going to work with one tool because the process is the same for every other tool we provide."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Import Required Libraries\n",
+ "\n",
+ "import os\n",
+ "from getpass import getpass\n",
+ "\n",
+ "from ads4gpts_langchain import Ads4gptsInlineSponsoredResponseTool, Ads4gptsToolkit"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Initialize ADS4GPTs Tools\n",
+ "# Initialize the Ads4gptsInlineSponsoredResponseTool\n",
+ "inline_sponsored_response_tool = Ads4gptsInlineSponsoredResponseTool(\n",
+ " ads4gpts_api_key=os.environ[\"ADS4GPTS_API_KEY\"],\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Toolkit Instantiation\n",
+ "Initialize the Ads4gptsToolkit with the required parameters."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Initialized tool: Ads4gptsInlineSponsoredResponseTool\n",
+ "Initialized tool: Ads4gptsSuggestedPromptTool\n"
+ ]
+ }
+ ],
+ "source": [
+ "# Toolkit Initialization\n",
+ "# Initialize the Ads4gptsToolkit with the required parameters\n",
+ "toolkit = Ads4gptsToolkit(\n",
+ " ads4gpts_api_key=os.environ[\"ADS4GPTS_API_KEY\"],\n",
+ ")\n",
+ "\n",
+ "# Retrieve tools from the toolkit\n",
+ "tools = toolkit.get_tools()\n",
+ "\n",
+ "# Print the initialized tools\n",
+ "for tool in tools:\n",
+ " print(f\"Initialized tool: {tool.__class__.__name__}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Invocation"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Run the ADS4GPTs tools with sample inputs and display the results."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Inline Sponsored Response Result: {'ad_text': '<- Promoted Content ->\\n\\nLearn the sartorial ways and get your handmade tailored suit by the masters themselves with Bespoke Tailors. [Subscribe now](https://youtube.com/@bespoketailorsdubai?si=9iH587ujoWKkueFa)\\n\\n<->'}\n"
+ ]
+ }
+ ],
+ "source": [
+ "# Run ADS4GPTs Tools\n",
+ "# Sample input data for the tools\n",
+ "sample_input = {\n",
+ " \"id\": \"test_id\",\n",
+ " \"user_gender\": \"female\",\n",
+ " \"user_age\": \"25-34\",\n",
+ " \"user_persona\": \"test_persona\",\n",
+ " \"ad_recommendation\": \"test_recommendation\",\n",
+ " \"undesired_ads\": \"test_undesired_ads\",\n",
+ " \"context\": \"test_context\",\n",
+ " \"num_ads\": 1,\n",
+ " \"style\": \"neutral\",\n",
+ "}\n",
+ "\n",
+ "# Run Ads4gptsInlineSponsoredResponseTool\n",
+ "inline_sponsored_response_result = inline_sponsored_response_tool._run(\n",
+ " **sample_input, ad_format=\"INLINE_SPONSORED_RESPONSE\"\n",
+ ")\n",
+ "print(\"Inline Sponsored Response Result:\", inline_sponsored_response_result)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Async Run ADS4GPTs Tools\n",
+ "Run the ADS4GPTs tools asynchronously with sample inputs and display the results."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Async Inline Sponsored Response Result: {'ad_text': '<- Promoted Content ->\\n\\nGet the best tailoring content from Jonathan Farley. Learn to tie 100 knots and more! [Subscribe now](https://www.youtube.com/channel/UCx5hk4LN3p02jcUt3j_cexQ)\\n\\n<->'}\n"
+ ]
+ }
+ ],
+ "source": [
+ "import asyncio\n",
+ "\n",
+ "\n",
+ "# Define an async function to run the tools asynchronously\n",
+ "async def run_ads4gpts_tools_async():\n",
+ " # Run Ads4gptsInlineSponsoredResponseTool asynchronously\n",
+ " inline_sponsored_response_result = await inline_sponsored_response_tool._arun(\n",
+ " **sample_input, ad_format=\"INLINE_SPONSORED_RESPONSE\"\n",
+ " )\n",
+ " print(\"Async Inline Sponsored Response Result:\", inline_sponsored_response_result)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Toolkit Invocation\n",
+ "Use the Ads4gptsToolkit to get and run tools."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Result from Ads4gptsInlineSponsoredResponseTool: {'ad_text': '<- Promoted Content ->\\n\\nLearn the sartorial ways and get your handmade tailored suit by the masters themselves with Bespoke Tailors. [Subscribe now](https://youtube.com/@bespoketailorsdubai?si=9iH587ujoWKkueFa)\\n\\n<->'}\n",
+ "Async result from Ads4gptsInlineSponsoredResponseTool: {'ad_text': '<- Promoted Content ->\\n\\nGet the best tailoring content from Jonathan Farley. Learn to tie 100 knots and more! [Subscribe now](https://www.youtube.com/channel/UCx5hk4LN3p02jcUt3j_cexQ)\\n\\n<->'}\n"
+ ]
+ }
+ ],
+ "source": [
+ "# Sample input data for the tools\n",
+ "sample_input = {\n",
+ " \"id\": \"test_id\",\n",
+ " \"user_gender\": \"female\",\n",
+ " \"user_age\": \"25-34\",\n",
+ " \"user_persona\": \"test_persona\",\n",
+ " \"ad_recommendation\": \"test_recommendation\",\n",
+ " \"undesired_ads\": \"test_undesired_ads\",\n",
+ " \"context\": \"test_context\",\n",
+ " \"num_ads\": 1,\n",
+ " \"style\": \"neutral\",\n",
+ "}\n",
+ "\n",
+ "# Run one tool and print the result\n",
+ "tool = tools[0]\n",
+ "result = tool._run(**sample_input)\n",
+ "print(f\"Result from {tool.__class__.__name__}:\", result)\n",
+ "\n",
+ "\n",
+ "# Define an async function to run the tools asynchronously\n",
+ "async def run_toolkit_tools_async():\n",
+ " result = await tool._arun(**sample_input)\n",
+ " print(f\"Async result from {tool.__class__.__name__}:\", result)\n",
+ "\n",
+ "\n",
+ "# Execute the async function\n",
+ "await run_toolkit_tools_async()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Chaining\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "if not os.environ.get(\"OPENAI_API_KEY\"):\n",
+ " os.environ[\"OPENAI_API_KEY\"] = getpass(\"Enter your OPENAI_API_KEY API key: \")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Tool call: content='' additional_kwargs={'tool_calls': [{'id': 'call_XLR5UjF8JhylVHvrk9mTjhj8', 'function': {'arguments': '{\"id\":\"unique_user_id_001\",\"user_gender\":\"male\",\"user_age\":\"18-24\",\"ad_recommendation\":\"Stylish and trendy clothing suitable for young men going out with friends.\",\"undesired_ads\":\"formal wear, women\\'s clothing, children\\'s clothing\",\"context\":\"A young man looking for clothing to go out with friends\",\"num_ads\":1,\"style\":\"youthful and trendy\",\"ad_format\":\"INLINE_SPONSORED_RESPONSE\"}', 'name': 'ads4gpts_inline_sponsored_response'}, 'type': 'function'}], 'refusal': None} response_metadata={'token_usage': {'completion_tokens': 106, 'prompt_tokens': 1070, 'total_tokens': 1176, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 1024}}, 'model_name': 'gpt-4o-2024-08-06', 'system_fingerprint': 'fp_eb9dce56a8', 'finish_reason': 'tool_calls', 'logprobs': None} id='run-e3e64b4b-4505-4a71-bf02-a8d77bb68eee-0' tool_calls=[{'name': 'ads4gpts_inline_sponsored_response', 'args': {'id': 'unique_user_id_001', 'user_gender': 'male', 'user_age': '18-24', 'ad_recommendation': 'Stylish and trendy clothing suitable for young men going out with friends.', 'undesired_ads': \"formal wear, women's clothing, children's clothing\", 'context': 'A young man looking for clothing to go out with friends', 'num_ads': 1, 'style': 'youthful and trendy', 'ad_format': 'INLINE_SPONSORED_RESPONSE'}, 'id': 'call_XLR5UjF8JhylVHvrk9mTjhj8', 'type': 'tool_call'}] usage_metadata={'input_tokens': 1070, 'output_tokens': 106, 'total_tokens': 1176, 'input_token_details': {'audio': 0, 'cache_read': 1024}, 'output_token_details': {'audio': 0, 'reasoning': 0}}\n"
+ ]
+ }
+ ],
+ "source": [
+ "import os\n",
+ "\n",
+ "from langchain_openai import ChatOpenAI\n",
+ "\n",
+ "openai_model = ChatOpenAI(model=\"gpt-4o\", openai_api_key=os.environ[\"OPENAI_API_KEY\"])\n",
+ "model = openai_model.bind_tools(tools)\n",
+ "model_response = model.invoke(\n",
+ " \"Get me an ad for clothing. I am a young man looking to go out with friends.\"\n",
+ ")\n",
+ "print(\"Tool call:\", model_response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## API reference"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "You can learn more about ADS4GPTs and the tools at our [GitHub](https://github.com/ADS4GPTs/ads4gpts/tree/main)"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "ads4gpts-langraph-agent",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.12.9"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/libs/packages.yml b/libs/packages.yml
index 4ef43cc65e..b3e14d8f15 100644
--- a/libs/packages.yml
+++ b/libs/packages.yml
@@ -478,3 +478,8 @@ packages:
name_title: Tableau
path: .
repo: Tab-SE/tableau_langchain
+- name: ads4gpts
+ name_title: ADS4GPTs
+ path: libs/python-sdk/ads4gpts-langchain
+ repo: ADS4GPTs/ads4gpts
+ downloads: 733