Agent Tools - supercog-ai/community GitHub Wiki
Tools are sets of functions that give your agents the ability to interact with the world and accomplish real tasks.
Connections are sets of functions that operate on authenticated connections to software as a service systems like Salesforce.com.
A tool is defined by:
- It's name and icon
- A set of functions that it explains to the LLM
After you attach a tool to your agent, you can hover over the tool to see the functions that your agent can use:
Using tools
Because of the intelligence of the Large Language Models, you rarely need to tell you agent which function to use. The agent automatically develops a plan to solve your request, and it chooses and executes tool functions automatically.
So if you give your agent the Salesforce tool, and then ask it "how many Opportunities do we have this month?", then the agent will automatically determine that it needs to execute the "SOQL search" function to answer your question:
Getting predictable behaviour
It is best practice to prompt your agent with high level tasks and goals and let it determine how to achieve them. However, in some cases you may experience the agent choosing the wrong function. It is always possible to include a specific instruction like:
please use the "read_file" function in order to...
One thing to note is that the more tools you give your agent, the more likely it is to choose the wrong function for some task. This is pretty much like us humans! If you give me 5 different saws with which to cut some plywood, there's a decent chance that I will pick the wrong one on the first attempt.
So if you are having trouble getting the right behaviour from your agent, it is a good idea to try removing a tool to see if that improves the results.
Connections
When you need access to a system that requires credentials to use look for it in the Connections tab. Below is a sample Connections tab:
If your connection does not yet exist then you can create a new one. Next to the blue New Connection button is a pulldown with a list of connections you can configure. Select the one you want and click the blue button. For example: Choose Salesforce and click the button. A modal window will appear requesting that you provide the credentials.
Some tools which support Oauth will show a Connect button for the oauth flow.
You should name the connection after the purpose of the connected system, like Sales CRM - Salesforce
or JIRA - Engineering.
Environment Variables
Besides creating named credentials, you can also set Environment Variables in your account. Env Vars are "global" to your account, and available to any agent that you run. Some functions require configuration via Env Var, including specialized frontier LLMs.
Note that only the name of the Env Var is disclosed to the Agent, the actual value is only readable by tool functions. This provides a secure way for you to "talk" about secrets with your Agent without actually revealing sensitive data which might get disclosed inadvertently. (In fact some newer LLMs, like Claude will refuse to remember or manipulate anything that looks like a password or API key).
Your agent may request, inline in the chat, for you to provide Env Var values. You can also visit the Settings page and set and edit Env Vars. Note that even though the form for providing the Env Var value appears in the chat window, the value itself is never disclosed to the agent.
Env Vars can also be used with the REST API tool. This allows you to access privileged ad-hoc APIs.
Some standard Env Vars used by Supercog include:
| Env Var | Purpose |
|---|---|
| OPENAI_API_KEY | API key to use OpenAI models |
| CLAUDE_API_KEY | API key to use Anthropic models |
| GROQ_API_KEY | API key to use Groq hosted models, like Llama 3.1 |
| EMAIL_WHITELIST | Comma separated list of email addresses for the Email tool |
Available Tools and Connections
Supercog comes with a large set of available tools and connections, covering a lot of "data processing" problems:
- reading and writing files in different formats
- accessing documents and cloud storage (S3)
- accessing databases and data warehouses
- transforming data with SQL
- gathering information from the internet
- accessing popular SaaS applications like Salesforce and JIRA
- sending and receiving email
Read about data processing as a particular focus area for tools.
If you need a tool that isn't available yet, feel free to file an issue to let us know. We are building new tools all the time.
Accessing new APIs
One effective way to access systems for which there isn't a dedicated tool is to use the REST API tool. This tool allows you to call ANY REST (JSON over HTTP) API.
Using the REST tool, your agent can construct any API call and then process the results. You can even pass API keys or authentication tokens as needed. In fact, when we develop new SaaS app tools, we usually start by prototyping with the REST API tool in order to get started.
Frontier LLMs (GPT4 class) often have existing specific API knowledge in their training. In those cases the REST API tool will often "just work". However if the LLM doesn't know about your API, you can always explain its endpoints, or use the Web Browser tool to lookup the relevant API docs.