WhatsApp agent#
FastAgency allows you to quickly create workflows with WhatsApp communication abilities, making it easy to integrate message sending.
Adding WhatsApp Capabilities to Agents#
FastAgency provides two ways to add WhatsApp communication capabilities to agents. You can either:
- Use a
WhatsAppAgent, which comes with built-in WhatsApp message sending capabilities (recommended) - Enhance an existing agent with WhatsApp capability using
WhatsAppTool
In this guide, we'll demonstrate both methods with a real-world example. We’ll create a workflow where a WhatsAppAgent will help you send messages to your phone over WhatsApp.
We’ll build agents and assign them the task: “Send 'Hi!' to YOUR_NUMBER” to showcase its ability to interact with Infobip WhatsApp API.
Installation & Setup#
We strongly recommend using Cookiecutter for setting up the project. Cookiecutter creates the project folder structure, default workflow, automatically installs all the necessary requirements, and creates a devcontainer that can be used with Visual Studio Code.
You can setup the project using Cookiecutter by following the project setup guide.
Alternatively, you can use pip + venv. Before getting started, make sure you have installed FastAgency with support for the AutoGen runtime by running the following command:
This command installs FastAgency with support for the Console interface and AutoGen framework.
Creating your WhatsApp API key#
Create Infobip Account#
Step 1: If you don’t have a Infobip account, you’ll need to sign up:
- Go to Infobip Portal and create account
Step 2: Settings
- In the Customize your experience section, choose:
- Customer support
- By using code (APIs, SDKs)
Step 3: Test WhatsApp API
- After you have created the account, you will be redirected Infobip Homepage.
- Check the Send your first message option and send a WhatsApp message to yourself.
- In this tutorial, we will only be sending messages to your own number
Important
Upon receiving this message, please reply (e.g., with "Hi") to initiate the session. Note that sessions expire after 24 hours. If your session has expired, simply send another message to create a new one.
Copy the API Key from the top-right corner and continue with the next steps.
Step 4: Register your WhatsApp sender (Optional)
- By default, Infobip number will be used as the sender for your messages.
- If you wish to create a new sender phone number and customize your branding (including your name and logo), click on Register Sender.
Set Up Your API Key in the Environment#
You can set the WhatsApp API key in your terminal as an environment variable:
Example: Create a workflow that will send a WhatsApp message to your phone#
Step-by-Step Breakdown#
1. Import Required Modules#
The example starts by importing the necessary modules from AutoGen and FastAgency. These imports lay the foundation for building and running multi-agent workflows.
import os
from typing import Any
from autogen import UserProxyAgent
from fastagency import UI, FastAgency
from fastagency.runtimes.autogen import AutoGenWorkflows
from fastagency.runtimes.autogen.agents.whatsapp import WhatsAppAgent
from fastagency.ui.console import ConsoleUI
To create a WhatsAppAgent, simply import WhatsAppAgent, which comes with built-in WhatsApp capabilities, and use it as needed.
import os
from typing import Any
from autogen import UserProxyAgent
from autogen.agentchat import ConversableAgent
from fastagency import UI, FastAgency
from fastagency.runtimes.autogen import AutoGenWorkflows
from fastagency.runtimes.autogen.tools import WhatsAppTool
from fastagency.ui.console import ConsoleUI
To enhance existing agents with WhatsApp communication capability, import WhatsAppTool from FastAgency and ConversableAgent from AutoGen.
2. Configure the Language Model (LLM)#
Here, the large language model is configured to use the gpt-4o model, and the API key is retrieved from the environment. This setup ensures that both the user and WhatsAppAgent can interact effectively.
llm_config = {
"config_list": [
{
"model": "gpt-4o-mini",
"api_key": os.getenv("OPENAI_API_KEY"),
}
],
"temperature": 0.8,
}
3. Define the Workflow and Agents#
In this step, we are going to create two agents and specify the initial message that will be displayed to users when the workflow starts:
-
UserProxyAgent: This agent simulates the user interacting with the system. -
WhatsAppAgent: This agent has built-in capability to communicate with Infobip WhatsApp API.
user_agent = UserProxyAgent(
name="User_Agent",
system_message="You are a user agent, when the message is successfully sent, you can end the conversation by sending 'TERMINATE'",
llm_config=llm_config,
human_input_mode="NEVER",
is_termination_msg=is_termination_msg,
)
whatsapp_agent = WhatsAppAgent(
name="Assistant_Agent",
llm_config=llm_config,
human_input_mode="NEVER",
executor=user_agent,
# This is the default sender number for Infobip.
# If you want to use your own sender, please update the value below:
sender="447860099299",
whatsapp_api_key=os.getenv("WHATSAPP_API_KEY", ""),
is_termination_msg=is_termination_msg,
)
When initiating the WhatsAppAgent, the executor parameter must be provided. This can be either a single instance of ConversableAgent or a list ofConversableAgent instances.
The WhatsAppAgent relies on the executor agent(s) to execute the sending of WhatsApp messages. In this example, the whatsapp_agent agent will call the user_agent agent with the necessary instructions when contacting the WhatsApp API required, and the user_agent will execute those instructions.
In this step, we create two agents, a WhatsApp tool and set an initial message that will be displayed to users when the workflow starts:
-
UserProxyAgent: This agent simulates the user interacting with the system. -
ConversableAgent: This is the conversable agent to which we will be adding WhatsApp capabilities. -
WhatsAppTool: The tool that gives theConversableAgentthe ability to interact with WhatsApp.
user_agent = UserProxyAgent(
name="User_Agent",
system_message="You are a user agent, when the message is successfully sent, you can end the conversation by sending 'TERMINATE'",
llm_config=llm_config,
human_input_mode="NEVER",
is_termination_msg=is_termination_msg,
)
assistant_agent = ConversableAgent(
name="Assistant_Agent",
system_message="You are a useful assistant for sending messages to whatsapp, use 447860099299 as your (sender) number.",
llm_config=llm_config,
human_input_mode="NEVER",
is_termination_msg=is_termination_msg,
)
whatsapp = WhatsAppTool(
whatsapp_api_key=os.getenv("WHATSAPP_API_KEY", ""),
)
Now, we need to register the WhatsAppTool with a caller and executor. This setup allows the caller to use the WhatsAppTool for performing real-time WhatsApp interactions.
The executor can be either a single instance of ConversableAgent or a list ofConversableAgent instances.
The caller relies on the executor agent(s) to execute the WhatsApp tasks. In this example, the assistant_agent agent will call the user_agent agent with the necessary instructions when WhatsApp interaction is required, and the user_agent will execute those instructions.
4. Enable Agent Interaction and Chat#
Here, the user agent starts a conversation with the WhatsAppAgent, which will send a message to the specified number. The conversation is then summarized using a method provided by the LLM.
5. Create and Run the Application#
Finally, we create the FastAgency application and launch it using the console interface.
Complete Application Code#
whatsapp_agent.py
import os
from typing import Any
from autogen import UserProxyAgent
from fastagency import UI, FastAgency
from fastagency.runtimes.autogen import AutoGenWorkflows
from fastagency.runtimes.autogen.agents.whatsapp import WhatsAppAgent
from fastagency.ui.console import ConsoleUI
llm_config = {
"config_list": [
{
"model": "gpt-4o-mini",
"api_key": os.getenv("OPENAI_API_KEY"),
}
],
"temperature": 0.8,
}
wf = AutoGenWorkflows()
@wf.register(name="simple_whatsapp", description="WhatsApp chat") # type: ignore[type-var]
def whatsapp_workflow(ui: UI, params: dict[str, Any]) -> str:
def is_termination_msg(msg: dict[str, Any]) -> bool:
return msg["content"] is not None and "TERMINATE" in msg["content"]
initial_message = ui.text_input(
sender="Workflow",
recipient="User",
prompt="I can help you with sending a message over whatsapp, what would you like to send?",
)
user_agent = UserProxyAgent(
name="User_Agent",
system_message="You are a user agent, when the message is successfully sent, you can end the conversation by sending 'TERMINATE'",
llm_config=llm_config,
human_input_mode="NEVER",
is_termination_msg=is_termination_msg,
)
whatsapp_agent = WhatsAppAgent(
name="Assistant_Agent",
llm_config=llm_config,
human_input_mode="NEVER",
executor=user_agent,
# This is the default sender number for Infobip.
# If you want to use your own sender, please update the value below:
sender="447860099299",
whatsapp_api_key=os.getenv("WHATSAPP_API_KEY", ""),
is_termination_msg=is_termination_msg,
)
chat_result = user_agent.initiate_chat(
whatsapp_agent,
message=initial_message,
summary_method="reflection_with_llm",
max_turns=5,
)
return chat_result.summary # type: ignore[no-any-return]
app = FastAgency(provider=wf, ui=ConsoleUI())
whatsapp_tool.py
import os
from typing import Any
from autogen import UserProxyAgent
from autogen.agentchat import ConversableAgent
from fastagency import UI, FastAgency
from fastagency.runtimes.autogen import AutoGenWorkflows
from fastagency.runtimes.autogen.tools import WhatsAppTool
from fastagency.ui.console import ConsoleUI
llm_config = {
"config_list": [
{
"model": "gpt-4o-mini",
"api_key": os.getenv("OPENAI_API_KEY"),
}
],
"temperature": 0.8,
}
wf = AutoGenWorkflows()
@wf.register(name="simple_whatsapp", description="WhatsApp chat") # type: ignore[type-var]
def whatsapp_workflow(ui: UI, params: dict[str, Any]) -> str:
def is_termination_msg(msg: dict[str, Any]) -> bool:
return msg["content"] is not None and "TERMINATE" in msg["content"]
initial_message = ui.text_input(
sender="Workflow",
recipient="User",
prompt="I can help you with sending a message over whatsapp, what would you like to send?",
)
user_agent = UserProxyAgent(
name="User_Agent",
system_message="You are a user agent, when the message is successfully sent, you can end the conversation by sending 'TERMINATE'",
llm_config=llm_config,
human_input_mode="NEVER",
is_termination_msg=is_termination_msg,
)
assistant_agent = ConversableAgent(
name="Assistant_Agent",
system_message="You are a useful assistant for sending messages to whatsapp, use 447860099299 as your (sender) number.",
llm_config=llm_config,
human_input_mode="NEVER",
is_termination_msg=is_termination_msg,
)
whatsapp = WhatsAppTool(
whatsapp_api_key=os.getenv("WHATSAPP_API_KEY", ""),
)
whatsapp.register(
caller=assistant_agent,
executor=user_agent,
)
chat_result = user_agent.initiate_chat(
assistant_agent,
message=initial_message,
summary_method="reflection_with_llm",
max_turns=5,
)
return chat_result.summary # type: ignore[no-any-return]
app = FastAgency(provider=wf, ui=ConsoleUI())
Running the Application#
Ensure you have set your OpenAI API key in the environment. The command will launch a console interface where users can input their requests and interact with the whatsapp agent.
Output#
Once you run it, FastAgency automatically detects the appropriate app to execute and runs it. The application will then prompt you with: "I can help you with sending a message over whatsapp, what would you like to send?"
╭─── Python package file structure ────╮
│ │
│ 📁 docs │
│ ├── 🐍 __init__.py │
│ └── 📁 docs_src │
│ ├── 🐍 __init__.py │
│ └── 📁 user_guide │
│ ├── 🐍 __init__.py │
│ └── 📁 runtimes │
│ ├── 🐍 __init__.py │
│ └── 📁 autogen │
│ ├── 🐍 __init__.py │
│ └── 🐍 whatsapp.py │
│ │
╰──────────────────────────────────────╯
2024-11-06 12:05:31,205 [INFO] Importing autogen.base.py
/home/vscode/.local/lib/python3.10/site-packages/pydantic/_internal/_config.py:341: UserWarning: Valid config keys have changed in V2:
* 'keep_untouched' has been renamed to 'ignored_types'
warnings.warn(message, UserWarning)
2024-11-06 12:05:31,512 [INFO] Patched OpenAPIParser.parse_schema
2024-11-06 12:05:31,512 [INFO] Patched Operation.function_name
2024-11-06 12:05:31,512 [INFO] Patched fastapi_code_generator.__main__.generate_code
2024-11-06 12:05:31,512 [INFO] Patched Parser.__apply_discriminator_type,
2024-11-06 12:05:31,712 [INFO] Initializing FastAgency <FastAgency title=FastAgency application> with workflows: <fastagency.runtimes.autogen.autogen.AutoGenWorkflows object at 0xffffafd51810> and UI: <fastagency.ui.console.console.ConsoleUI object at 0xffffa043ccd0>
2024-11-06 12:05:31,712 [INFO] Initialized FastAgency: <FastAgency title=FastAgency application>
╭───────────────────── Importable FastAgency app ──────────────────────╮
│ │
│ from docs.docs_src.user_guide.runtimes.autogen.whatsapp import app │
│ │
╰──────────────────────────────────────────────────────────────────────╯
╭─ AutoGenWorkflows -> User [workflow_started] ────────────────────────────────╮
│ │
│ { │
│ "name": "simple_whatsapp", │
│ "description": "WhatsApp chat", │
│ │
│ "params": {} │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Workflow -> User [text_input] ──────────────────────────────────────────────╮
│ │
│ I can help you with sending a message over whatsapp, what would you │
│ like to send?: │
╰──────────────────────────────────────────────────────────────────────────────╯
╭────── Python package file structure ──────╮
│ │
│ 📁 docs │
│ ├── 🐍 __init__.py │
│ └── 📁 docs_src │
│ ├── 🐍 __init__.py │
│ └── 📁 user_guide │
│ ├── 🐍 __init__.py │
│ └── 📁 runtimes │
│ ├── 🐍 __init__.py │
│ └── 📁 autogen │
│ ├── 🐍 __init__.py │
│ └── 🐍 whatsapp_tool.py │
│ │
╰───────────────────────────────────────────╯
2024-11-06 12:01:55,921 [INFO] Importing autogen.base.py
/home/vscode/.local/lib/python3.10/site-packages/pydantic/_internal/_config.py:341: UserWarning: Valid config keys have changed in V2:
* 'keep_untouched' has been renamed to 'ignored_types'
warnings.warn(message, UserWarning)
2024-11-06 12:01:56,374 [INFO] Patched OpenAPIParser.parse_schema
2024-11-06 12:01:56,374 [INFO] Patched Operation.function_name
2024-11-06 12:01:56,374 [INFO] Patched fastapi_code_generator.__main__.generate_code
2024-11-06 12:01:56,374 [INFO] Patched Parser.__apply_discriminator_type,
2024-11-06 12:01:56,611 [INFO] Initializing FastAgency <FastAgency title=FastAgency application> with workflows: <fastagency.runtimes.autogen.autogen.AutoGenWorkflows object at 0xffff88721840> and UI: <fastagency.ui.console.console.ConsoleUI object at 0xffff89e50760>
2024-11-06 12:01:56,611 [INFO] Initialized FastAgency: <FastAgency title=FastAgency application>
╭──────────────────────── Importable FastAgency app ────────────────────────╮
│ │
│ from docs.docs_src.user_guide.runtimes.autogen.whatsapp_tool import app │
│ │
╰───────────────────────────────────────────────────────────────────────────╯
╭─ AutoGenWorkflows -> User [workflow_started] ────────────────────────────────╮
│ │
│ { │
│ "name": "simple_whatsapp", │
│ "description": "WhatsApp chat", │
│ │
│ "params": {} │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Workflow -> User [text_input] ──────────────────────────────────────────────╮
│ │
│ I can help you with sending a message over whatsapp, what would you │
│ like to send?: │
╰──────────────────────────────────────────────────────────────────────────────╯
In the prompt, type Send "Hi!" to YOUR-NUMBER and press Enter.
This will initiate the task, allowing you to see the real-time conversation between the agents as they collaborate to complete it. Once the task is finished, you’ll see an output similar to the one below.
╭─ User_Agent -> Assistant_Agent [text_message] ───────────────────────────────╮
│ │
│ Send "Hi!" to 123456789 │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Assistant_Agent -> User_Agent [suggested_function_call] ────────────────────╮
│ │
│ { │
│ "function_name": "send_whatsapp_text_message", │
│ "call_id": │
│ "call_NnptdiOOvZNjzHPb7grxwr9d", │
│ "arguments": { │
│ "body": { │
│ │
│ "from": "447860099299", │
│ "to": "123456789", │
│ "messageId": │
│ "test-message-12345", │
│ "content": { │
│ "text": "Hi!" │
│ │
│ }, │
│ "callbackData": "User_Agent" │
│ } │
│ } │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ User_Agent -> Assistant_Agent [function_call_execution] ────────────────────╮
│ │
│ { │
│ "function_name": "send_whatsapp_text_message", │
│ "call_id": │
│ "call_NnptdiOOvZNjzHPb7grxwr9d", │
│ "retval": "{\"to\": │
│ \"123456789\", \"messageCount\": 1, \"messageId\": \"test- │
│ message-12345\", \"status\": {\"groupId\": 1, \"groupName\": │
│ \"PENDING\", \"id\": 7, \"name\": \"PENDING_ENROUTE\", │
│ \"description\": \"Message sent to next instance\"}}\n" │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Assistant_Agent -> User_Agent [text_message] ───────────────────────────────╮
│ │
│ The message "Hi!" has been sent to 123456789. The current status of │
│ the message is "PENDING." │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ User_Agent -> Assistant_Agent [text_message] ───────────────────────────────╮
│ │
│ TERMINATE │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ AutoGenWorkflows -> User [workflow_completed] ──────────────────────────────╮
│ │
│ { │
│ "result": "The message \"Hi!\" was successfully sent to the number │
│ 123456789, and its status is currently \"PENDING.\"" │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯
If you configured your WHATSAPP_API_KEY correctly, you should get a message from your agent to your WhatsApp now.
This example highlights the capabilities of the AutoGen runtime within FastAgency, demonstrating how seamlessly LLM-powered agents can be integrated with WhatsApp for real-time, automated messaging. By using FastAgency, developers can rapidly build interactive, scalable applications that connect with external APIs—such as those for WhatsApp messaging, CRM systems, or custom data services—enabling the retrieval and delivery of dynamic content directly through WhatsApp. This setup empowers users to automate communication workflows, integrate live data, and facilitate on-demand, personalized interactions with end users.