@superagnt/superagnt 2.0.6 → 2.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -3
- package/index.js +10 -3
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
- package/skills/superagnt-automations/SKILL.md +18 -3
- package/skills/superagnt-canvas/SKILL.md +21 -3
- package/skills/superagnt-data-pipelines/SKILL.md +24 -7
- package/skills/superagnt-data-sources/SKILL.md +63 -20
- package/skills/superagnt-lead-generation/SKILL.md +21 -0
- package/skills/superagnt-setup/SKILL.md +72 -23
- package/skills/superagnt-task-agents/SKILL.md +57 -14
- package/skills/superagnt-workspace-db/SKILL.md +18 -2
package/README.md
CHANGED
|
@@ -20,7 +20,7 @@ openclaw superagnt connect
|
|
|
20
20
|
OAuth in the browser; the consent screen doubles as signup if you don't have
|
|
21
21
|
an account yet. After login the workspace tool surface is available in every
|
|
22
22
|
OpenClaw session. Which tool families are active is controlled by the user:
|
|
23
|
-
they are enabled explicitly, per workspace, in the superagnt
|
|
23
|
+
they are enabled explicitly, per workspace, in the superagnt app — the
|
|
24
24
|
plugin itself never turns anything on.
|
|
25
25
|
|
|
26
26
|
<details>
|
|
@@ -41,7 +41,7 @@ openclaw mcp login superagnt
|
|
|
41
41
|
|
|
42
42
|
One MCP connection to the user's own superagnt workspace. The tool families
|
|
43
43
|
below exist on the platform; each one is active only when the user has enabled
|
|
44
|
-
it for their workspace in the
|
|
44
|
+
it for their workspace in the superagnt app:
|
|
45
45
|
|
|
46
46
|
- **Data sources** — X, TikTok, YouTube, Instagram, Reddit, LinkedIn, and web
|
|
47
47
|
scraping, as structured JSON tools
|
|
@@ -82,5 +82,5 @@ openclaw superagnt doctor # connectivity + auth checks
|
|
|
82
82
|
## Links
|
|
83
83
|
|
|
84
84
|
- Product: https://superagnt.com
|
|
85
|
-
-
|
|
85
|
+
- App: https://app.superagnt.com/dashboard
|
|
86
86
|
- Docs: https://superagnt.com/docs
|
package/index.js
CHANGED
|
@@ -50,7 +50,12 @@ function registerAgntCli(api) {
|
|
|
50
50
|
.command('connect')
|
|
51
51
|
.description('Wire up the live MCP tool surface: save the server config, then run OAuth login')
|
|
52
52
|
.action(async () => {
|
|
53
|
-
|
|
53
|
+
// SUPERAGNT_MCP_URL points the saved server at a QA/staging MCP origin;
|
|
54
|
+
// customers never set it. The saved config entry overrides the
|
|
55
|
+
// manifest's prod default by name, so this is the one override that
|
|
56
|
+
// reaches OpenClaw (it does not expand env vars in plugin manifests).
|
|
57
|
+
const MCP_URL = process.env.SUPERAGNT_MCP_URL || 'https://mcp.superagnt.com/mcp'
|
|
58
|
+
const MCP_ARGS = ['--url', MCP_URL, '--transport', 'streamable-http', '--auth', 'oauth']
|
|
54
59
|
const run = (args, quiet) => _spawnSync('openclaw', args, { stdio: quiet ? 'ignore' : 'inherit', shell: false })
|
|
55
60
|
const probe = run(['mcp', 'show', 'superagnt'], true)
|
|
56
61
|
if (probe.error) {
|
|
@@ -101,9 +106,11 @@ function registerAgntCli(api) {
|
|
|
101
106
|
.description('Check connectivity and validate API key against api.superagnt.com')
|
|
102
107
|
.action(async () => {
|
|
103
108
|
console.log('\nsuperagnt doctor\n')
|
|
109
|
+
// SUPERAGNT_API_URL overrides the API origin (QA/staging); customers never set it.
|
|
110
|
+
const API_ORIGIN = process.env.SUPERAGNT_API_URL || 'https://api.superagnt.com'
|
|
104
111
|
|
|
105
112
|
try {
|
|
106
|
-
const publicRes = await fetch('
|
|
113
|
+
const publicRes = await fetch(API_ORIGIN + '/v1/platforms')
|
|
107
114
|
console.log(' Public API: ' + (publicRes.ok ? 'OK (' + publicRes.status + ')' : 'HTTP ' + publicRes.status))
|
|
108
115
|
} catch (err) {
|
|
109
116
|
const msg = err instanceof Error ? err.message : String(err)
|
|
@@ -120,7 +127,7 @@ function registerAgntCli(api) {
|
|
|
120
127
|
}
|
|
121
128
|
|
|
122
129
|
try {
|
|
123
|
-
const res = await fetch('
|
|
130
|
+
const res = await fetch(API_ORIGIN + '/v1/platforms', {
|
|
124
131
|
headers: { Authorization: 'Bearer ' + key },
|
|
125
132
|
})
|
|
126
133
|
const text = await res.text()
|
package/openclaw.plugin.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"id": "superagnt",
|
|
3
3
|
"name": "superagnt_",
|
|
4
4
|
"description": "The agent value layer: one MCP connection = every data source (X, TikTok, YouTube, Instagram, Reddit, LinkedIn, web), people + company enrichment, a real workspace Postgres, schedules, webhooks and shareable canvases — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.",
|
|
5
|
-
"version": "2.0.
|
|
5
|
+
"version": "2.0.7",
|
|
6
6
|
"mcpServers": {
|
|
7
7
|
"superagnt": {
|
|
8
8
|
"url": "https://mcp.superagnt.com/mcp",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@superagnt/superagnt",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.7",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "The agent value layer: one MCP connection = every data source (X, TikTok, YouTube, Instagram, Reddit, LinkedIn, web), people + company enrichment, a real workspace Postgres, schedules, webhooks and shareable canvases — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.",
|
|
6
6
|
"main": "index.js",
|
|
@@ -28,9 +28,11 @@ system, then read deliveries with `receive_recent` when the session runs.
|
|
|
28
28
|
`agnt_webhooks_create_endpoint`, `create_outbound`, `list_endpoints`,
|
|
29
29
|
`link_agent`, `link_data_job`, `set_active`, `rotate_secret`,
|
|
30
30
|
`list_deliveries`, `get_delivery`. Enable with
|
|
31
|
-
`agnt_tools_enable(['webhooks'])
|
|
32
|
-
|
|
33
|
-
|
|
31
|
+
`agnt_tools_enable({ families: ['webhooks'] })`; it is on every plan. Plans
|
|
32
|
+
cap inbound events per billing period, and deliveries past the cap are
|
|
33
|
+
refused to the sender. A `requires_upgrade` result (a plan limit, or a trial
|
|
34
|
+
or plan that ended) carries a `confirm_url` for the human. Hand the link over
|
|
35
|
+
and wait; never treat it as an error.
|
|
34
36
|
|
|
35
37
|
Three patterns, in the order clients usually need them:
|
|
36
38
|
|
|
@@ -54,6 +56,19 @@ Three patterns, in the order clients usually need them:
|
|
|
54
56
|
`agnt_webhooks_list_deliveries` / `get_delivery` show what actually arrived
|
|
55
57
|
and how it was acked. Check there before assuming the upstream never fired.
|
|
56
58
|
|
|
59
|
+
## Tool names on grouped servers
|
|
60
|
+
|
|
61
|
+
This skill writes flat (per-operation) tool names. New superagnt servers list
|
|
62
|
+
grouped tools instead: one tool per resource with an `action` argument. Flat
|
|
63
|
+
names still resolve there but are not listed, so call the grouped form:
|
|
64
|
+
|
|
65
|
+
- `agnt_webhooks_inbound_url` / `agnt_webhooks_receive_recent` / `agnt_webhooks_list_endpoints` / `agnt_webhooks_list_deliveries` / `agnt_webhooks_get_delivery` → `agnt_webhooks_read`, action `inbound_url` / `receive_recent` / `list_endpoints` / `list_deliveries` / `get_delivery`
|
|
66
|
+
- `agnt_webhooks_send` / `agnt_webhooks_create_endpoint` / `agnt_webhooks_create_outbound` / `agnt_webhooks_link_agent` / `agnt_webhooks_link_data_job` → `agnt_webhooks_write`, action `send` / `create_endpoint` / `create_outbound` / `link_agent` / `link_data_job`
|
|
67
|
+
- `agnt_webhooks_set_active` / `agnt_webhooks_rotate_secret` → `agnt_webhooks_admin`, action `set_active` / `rotate_secret`
|
|
68
|
+
|
|
69
|
+
`agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
|
|
70
|
+
server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
|
|
71
|
+
|
|
57
72
|
## More
|
|
58
73
|
|
|
59
74
|
- Schedules (cron) moved to the task-agents skill — see its `schedules.md`.
|
|
@@ -32,9 +32,27 @@ opens for anyone — no account needed on the viewer's side.
|
|
|
32
32
|
accent.
|
|
33
33
|
- Time widgets need `event_at`/`created_at` timestamptz columns; funnels and
|
|
34
34
|
kanbans bind to stable status strings — schema rules in workspace-db.
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
35
|
+
- The canvas tools are missing only when neither the flat
|
|
36
|
+
`agnt_canvas_put_widget` nor the grouped `agnt_canvas_write` (action
|
|
37
|
+
`put_widget`) is listed. Then enable the family:
|
|
38
|
+
`agnt_tools_enable({ families: ['canvas'] })`, or on a grouped server
|
|
39
|
+
`agnt_tools_write` with `action: "enable"` and the same `families`.
|
|
40
|
+
Canvases are on every plan and count against no limit; what the plan caps
|
|
41
|
+
is the workspace database behind them (tables, rows, storage).
|
|
42
|
+
|
|
43
|
+
## Tool names on grouped servers
|
|
44
|
+
|
|
45
|
+
New servers list one tool per family with an `action` argument. The flat
|
|
46
|
+
names above map to:
|
|
47
|
+
|
|
48
|
+
| Flat | Grouped tool, action |
|
|
49
|
+
|---|---|
|
|
50
|
+
| `agnt_canvas_get`, `_introspect_schema`, `_preview_query`, `_chart_render`, `_snapshot`, `_share_list` | `agnt_canvas_read`: `get`, `introspect_schema`, `preview_query`, `chart_render`, `snapshot`, `share_list` |
|
|
51
|
+
| `agnt_canvas_put_widget`, `_update_widget`, `_set_layout`, `_share_create` | `agnt_canvas_write`: `put_widget`, `update_widget`, `set_layout`, `share_create` |
|
|
52
|
+
| `agnt_canvas_remove_widget`, `_share_revoke` | `agnt_canvas_remove`: `remove_widget`, `share_revoke` |
|
|
53
|
+
|
|
54
|
+
Flat names still resolve on a grouped server but are not listed, so most
|
|
55
|
+
clients will not let you call them: use the grouped tool.
|
|
38
56
|
|
|
39
57
|
## More
|
|
40
58
|
|
|
@@ -26,19 +26,22 @@ you fetch).
|
|
|
26
26
|
|
|
27
27
|
## Running the job
|
|
28
28
|
|
|
29
|
-
1. The job itself (the per-item recipe) is created once
|
|
30
|
-
data-pipelines page or the `data-jobs` management
|
|
31
|
-
(`agnt_data_job_create` / `list` / `read` / `inspect_run`)
|
|
32
|
-
|
|
33
|
-
`agnt_tools_enable(['data-jobs'])
|
|
29
|
+
1. The job itself (the per-item recipe) is created once, via the
|
|
30
|
+
data-pipelines page in the superagnt app or the `data-jobs` management
|
|
31
|
+
family (`agnt_data_job_create` / `list` / `read` / `inspect_run`), on
|
|
32
|
+
every plan:
|
|
33
|
+
`agnt_tools_enable({ families: ['data-jobs'] })`. Plans cap active
|
|
34
|
+
pipelines and items per month; on `requires_upgrade` hand the
|
|
34
35
|
`confirm_url` to the human and wait.
|
|
35
36
|
2. `agnt_data_job_submit` (always available) pushes 1–1000 payloads onto an
|
|
36
|
-
existing job
|
|
37
|
+
existing job, each payload a row pointer like `{ "row_id": ... }`. A batch
|
|
38
|
+
that would cross the monthly item cap is refused whole, and the refusal
|
|
39
|
+
says how many items are left.
|
|
37
40
|
3. **Results must be written back to a workspace table.** Make sure the
|
|
38
41
|
job's recipe upserts each item's output into a table with a `status`
|
|
39
42
|
column — that table is the ONLY place this session, later sessions, task
|
|
40
43
|
agents, and canvases can read outcomes from. A recipe that merely returns
|
|
41
|
-
its result stores it where only the
|
|
44
|
+
its result stores it where only the superagnt app can show it.
|
|
42
45
|
4. Report progress from the table, not memory: counts by status via
|
|
43
46
|
`agnt_db_select`. Failed items keep their error (`agnt_data_job_inspect_run`
|
|
44
47
|
shows failures and sandbox logs); fix the cause and resubmit the failures,
|
|
@@ -52,6 +55,20 @@ in-session first to prove the step, then scale. Webhook-fed jobs (one
|
|
|
52
55
|
delivery = one item, automations skill) inherit the same rule: know the
|
|
53
56
|
expected volume before binding.
|
|
54
57
|
|
|
58
|
+
## Tool names on grouped servers
|
|
59
|
+
|
|
60
|
+
This skill writes flat (per-operation) tool names. New superagnt servers list
|
|
61
|
+
grouped tools instead: one tool per resource with an `action` argument. Flat
|
|
62
|
+
names still resolve there but are not listed, so call the grouped form:
|
|
63
|
+
|
|
64
|
+
- `agnt_data_job_create` / `agnt_data_job_submit` → `agnt_data_job_write`, action `create` / `submit`
|
|
65
|
+
- `agnt_data_job_list` / `agnt_data_job_read` / `agnt_data_job_inspect_run` → `agnt_data_job_lookup`, action `list` / `read` / `inspect_run`
|
|
66
|
+
- `agnt_db_load_csv` → `agnt_db_write`, action `load_csv`
|
|
67
|
+
- `agnt_db_select` → `agnt_db_read`, action `select`
|
|
68
|
+
|
|
69
|
+
`agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
|
|
70
|
+
server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
|
|
71
|
+
|
|
55
72
|
## More
|
|
56
73
|
|
|
57
74
|
- Table design for pipelines: the workspace-db skill
|
|
@@ -1,59 +1,102 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superagnt-data-sources
|
|
3
|
-
description: This skill should be used when the agent needs external data: searching or scraping X/Twitter, TikTok, YouTube, Instagram, Reddit, Facebook, or LinkedIn; running web or SERP searches; crawling pages; enriching a person or company; or finding and verifying emails. Also whenever normal fetching is blocked
|
|
3
|
+
description: This skill should be used when the agent needs external data: searching or scraping X/Twitter, TikTok, YouTube, Instagram, Reddit, Facebook, or LinkedIn; running web or SERP searches; crawling pages; enriching a person or company; or finding and verifying emails. Also whenever normal fetching is blocked: bot detection, login walls, crawl prevention. Covers the superagnt data tools that return structured results in one call, instead of hand-rolled scraping or headless browsing.
|
|
4
4
|
version: 0.2.0
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# External data through superagnt
|
|
8
8
|
|
|
9
9
|
Query, don't scrape. Every source below is one authenticated MCP call
|
|
10
|
-
returning structured
|
|
11
|
-
per-vendor API keys. Calls spend workspace data credits
|
|
12
|
-
a
|
|
10
|
+
returning structured results: no headless browser, no HTML parsing, no
|
|
11
|
+
per-vendor API keys. Calls spend workspace data credits: the no-card trial
|
|
12
|
+
starts with a one-time data grant, each builder plan includes a monthly
|
|
13
|
+
amount, and `agnt_credits_balance` shows what's left.
|
|
13
14
|
|
|
14
15
|
**When you're blocked, this is the unblock.** Social platforms and many sites
|
|
15
16
|
stop direct fetching cold — bot detection, login walls, rate limits,
|
|
16
|
-
JS-rendered pages. The data tools return the same content as structured
|
|
17
|
+
JS-rendered pages. The data tools return the same content as structured data
|
|
17
18
|
anyway: an X profile behind a login wall is one `data_x_*` call, a
|
|
18
19
|
JS-rendered page is one `web` crawl call. Reach here the moment a fetch
|
|
19
20
|
returns a challenge page instead of burning turns fighting it.
|
|
20
21
|
|
|
22
|
+
**Codex:** superagnt's tools can take a few seconds to appear in a new chat.
|
|
23
|
+
If none are listed, wait about 10 seconds and check again before concluding
|
|
24
|
+
superagnt isn't connected or falling back to web search.
|
|
25
|
+
|
|
26
|
+
## Two tool surfaces
|
|
27
|
+
|
|
28
|
+
A server lists the data tools one of two ways, fixed when it was created:
|
|
29
|
+
|
|
30
|
+
- **Grouped** (every new server): one tool per source and resource with an
|
|
31
|
+
`action` argument, e.g. `data_x_users` action `tweets`,
|
|
32
|
+
`data_linkedin_posts` action `reactions`, `data_agnt_people` action
|
|
33
|
+
`enrich`. Every curated data source is always on: nothing to enable.
|
|
34
|
+
Results come back as a compact markdown table (lists) or `key: value` lines
|
|
35
|
+
(one item), with a footer naming the next-page parameter and the cost. The
|
|
36
|
+
web tools (`data_web_*`) and a few single tools stay listed under their own
|
|
37
|
+
names and answer in their usual JSON.
|
|
38
|
+
Pass `response_format: "json"` for the same view as JSON with every view
|
|
39
|
+
field, `"raw"` for the full upstream payload, `response_fields` to pick
|
|
40
|
+
fields, and `response_limit` to cap rows.
|
|
41
|
+
- **Flat** (servers created before grouped tools shipped): one tool per
|
|
42
|
+
operation, e.g. `data_x_user_s_tweets_get_user_tweets`,
|
|
43
|
+
`data_agnt_people_enrich`. Results are the raw JSON payload. Curated
|
|
44
|
+
families other than the first-party `data_agnt_*` tools start off and need
|
|
45
|
+
enabling.
|
|
46
|
+
|
|
47
|
+
Flat names still resolve on a grouped server, but they are not listed, so
|
|
48
|
+
most clients will not let you call them: use the grouped tool.
|
|
49
|
+
|
|
21
50
|
## Picking the tool
|
|
22
51
|
|
|
23
52
|
1. `agnt_tools_list_enabled` — what this workspace already serves.
|
|
24
53
|
2. `agnt_tools_search` with a plain-language query ("tiktok video comments",
|
|
25
54
|
"company headcount", "serp") — finds the tool whether or not its family is
|
|
26
|
-
enabled yet.
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
55
|
+
enabled yet. On a grouped server each hit carries `grouped_name` and
|
|
56
|
+
`action`: call that. On a flat server, if the family is disabled, enable
|
|
57
|
+
it: `agnt_tools_enable` with the family id from the search result. Every
|
|
58
|
+
family enables instantly.
|
|
59
|
+
3. On the trial or a builder plan, when the data credits run out a data
|
|
60
|
+
call returns `requires_upgrade` with a `confirm_url` for the human
|
|
61
|
+
instead of data; never treat that as an error, hand the link over and
|
|
62
|
+
wait. Everything that is not a data call keeps working. On other plans
|
|
63
|
+
it is a credit error: the human tops up in the superagnt app.
|
|
30
64
|
|
|
31
65
|
## The surfaces
|
|
32
66
|
|
|
33
67
|
- **Social**: `data_x_*`, `data_tiktok_*`, `data_youtube_*`,
|
|
34
|
-
`data_instagram_*`, `data_reddit_*`, `data_facebook_*`, `data_linkedin_
|
|
35
|
-
search, profiles, posts, comments, transcripts per platform.
|
|
36
|
-
|
|
37
|
-
`
|
|
38
|
-
`
|
|
39
|
-
|
|
40
|
-
- **Web**:
|
|
41
|
-
aren't behind a social platform.
|
|
68
|
+
`data_instagram_*`, `data_reddit_*`, `data_facebook_*`, `data_linkedin_*`:
|
|
69
|
+
search, profiles, posts, comments, transcripts per platform. Grouped tools
|
|
70
|
+
are named per resource (`data_x_users`, `data_x_posts`,
|
|
71
|
+
`data_linkedin_profiles`, `data_reddit_subreddits`, `data_youtube_videos`,
|
|
72
|
+
`data_tiktok_read`, ...).
|
|
73
|
+
- **People + companies (first-party, always on)**: the table below.
|
|
74
|
+
- **Web**: `data_web_search`, `data_web_scrape`, `data_web_map`: search,
|
|
75
|
+
scrape and crawl pages that aren't behind a social platform. Same names on
|
|
76
|
+
both surfaces.
|
|
77
|
+
|
|
78
|
+
| Flat | Grouped |
|
|
79
|
+
|---|---|
|
|
80
|
+
| `data_agnt_people_search` / `_enrich` / `_bulk_enrich` | `data_agnt_people` action `search` / `enrich` / `bulk_enrich` |
|
|
81
|
+
| `data_agnt_companies_search` / `_discover` / `_enrich` / `_bulk_enrich` / `_intelligence` | `data_agnt_companies` action `search` / `discover` / `enrich` / `bulk_enrich` / `intelligence` |
|
|
82
|
+
| `data_agnt_people_email_finder` / `_email_verifier` | `data_agnt_contacts` action `find_email` / `verify_email` |
|
|
83
|
+
| `data_agnt_companies_domain_emails` | `data_agnt_contacts` action `domain_emails` |
|
|
84
|
+
| `data_agnt_people_find_mobile` | same name on both |
|
|
42
85
|
|
|
43
86
|
## Rules
|
|
44
87
|
|
|
45
88
|
- Prefer one search call with good parameters over many broad ones — each
|
|
46
89
|
call is metered, and tight queries return better data anyway.
|
|
47
90
|
- Batch enrichment goes through `data_agnt_people_bulk_enrich` /
|
|
48
|
-
`data_agnt_companies_bulk_enrich
|
|
49
|
-
data-pipelines skill).
|
|
91
|
+
`data_agnt_companies_bulk_enrich` (grouped: action `bulk_enrich`), or a
|
|
92
|
+
data job for large sets (see the data-pipelines skill).
|
|
50
93
|
- Results worth keeping belong in the workspace database (see the
|
|
51
94
|
workspace-db skill), not in chat scrollback.
|
|
52
95
|
|
|
53
96
|
## More
|
|
54
97
|
|
|
55
98
|
- Every source, with live tool lists: `agnt_platform_map`, or
|
|
56
|
-
https://superagnt.com
|
|
99
|
+
https://superagnt.com
|
|
57
100
|
- Packaged research workflows: https://superagnt.com/skills
|
|
58
101
|
|
|
59
102
|
<!-- skill_id: data-sources · source: https://github.com/superagnt/plugins -->
|
|
@@ -10,6 +10,10 @@ The workflow: pin the ICP → discover companies → find the people → verify
|
|
|
10
10
|
emails → score → store → draft. Everything lands in the workspace database so
|
|
11
11
|
runs compound instead of starting over.
|
|
12
12
|
|
|
13
|
+
**Codex:** superagnt's tools can take a few seconds to appear in a new chat.
|
|
14
|
+
If none are listed, wait about 10 seconds and check again before concluding
|
|
15
|
+
superagnt isn't connected or falling back to web search.
|
|
16
|
+
|
|
13
17
|
## Procedure
|
|
14
18
|
|
|
15
19
|
1. **Pin the ICP once.** Ask the user for company filters (size, industry,
|
|
@@ -42,6 +46,23 @@ runs compound instead of starting over.
|
|
|
42
46
|
- Large lists (500+): move enrichment to a data job (data-pipelines skill)
|
|
43
47
|
instead of looping calls in-session.
|
|
44
48
|
|
|
49
|
+
## Tool names on grouped servers
|
|
50
|
+
|
|
51
|
+
This skill writes flat (per-operation) tool names. New superagnt servers list
|
|
52
|
+
grouped tools instead: one tool per resource with an `action` argument. Flat
|
|
53
|
+
names still resolve there but are not listed, so call the grouped form:
|
|
54
|
+
|
|
55
|
+
- `data_agnt_companies_search` / `data_agnt_companies_discover` / `data_agnt_companies_enrich` → `data_agnt_companies`, action `search` / `discover` / `enrich`
|
|
56
|
+
- `data_agnt_people_search` / `data_agnt_people_enrich` → `data_agnt_people`, action `search` / `enrich`
|
|
57
|
+
- `data_agnt_people_email_finder` / `data_agnt_people_email_verifier` → `data_agnt_contacts`, action `find_email` / `verify_email`
|
|
58
|
+
- `agnt_db_insert` / `agnt_db_upsert` → `agnt_db_write`, action `insert` / `upsert`
|
|
59
|
+
- `agnt_db_select` → `agnt_db_read`, action `select`
|
|
60
|
+
|
|
61
|
+
`agnt_tools_search` and `agnt_tools_list_enabled` keep their names. Grouped
|
|
62
|
+
data calls return a compact markdown view: pass `response_format: "json"` for
|
|
63
|
+
every view field, or `"raw"` for the full payload, when a step needs a field
|
|
64
|
+
the table leaves out.
|
|
65
|
+
|
|
45
66
|
## More
|
|
46
67
|
|
|
47
68
|
- A standing weekly refresh belongs on a task agent (task-agents skill), not
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superagnt-setup
|
|
3
|
-
description: This skill should be used when a superagnt MCP call fails (401/403, tool not found, missing connection, credit or
|
|
3
|
+
description: This skill should be used when a superagnt MCP call fails (401/403, tool not found, missing connection, credit, plan limit or trial errors), when connecting or reconnecting the superagnt server, right after a fresh connection (run onboarding first), or when the user asks "what can superagnt do", about pricing or trials, or how to add tools or skills. Covers agnt_onboarding, agnt_platform_map, agnt_tools_search/enable, and the human-confirmed upgrade flow. Money never moves without a human tap on a confirmation link.
|
|
4
4
|
version: 0.2.0
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -11,42 +11,91 @@ version: 0.2.0
|
|
|
11
11
|
The live setup doc handles every client:
|
|
12
12
|
`https://superagnt.com/agent-setup/prompt.md` — fetch and follow it. The
|
|
13
13
|
endpoint is `https://mcp.superagnt.com/mcp`, OAuth-first (the consent screen
|
|
14
|
-
doubles as signup).
|
|
15
|
-
|
|
14
|
+
doubles as signup). On Claude the server is a claude.ai connector, not part of
|
|
15
|
+
the plugin: give the user https://claude.ai/customize/connectors/yours?modal=add-custom-connector&connectorName=superagnt&connectorUrl=https%3A%2F%2Fmcp.superagnt.com%2Fmcp&open_in_browser=1
|
|
16
|
+
(claude.ai's Add custom connector dialog, prefilled) and they click Add. It
|
|
17
|
+
opens in the browser, and the Claude desktop app only loads connectors when it
|
|
18
|
+
starts: in the desktop app, tell them to refresh it with Cmd+R (Ctrl+R on
|
|
19
|
+
Windows) or quit and reopen it once they've approved. Tokens, when a client needs one, are revealed on the MCP page in the superagnt app —
|
|
20
|
+
never invent or reuse one.
|
|
21
|
+
|
|
22
|
+
**Codex: the tools may not be loaded yet.** Codex starts the first turn of a
|
|
23
|
+
new chat before its MCP servers finish connecting, so superagnt's tools can be
|
|
24
|
+
missing for the first few seconds. If you see none (in Codex's code mode,
|
|
25
|
+
nothing named `mcp__superagnt__*` in `ALL_TOOLS`), wait about 10 seconds and
|
|
26
|
+
check again before telling the user superagnt isn't connected or falling back
|
|
27
|
+
to web search. `codex mcp list` showing `superagnt` enabled, with an Auth
|
|
28
|
+
column that doesn't read "Not logged in", means it is connected; "Not logged
|
|
29
|
+
in" means the sign-in never finished (see 401 below).
|
|
16
30
|
|
|
17
31
|
## First call on a fresh connection: `agnt_onboarding`
|
|
18
32
|
|
|
19
|
-
Once tools respond, call `agnt_onboarding` before anything else
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
33
|
+
Once tools respond, call `agnt_onboarding` before anything else, with
|
|
34
|
+
`client` (which client this is) and nothing else. It needs nothing from the
|
|
35
|
+
user, so don't ask them questions for it. It returns the full platform brief
|
|
36
|
+
(every surface, what it's for, live links) and, when the user started from a
|
|
37
|
+
skill on superagnt.com, that skill and its first-run prompt in
|
|
38
|
+
`skill_setups`. Then:
|
|
24
39
|
|
|
25
40
|
- Save what's relevant to this user in your memory (if this client has one),
|
|
26
41
|
so later sessions skip rediscovery.
|
|
27
|
-
-
|
|
28
|
-
|
|
42
|
+
- If `skill_setups` names a skill, offer its first-run prompt. Otherwise give
|
|
43
|
+
the user a short brief of the 3–5 most useful use cases, not the whole
|
|
44
|
+
catalog.
|
|
45
|
+
|
|
46
|
+
For a raw capability map any time later (always current):
|
|
47
|
+
`agnt_platform_map`.
|
|
48
|
+
|
|
49
|
+
## Tool names: flat and grouped servers
|
|
50
|
+
|
|
51
|
+
A server lists its tools one of two ways, fixed when it was created. New
|
|
52
|
+
servers (including every new workspace's default server) are **grouped**:
|
|
53
|
+
one tool per family and risk level with an `action` argument, e.g.
|
|
54
|
+
`agnt_db_write` with `action: "insert"`, `agnt_agents_write` with
|
|
55
|
+
`action: "create"`, `data_linkedin_posts` with `action: "reactions"`. Servers
|
|
56
|
+
created before grouped tools shipped are **flat**: one tool per operation (`agnt_db_insert`, `agnt_agents_create`,
|
|
57
|
+
`data_linkedin_get_post_reactions`). These skills write flat names; on a
|
|
58
|
+
grouped server call the grouped tool whose description lists that name as an
|
|
59
|
+
action (each action line reads `- insert (agnt_db_insert): ...`). Flat names
|
|
60
|
+
still resolve server-side there, but they are not listed, so most clients
|
|
61
|
+
will not let you call them.
|
|
29
62
|
|
|
30
|
-
|
|
31
|
-
|
|
63
|
+
On grouped servers the `agnt_email_*` tools are
|
|
64
|
+
`agnt_inbox_automation_read` / `_write` / `_delete`, and `data_*` results come
|
|
65
|
+
back as a compact markdown view. Pass `response_format: "json"` for every
|
|
66
|
+
view field as JSON, or `"raw"` for the full upstream payload, when a step
|
|
67
|
+
needs a field the table leaves out.
|
|
32
68
|
|
|
33
69
|
## Error triage
|
|
34
70
|
|
|
35
71
|
- **401 / auth expired**: re-run the client's login step
|
|
36
|
-
(`openclaw mcp login superagnt` or equivalent).
|
|
37
|
-
the user
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
72
|
+
(`openclaw mcp login superagnt`, `codex mcp login superagnt` or equivalent).
|
|
73
|
+
For a Claude connector, the user reconnects superagnt in claude.ai under
|
|
74
|
+
Customize, Connectors. If the client is token-based, the user re-reveals
|
|
75
|
+
the token in the superagnt app.
|
|
76
|
+
- **Tool not found**: first check which surface this server lists (see
|
|
77
|
+
"Tool names" above). On a grouped server the operation usually lives inside
|
|
78
|
+
a grouped tool: look for the tool whose description lists it as an action,
|
|
79
|
+
or run `agnt_tools_search`, whose hits carry `grouped_name` and `action`.
|
|
80
|
+
Only a family missing under both names is off: enable it with
|
|
81
|
+
`agnt_tools_enable` (grouped: `agnt_tools_write` with `action: "enable"`);
|
|
82
|
+
every family enables instantly on every plan. Data sources are always on
|
|
83
|
+
for a grouped server, so never enable `data:*` there. After enabling, some
|
|
84
|
+
clients only pick up new tools on reconnect/restart; say so instead of
|
|
85
|
+
calling enable again.
|
|
86
|
+
- **`requires_upgrade` with a `confirm_url`**: not an error, and the call did
|
|
87
|
+
not run. The organization hit a plan limit, spent its included or trial
|
|
88
|
+
data credits, or its trial or plan ended; `reason` says which, and the
|
|
89
|
+
result names the next plan and what it unlocks. Give the user the link,
|
|
90
|
+
they review the plan in the browser, then re-run the call. `rate_limited`
|
|
91
|
+
only means wait `retry_after_seconds`. Money moves only on that page, never
|
|
92
|
+
from a tool call.
|
|
46
93
|
- **`requires_connection`**: the tool needs the user's own account
|
|
47
94
|
(a vendor integration). The result carries a connect link — hand it over.
|
|
48
95
|
- **Credit errors**: `agnt_credits_balance` for the number;
|
|
49
|
-
`agnt_usage_recent` for where it went. Top-ups
|
|
96
|
+
`agnt_usage_recent` for where it went. Top-ups happen in the superagnt
|
|
97
|
+
app. AI credits (what running agents spend) are topped up there on the
|
|
98
|
+
builder plans and during the trial; those plans include data credits only.
|
|
50
99
|
|
|
51
100
|
## Finding more
|
|
52
101
|
|
|
@@ -1,17 +1,42 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superagnt-task-agents
|
|
3
|
-
description: This skill should be used when a task must recur — "run this every day", "on a schedule", "set up a cron", "keep this updated while I sleep", "check X every morning" — or when a recurring job keeps re-running inside this client and eating its usage. Covers
|
|
4
|
-
version: 0.
|
|
3
|
+
description: This skill should be used when a task must recur — "run this every day", "on a schedule", "set up a cron", "keep this updated while I sleep", "check X every morning" — or when a recurring job keeps re-running inside this client and eating its usage. Covers the two ways to run it: this client's own scheduler when it can run the superagnt tools, or a superagnt task agent, a small deployed agent that runs one job on the hosted runtime, fired by a schedule or webhook, with state in the workspace database. Cron mechanics in schedules.md.
|
|
4
|
+
version: 0.2.0
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# Task agents: recurring work
|
|
7
|
+
# Task agents: recurring work
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
9
|
+
A recurring task can run two ways. Offer whichever fits the human:
|
|
10
|
+
|
|
11
|
+
- **This client's own scheduler.** If the client can schedule a recurring
|
|
12
|
+
task whose runs have the superagnt tools, use it. Each run starts with no
|
|
13
|
+
chat history, so write the task to stand alone and keep its state in the
|
|
14
|
+
workspace database. Runs use the human's plan for this client; superagnt
|
|
15
|
+
data calls still spend data credits. A scheduled run starts with nobody
|
|
16
|
+
signed in: check that the client can run unattended on this machine and
|
|
17
|
+
that something will fire it (the client's scheduler, cron or launchd), and
|
|
18
|
+
test one run. Nobody approves calls in a scheduled run and superagnt
|
|
19
|
+
doesn't gate tools for a client, so give the run an allowlist of only the
|
|
20
|
+
tools the job needs, with nothing that sends a message or starts a
|
|
21
|
+
campaign (on a grouped server that's the whole group tool, such as
|
|
22
|
+
`connection_gmail_mail_send`), and check in the test run that the
|
|
23
|
+
scheduled run's tool list has none of them. If the client can't restrict
|
|
24
|
+
tools for a scheduled run, build a task agent. Have
|
|
25
|
+
each run write its result where the human looks, and check the last run's
|
|
26
|
+
timestamp in the next attended session. If you are not sure the client can
|
|
27
|
+
schedule, or that its scheduled runs see the superagnt tools, say so and
|
|
28
|
+
build a task agent.
|
|
29
|
+
- **A task agent.** A small deployed superagnt agent that carries ONE job.
|
|
30
|
+
It runs on the hosted runtime, billed per run to the workspace, and a
|
|
31
|
+
schedule or webhook fires it with nobody at a keyboard and the laptop
|
|
32
|
+
closed. Use it when the client can't schedule, when the job reacts to
|
|
33
|
+
events (webhooks), or when it must run whether or not the human's machine
|
|
34
|
+
is on.
|
|
35
|
+
|
|
36
|
+
What doesn't work is re-running the job by hand in chat each time. Once a
|
|
37
|
+
task has run in-session more than twice and will keep recurring, offer one
|
|
38
|
+
of the two. The recipe below builds a task agent; steps 1 and 2 apply to a
|
|
39
|
+
client-scheduled task too.
|
|
15
40
|
|
|
16
41
|
## Recipe
|
|
17
42
|
|
|
@@ -19,10 +44,11 @@ task has run in-session more than twice and will keep recurring.
|
|
|
19
44
|
not succeeded once end to end.
|
|
20
45
|
2. **State in the workspace database** (workspace-db skill). A hosted run has
|
|
21
46
|
no chat history — everything it needs to resume must be in a table.
|
|
22
|
-
3. **Enable the families.** `agnt_tools_enable(['lifecycle'])`
|
|
23
|
-
create/deploy; `['schedules']` for cron.
|
|
24
|
-
|
|
25
|
-
`confirm_url`
|
|
47
|
+
3. **Enable the families.** `agnt_tools_enable({ families: ['lifecycle'] })`
|
|
48
|
+
for create/deploy; `['schedules']` for cron. Both are on every plan. Plans
|
|
49
|
+
cap deployed agents and enabled schedules, so a `requires_upgrade` result
|
|
50
|
+
carries a `confirm_url` naming the next plan: hand it to the human and
|
|
51
|
+
wait; not an error.
|
|
26
52
|
4. **Create narrow.** `agnt_agents_create` with a name and a system prompt
|
|
27
53
|
that is the full job: the task, the tables it reads/writes, what done
|
|
28
54
|
looks like, what to do on failure. Then `agnt_agents_update_config` with
|
|
@@ -30,7 +56,9 @@ task has run in-session more than twice and will keep recurring.
|
|
|
30
56
|
`agnt_tools_search`, and only the tools the job needs. A task agent with
|
|
31
57
|
every tool is a liability, not a convenience.
|
|
32
58
|
5. **Deploy.** `agnt_agents_deploy` flips it live and it starts billing from
|
|
33
|
-
its first session
|
|
59
|
+
its first session, so confirm with the human before calling. Runs spend
|
|
60
|
+
AI credits, which the builder plans and the trial don't include: the human
|
|
61
|
+
tops them up in the superagnt app.
|
|
34
62
|
6. **Wire the trigger.** An event exists → bind a webhook to the agent
|
|
35
63
|
(automations skill). Purely time-based → create a schedule
|
|
36
64
|
([schedules.md](schedules.md)). On-demand from another agent or session →
|
|
@@ -50,6 +78,21 @@ task has run in-session more than twice and will keep recurring.
|
|
|
50
78
|
- Misbehaving agent: `agnt_agents_set_enabled(false)` stops triggers
|
|
51
79
|
reversibly — prefer it over archiving.
|
|
52
80
|
|
|
81
|
+
## Tool names on grouped servers
|
|
82
|
+
|
|
83
|
+
This skill writes flat (per-operation) tool names. New superagnt servers list
|
|
84
|
+
grouped tools instead: one tool per resource with an `action` argument. Flat
|
|
85
|
+
names still resolve there but are not listed, so call the grouped form:
|
|
86
|
+
|
|
87
|
+
- `agnt_agents_create` / `agnt_agents_update_config` / `agnt_agents_deploy` / `agnt_agents_set_enabled` → `agnt_agents_write`, action `create` / `update_config` / `deploy` / `set_enabled`
|
|
88
|
+
- `agnt_agents_dispatch` / `agnt_agents_session_start` / `agnt_agents_session_send` → `agnt_agents_run`, action `dispatch` / `session_start` / `session_send`
|
|
89
|
+
- `agnt_agents_session_poll` → `agnt_agents_read`, action `session_poll`
|
|
90
|
+
- `agnt_observability_read_session` → `agnt_observability_read`, action `read_session`
|
|
91
|
+
- `agnt_schedules_create` / `agnt_schedules_update` → `agnt_schedules_write`, action `create` / `update`
|
|
92
|
+
|
|
93
|
+
`agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
|
|
94
|
+
server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
|
|
95
|
+
|
|
53
96
|
## More
|
|
54
97
|
|
|
55
98
|
- Cron syntax, cadence discipline, timezones: [schedules.md](schedules.md)
|
|
@@ -9,8 +9,10 @@ version: 0.2.0
|
|
|
9
9
|
Every superagnt workspace can carry a real Postgres the agent owns:
|
|
10
10
|
`agnt_db_list_tables`, `agnt_db_execute_sql`, `agnt_db_apply_migration`,
|
|
11
11
|
`agnt_db_insert` / `select` / `update` / `upsert` / `delete`,
|
|
12
|
-
`agnt_db_load_csv`.
|
|
13
|
-
|
|
12
|
+
`agnt_db_load_csv`. On a grouped server these are actions of `agnt_db_read`,
|
|
13
|
+
`agnt_db_write` and `agnt_db_sql` (see the end of this file). If the tools are
|
|
14
|
+
missing under both names, enable the `database` family (`agnt_tools_enable`);
|
|
15
|
+
if the database is not yet provisioned,
|
|
14
16
|
`agnt_db_status` says so and provisioning is automatic on first use.
|
|
15
17
|
|
|
16
18
|
Local files die with the session. Anything a later run, another agent, a
|
|
@@ -38,6 +40,20 @@ schedule, or a canvas must read belongs here.
|
|
|
38
40
|
stable status strings are exactly what canvas widgets bind to (see the
|
|
39
41
|
canvas skill).
|
|
40
42
|
|
|
43
|
+
## Tool names on grouped servers
|
|
44
|
+
|
|
45
|
+
This skill writes flat (per-operation) tool names. New superagnt servers list
|
|
46
|
+
grouped tools instead: one tool per resource with an `action` argument. Flat
|
|
47
|
+
names still resolve there but are not listed, so call the grouped form:
|
|
48
|
+
|
|
49
|
+
- `agnt_db_status` / `agnt_db_list_tables` / `agnt_db_select` → `agnt_db_read`, action `status` / `list_tables` / `select`
|
|
50
|
+
- `agnt_db_insert` / `agnt_db_upsert` / `agnt_db_update` / `agnt_db_load_csv` → `agnt_db_write`, action `insert` / `upsert` / `update` / `load_csv`
|
|
51
|
+
- `agnt_db_execute_sql` / `agnt_db_apply_migration` → `agnt_db_sql`, action `execute_sql` / `apply_migration`
|
|
52
|
+
- `agnt_db_delete` keeps its name on both surfaces
|
|
53
|
+
|
|
54
|
+
`agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
|
|
55
|
+
server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
|
|
56
|
+
|
|
41
57
|
## More
|
|
42
58
|
|
|
43
59
|
- CSVs and exports land as tables in one call: `agnt_db_load_csv` — then
|