Skip to content

Commit 19da214

Browse files
martyndaviesmartyndavies
committed
add agent specific documentation
1 parent a1e6f76 commit 19da214

8 files changed

+182
-0
lines changed

‎docs/agent/adding-tools.mdx

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Adding new tools
2+
To get the most out Superface, you need to connect it to the various platforms that you want to access data and insights from.
3+
4+
This is done using "Tools" created using the Superface CLI, or they may be provided for you.
5+
6+
Once a tool is created, it must be added to the Agent in order to be used. To do this, click on **Settings** and **Add Comlinks**.
7+
8+
![An empty Add Comlinks view. This is where tools are added to Superface](/img/agent/2-add-new-comlinks.png)
9+
10+
## What are Comlinks?
11+
Superface tools are made up of a set of files called Comlinks. Typically they are composed of three files that are generated by the Superface CLI.
12+
13+
1. A **provider** (`.provider.json`), that outlines the security policy, and additional required parameters for connecting to an external service.
14+
2. A **profile** (`.profile`), which is the overview of expected inputs and outputs required by the external service's API.
15+
3. A **map** (`.map.js`), which is a defined function call that executes the API request and handles the response from the external service.
16+
17+
## Adding tools
18+
To add a tool to Superface, locate the correct files on your local system and drag and drop them onto the browser window to upload them.
19+
20+
Once your tool(s) have uploaded, you will need to configure the security settings and any additional paramters as outlined in the provider file.

‎docs/agent/changing-models.mdx

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Changing models
2+
By default Superface uses the *OpenAI ChatGPT-3.5 Turbo* model, however this may not necessarily be the best model for all the capabilities you want to add with your tools.
3+
4+
You can modify the model that the agent uses by clicking on **Settings > System** and selecting the model you want to run your tools with from the **Foundation model** drop down list.
5+
6+
![The Foundation model list is found on the System settings page](/img/agent/6a-foundation-model-expanded.png)

‎docs/agent/configure-providers.mdx

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Configuring providers
2+
All Superface tools have a *provider* as part of their configuration. The provider is where necessary elements such as API keys, and additional parameters that are needed to connect to an external service are defined.
3+
4+
![A list of Providers in Superface](/img/agent/3-configuring-providers.png)
5+
6+
The providers are listed in alpabetical order of the name of the external service they represent.
7+
8+
A fully configured provider will have a green dot next to it. If it's green, it's good to go.
9+
10+
If there is a red dot next to the name then some additional configuration is needed.
11+
12+
## Setting configurations
13+
To set up configuration options for a provider you can click on the cog icon to see the specific settings required.
14+
15+
For example, here are the configuration parameters required for the Mixpanel provider shown in the image above.
16+
17+
![The Mixpanel provider configuration options](/img/agent/4-mixpanel-provider-config.png)
18+
19+
Typically a provider outlines the security configuration as well as any additional parameters that are required by the third-party API your tool is connecting to. In this case we can see that Mixpanel requires both of these.
20+
21+
To set up your provider, fill out all of the blank fields and click **Save Changes**.
22+
23+
## Provider file example
24+
Below you can see the provider file for Mixpanel. This is where the parameters and security scheme detals you can see on the screen are defined.
25+
26+
```json
27+
{
28+
"name": "mixpanel",
29+
"defaultService": "default",
30+
"parameters": [
31+
{
32+
"name": "project_id",
33+
"description": "The ID of the Mixpanel project"
34+
},
35+
{
36+
"name": "workspace_id",
37+
"description": "The ID of the workspace to query"
38+
}
39+
],
40+
"services": [
41+
{
42+
"baseUrl": "https://eu.mixpanel.com/api/query",
43+
"id": "default"
44+
}
45+
],
46+
"securitySchemes": [
47+
{
48+
"type": "http",
49+
"scheme": "basic",
50+
"id": "ServiceAccount"
51+
}
52+
]
53+
}
54+
```
55+
56+
## Replacing a provider
57+
If you need to replace a provider at any time you can click on the edit icon to upload a new version.
58+
59+
![The Mixpanel provider configuration options](/img/agent/4a-config-replacement.png)
60+
61+
All tools can be updated by replacing the Comlink files at any time.

