Communication Agents
Bring your social platforms into your AG2 workflow with DiscordAgent
, SlackAgent
, and TelegramAgent
.
Available as standalone agents or as tools that you can add to your own agents.
These tools are currently in our experimental
namespace, indicating that we have tested the functionality but their interface may change. Please use them with that in mind and we appreciate any feedback on them.
If you do find any bugs please log an issue in the AG2 repository. If you would like to add more tools or functionality, we would love your contribution.
Installation
Install AG2 with the necessary extra for the platform(s) you need.
Capabilities
The send functionality is consistent across agents/send tools, they take a message and post it to the configured channel/group/bot. If a message is longer than the platforms permitted message length, the tool will split the message into multiple messages.
The common retrieve functionality includes:
- Retrieve the latest X messages from a channel/group/bot.
- Retrieve messages since a given date.
- Retrieve messages since a given message ID.
- Retrieve a message given its ID.
The Telegram retrieve tool also has the ability to retrieve messages using a search string (and this can be done in combination with the retrieval options above).
The agent will automatically determine how to retrieve the messages based on the conversation.
Platform configuration
Each agent/tool is configured for a specific channel/group/bot. This configuration is applied when you create the agent/tool.
Discord, Slack, and Telegram all have their own authentication and channel/group/bot identifiers. See this notebook for more guidance on establishing those authentication details and identifiers.
Using the Agents
The three communication agents have two in-built tools for sending and retrieving messages, respectively. The agents will automatically determine which tool(s) to call based on the conversation (you can influence this by adjusting their system message).
Agent | Send Tool | Retrieve Tool |
---|---|---|
DiscordAgent | DiscordSendTool | DiscordRetrieveTool |
SlackAgent | SlackSendTool | SlackRetrieveTool |
TelegramAgent | TelegramSendTool | TelegramRetrieveTool |
As the agents are based on ConversableAgent
you can use them in any conversation pattern in AG2.
An important component of the new agents (as opposed to just using their tools) is that the platform’s messaging requirements will be appended to their system message.
They cover aspects like maximum message length, preferred format (e.g. Markdown), and provide tips like using emojis.
Agent | System Message guidance |
---|---|
DiscordAgent | 2,000 character limit, Markdown, bold/italic/code, use emojis |
SlackAgent | 40,000 character limit, Markdown, bold/italic/code, emojis, notification formats |
TelegramAgent | 4,096 character limit, HTML, mentions and emojis |
These are enabled by default, but you can turn these off by setting has_writing_instructions
to False
when creating the agent.
Here’s a simple example using the DiscordAgent
where we will use both tools by retrieving the latest message and then sending back a poem about it.
Here’s the message it retrieved and the poem it sent back.
Code examples
See our blog post for a demonstration of using the communication agents.
For supporting guidance on establishing the relevant authentication tokens and IDs, see this notebook.
Using the Tools directly
You can create and add any of the available communication tools to your agents, empowering your agents with communication abilities.
Here’s a simple example using the Slack tools with a ConversableAgent
-based agent to send a weather forecast to a Slack channel.
The main difference between this example and using the SlackAgent
agent is that the agent in this example doesn’t have the Slack-specific system message, including formatting instructions.
Code examples
See this notebook for examples of using all the communication tools, and guidance on establishing the relevant authentication tokens and IDs.
Tool execution
In AG2 the tool execution is typically handled by a separate agent that will follow the agent in the conversation (unless its an agent in a swarm whereby tools are executed automatically). So, you will need to register the tools with another agent for execution.
You will see an example of this is the examples above and linked blog/notebook.