‎docs/agent/custom-instructions.mdx

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Custom instructions
2+
It is possible to pass your own instructions that will be pre-loaded into the agent every time you use it.
3+
4+
This is useful for setting rules that are specific to you and how you want to use the agent on a day to day basis.
5+
6+
You can set your custom instructions by clicking on **Settings > System** and adding to the *Custom instructions* section.
7+
8+
![The Foundation model list is found on the System settings page](/img/agent/6-foundation-model.png)
9+
10+
## Custom instruction examples
11+
How you set up your instructions is up to you, but we recommend using a list. For example:
12+
13+
```text
14+
- When I ask for the top events from Mixpanel, always format the results in a table with the percentage change in descending order
15+
16+
- When sending an email always set the sender name to Operations Department
17+
18+
- When extracting sentiment from support tickets, only show me the email address of the user and if their sentiment was positive or negative, exclude other information.
19+
```

‎docs/agent/index.mdx

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Superface Agent
2+
The Superface Agent allows you to interact with SaaS platforms via natural language prompts.
3+
4+
![An example prompt asking for Top Events from Mixpanel](/img/agent/prompt-top-events-example.png)
5+

‎docs/agent/interface.mdx

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Using the agent interface
2+
After logging in to Superface, you will see a fresh agent interface ready to get started with your prompts.
3+
4+
![The initial Superface interface after log in](/img/agent/1-initial-interface.png)
5+
6+
If it's your first time using the agent, there probably won't be any tools set up yet. You can check this by asking `What can you do?`.
7+
8+
:::tip
9+
In Superface term, "Tools" are what connects the agent to your external services.
10+
:::
11+
12+
To get started, you will need to add some tools. You can do this by clicking on **Settings**.
13+
14+
## Task history
15+
To access previous tasks, click on **History**. A drawer of your previous tasks (and any scheduled tasks) will appear on the left of the screen.
16+
17+
![The task history drawer in the main agent interface](/img/agent/task-history.png)

‎docs/agent/scheduling-tasks.mdx

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Scheduling tasks
2+
Once you have completed any task in the Superface agent it is possible to set it up on a recurrent schedule.
3+
4+
To do this in the main agent interface, click on **Schedules** next to the title of your task at the top of the screen.
5+
6+
![Tasks can be set to run on schedules using the Schedules feature](/img/agent/7-schedules.png)
7+
8+
Next, you will see the schedule configuration screen for this task.
9+
10+
![The schedule configuration screen for a task](/img/agent/7a-schedule-overview.png)
11+
12+
## Setting a schedule
13+
To add a schedule, select a time period from the drop down list and click on **Add Schedule**
14+
15+
![The schedule selection drop down](/img/agent/7b-schedule-dropdown.png)
16+
17+
The schedule options currently available are:
18+
- Every minute
19+
- Every hour
20+
- Daily at 6am
21+
- Weekly on Monday
22+
- Custom
23+
24+
## Define a custom schedule
25+
The custom schedule option is the most flexible because it allows you to define the exact time and frequency you want your task to run.
26+
27+
Custom schedules are defined using CRON formatting.
28+
29+
![Custom scheduling](/img/agent/7c-custom-schedule.png)
30+
31+
In the above example the custom schedule is set up to run at 0800 every Monday.
32+
33+
From left to right the numbers (or asterisks) used represent, the minute, the hour, the day of the month, the month, the day of the week.
34+
35+
We have included a visual representation of the CRON you set so you can make sure you get it right.
36+
37+
## Replays of scheduled tasks
38+
Every time your task is triggered, a *run* will be added to the list on the schedule page.
39+
40+
The output from the task will be added to your Chat History in the main agent interface.

‎docs/agent/updating-tools.mdx

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Updating tools
2+
You can update the tools you have available in Superface at any time by clicking on the edit icon.
3+
4+
![A list of tools in the Superface agent that are available to use](/img/agent/5-updating-tools.png)
5+
6+
This will take you to the **Add Comlinks** section where you can re-upload new files for the tool you want to make changes to.
7+
8+
![The Upload Comlinks screen is where you can edit tools by uploading new files](/img/agent/2-add-new-comlinks.png).
9+
10+
Drag and drop your updated/edited files and they will overwrite the previous versions if the naming convention used has not changed.
11+
12+
:::tip
13+
You only need to upload the files that you have made changes to. If nothing has changed in the profile, or provider files, you don't need to add these because they already exist in Superface.
14+
:::

0 commit comments

Comments
 (0)