@superagnt/superagnt 2.0.6 → 2.0.8
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 +6 -6
- package/index.js +10 -3
- package/openclaw.plugin.json +3 -3
- package/package.json +3 -3
- package/skills/superagnt-automations/SKILL.md +19 -4
- package/skills/superagnt-dashboards/SKILL.md +70 -0
- package/skills/superagnt-data-pipelines/SKILL.md +26 -9
- package/skills/superagnt-data-sources/SKILL.md +63 -20
- package/skills/superagnt-lead-generation/SKILL.md +21 -0
- package/skills/superagnt-setup/SKILL.md +76 -26
- package/skills/superagnt-task-agents/SKILL.md +61 -17
- package/skills/superagnt-workspace-db/SKILL.md +24 -8
- package/skills/superagnt-canvas/SKILL.md +0 -45
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# superagnt_ for OpenClaw — the agent value layer
|
|
2
2
|
|
|
3
|
-
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
|
|
3
|
+
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 dashboards — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -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,14 +41,14 @@ 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
|
|
48
48
|
- **People + company enrichment** — search, enrich, verified emails
|
|
49
49
|
- **Workspace database** — a real Postgres per workspace, with migrations
|
|
50
50
|
- **Schedules & webhooks** — recurring automations and inbound event ingestion
|
|
51
|
-
- **
|
|
51
|
+
- **Dashboards** — live views the agent builds over the workspace's data
|
|
52
52
|
|
|
53
53
|
## Bundled skills
|
|
54
54
|
|
|
@@ -56,7 +56,7 @@ The same base skills as the superagnt Claude Code plugin, teaching the
|
|
|
56
56
|
workflows on top of the tools:
|
|
57
57
|
|
|
58
58
|
- `superagnt-automations`
|
|
59
|
-
- `superagnt-
|
|
59
|
+
- `superagnt-dashboards`
|
|
60
60
|
- `superagnt-data-pipelines`
|
|
61
61
|
- `superagnt-data-sources`
|
|
62
62
|
- `superagnt-lead-generation`
|
|
@@ -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
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"id": "superagnt",
|
|
3
3
|
"name": "superagnt_",
|
|
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
|
|
5
|
-
"version": "2.0.
|
|
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 dashboards — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.",
|
|
5
|
+
"version": "2.0.8",
|
|
6
6
|
"mcpServers": {
|
|
7
7
|
"superagnt": {
|
|
8
8
|
"url": "https://mcp.superagnt.com/mcp",
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
},
|
|
13
13
|
"skills": [
|
|
14
14
|
"skills/superagnt-automations",
|
|
15
|
-
"skills/superagnt-
|
|
15
|
+
"skills/superagnt-dashboards",
|
|
16
16
|
"skills/superagnt-data-pipelines",
|
|
17
17
|
"skills/superagnt-data-sources",
|
|
18
18
|
"skills/superagnt-lead-generation",
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@superagnt/superagnt",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.8",
|
|
4
4
|
"type": "module",
|
|
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
|
|
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 dashboards — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.",
|
|
6
6
|
"main": "index.js",
|
|
7
7
|
"license": "MIT",
|
|
8
8
|
"homepage": "https://superagnt.com/agent-toolkit",
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
"database",
|
|
16
16
|
"automation",
|
|
17
17
|
"lead-generation",
|
|
18
|
-
"
|
|
18
|
+
"dashboards",
|
|
19
19
|
"ai-agent"
|
|
20
20
|
],
|
|
21
21
|
"publishConfig": {
|
|
@@ -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,10 +56,23 @@ 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`.
|
|
60
|
-
-
|
|
75
|
+
- Setup guide, every client: https://www.superagnt.com/install
|
|
61
76
|
- Packaged event-driven workflows: https://superagnt.com/skills
|
|
62
77
|
|
|
63
78
|
<!-- skill_id: automations · source: https://github.com/superagnt/plugins -->
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: superagnt-dashboards
|
|
3
|
+
description: This skill should be used when the user asks for a "dashboard", "shareable report", "KPI page", or "live chart", or wants results as a page someone else can open. Covers the superagnt workspace dashboard: views (HTML pages on sa-* elements) bound to named queries over the workspace database and platform data, the draft-and-publish loop, and public links. Use after data lands in the workspace database; see workspace-db for table design.
|
|
4
|
+
version: 0.3.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# The workspace dashboard: results as a living page
|
|
8
|
+
|
|
9
|
+
Every workspace has one dashboard of views. A view is an HTML page built from
|
|
10
|
+
`sa-*` elements (numbers, charts, tables, lists), each bound to a named query
|
|
11
|
+
over the workspace database or platform data (credits, usage, data jobs,
|
|
12
|
+
agent runs, pending approvals). Views stay current as the data changes.
|
|
13
|
+
People in the workspace see them in the superagnt app, and a person can share
|
|
14
|
+
one as a public link that anyone can open, no account needed.
|
|
15
|
+
|
|
16
|
+
## Procedure
|
|
17
|
+
|
|
18
|
+
1. Data first. Queries read tables; if the table does not exist yet, the
|
|
19
|
+
workspace-db skill's patterns come first.
|
|
20
|
+
2. `agnt_dashboards_guide` once: the files, the query grammar, the `sa-*`
|
|
21
|
+
elements and publishing. `agnt_dashboards_describe_data` lists the tables
|
|
22
|
+
and platform datasets a query can read.
|
|
23
|
+
3. Build in your own draft: `agnt_dashboards_apply_template` for a starter
|
|
24
|
+
view (number row, trend, breakdown, table with CSV, approvals, credits and
|
|
25
|
+
usage), or `agnt_dashboards_write_file` for `queries/<name>.sql`,
|
|
26
|
+
`views/<slug>.html` and the view's `dashboard.json` entry. Every write is
|
|
27
|
+
checked and returns its problems in plain words. Each query runs once with
|
|
28
|
+
its defaults, so aggregate in SQL (`group by date_trunc('day', ...)`).
|
|
29
|
+
4. `agnt_dashboards_preview` renders the view as a PNG with a report on each
|
|
30
|
+
query. Fix what it names, then `agnt_dashboards_publish` with a one-line
|
|
31
|
+
summary: people in the workspace see the new version at once.
|
|
32
|
+
5. Share: a person in the workspace turns on a view's public link from the
|
|
33
|
+
superagnt app. Agents can't make one; `agnt_dashboards_unshare_view` turns
|
|
34
|
+
one off.
|
|
35
|
+
|
|
36
|
+
## Layout discipline
|
|
37
|
+
|
|
38
|
+
- Lead with a row of 3–5 numbers (`sa-value`), then trends (`sa-chart`),
|
|
39
|
+
then detail tables (`sa-table`).
|
|
40
|
+
- One measure per chart; failed/error series go in `danger-fields`, never the
|
|
41
|
+
accent.
|
|
42
|
+
- Time charts need `event_at`/`created_at` timestamptz columns; funnels bind
|
|
43
|
+
to stable status strings — schema rules in workspace-db.
|
|
44
|
+
- The dashboard tools are on for every workspace where the dashboard is on; a
|
|
45
|
+
deployed agent gets them with `dashboards_enabled`. What the plan caps is
|
|
46
|
+
the workspace database behind the queries (tables, rows, storage).
|
|
47
|
+
|
|
48
|
+
## Tool names on grouped servers
|
|
49
|
+
|
|
50
|
+
New servers list one tool per family with an `action` argument. The flat
|
|
51
|
+
names above map to:
|
|
52
|
+
|
|
53
|
+
| Flat | Grouped tool, action |
|
|
54
|
+
|---|---|
|
|
55
|
+
| `agnt_dashboards_guide`, `_list_files`, `_read_file`, `_describe_data`, `_history`, `_preview` | `agnt_dashboards_read`: `guide`, `list_files`, `read_file`, `describe_data`, `history`, `preview` |
|
|
56
|
+
| `agnt_dashboards_write_file`, `_edit_file`, `_apply_template`, `_publish`, `_restore` | `agnt_dashboards_write`: `write_file`, `edit_file`, `apply_template`, `publish`, `restore` |
|
|
57
|
+
| `agnt_dashboards_delete_file`, `_discard_draft`, `_unshare_view` | `agnt_dashboards_remove`: `delete_file`, `discard_draft`, `unshare_view` |
|
|
58
|
+
|
|
59
|
+
Flat names still resolve on a grouped server but are not listed, so most
|
|
60
|
+
clients will not let you call them: use the grouped tool. Canvases (the old
|
|
61
|
+
`agnt_canvas_*` tools) were retired; those names now only answer with this
|
|
62
|
+
replacement.
|
|
63
|
+
|
|
64
|
+
## More
|
|
65
|
+
|
|
66
|
+
- A view over a table a task agent keeps fresh is a live dashboard with zero
|
|
67
|
+
upkeep — pair with the task-agents skill.
|
|
68
|
+
- Worked examples: https://superagnt.com/skills
|
|
69
|
+
|
|
70
|
+
<!-- skill_id: dashboards · source: https://github.com/superagnt/plugins -->
|
|
@@ -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
|
-
agents, and
|
|
41
|
-
its result stores it where only the
|
|
43
|
+
agents, and dashboard views can read outcomes from. A recipe that merely returns
|
|
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,10 +55,24 @@ 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
|
|
58
75
|
- Feeding a job from an inbound webhook: the automations skill
|
|
59
|
-
-
|
|
76
|
+
- Setup guide, every client: https://www.superagnt.com/install
|
|
60
77
|
|
|
61
78
|
<!-- skill_id: data-pipelines · source: https://github.com/superagnt/plugins -->
|
|
@@ -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
|
|
|
@@ -8,45 +8,95 @@ version: 0.2.0
|
|
|
8
8
|
|
|
9
9
|
## Connecting / reconnecting
|
|
10
10
|
|
|
11
|
-
The
|
|
12
|
-
`https://superagnt.com/
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
11
|
+
The setup guide has the steps for every client, one section each:
|
|
12
|
+
`https://www.superagnt.com/install`. The endpoint is
|
|
13
|
+
`https://mcp.superagnt.com/mcp`, OAuth-first (the consent screen doubles as
|
|
14
|
+
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; the plans include data credits only,
|
|
99
|
+
and the trial adds a one-time AI credit for hosted agents.
|
|
50
100
|
|
|
51
101
|
## Finding more
|
|
52
102
|
|
|
@@ -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,10 @@ 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. The builder plans include none and the trial a one-time AI
|
|
61
|
+
credit for hosted agents: past that, the human tops them up in the
|
|
62
|
+
superagnt app.
|
|
34
63
|
6. **Wire the trigger.** An event exists → bind a webhook to the agent
|
|
35
64
|
(automations skill). Purely time-based → create a schedule
|
|
36
65
|
([schedules.md](schedules.md)). On-demand from another agent or session →
|
|
@@ -43,17 +72,32 @@ task has run in-session more than twice and will keep recurring.
|
|
|
43
72
|
|
|
44
73
|
## Keeping it honest
|
|
45
74
|
|
|
46
|
-
- Results land where the human already looks: a
|
|
47
|
-
table the next session reads — never only in the agent's own transcript.
|
|
75
|
+
- Results land where the human already looks: a dashboard view (dashboards
|
|
76
|
+
skill), or a table the next session reads — never only in the agent's own transcript.
|
|
48
77
|
- One job per agent. A second job is a second agent; they can hand off via
|
|
49
78
|
`agnt_agents_dispatch` or agent-to-agent webhooks.
|
|
50
79
|
- Misbehaving agent: `agnt_agents_set_enabled(false)` stops triggers
|
|
51
80
|
reversibly — prefer it over archiving.
|
|
52
81
|
|
|
82
|
+
## Tool names on grouped servers
|
|
83
|
+
|
|
84
|
+
This skill writes flat (per-operation) tool names. New superagnt servers list
|
|
85
|
+
grouped tools instead: one tool per resource with an `action` argument. Flat
|
|
86
|
+
names still resolve there but are not listed, so call the grouped form:
|
|
87
|
+
|
|
88
|
+
- `agnt_agents_create` / `agnt_agents_update_config` / `agnt_agents_deploy` / `agnt_agents_set_enabled` → `agnt_agents_write`, action `create` / `update_config` / `deploy` / `set_enabled`
|
|
89
|
+
- `agnt_agents_dispatch` / `agnt_agents_session_start` / `agnt_agents_session_send` → `agnt_agents_run`, action `dispatch` / `session_start` / `session_send`
|
|
90
|
+
- `agnt_agents_session_poll` → `agnt_agents_read`, action `session_poll`
|
|
91
|
+
- `agnt_observability_read_session` → `agnt_observability_read`, action `read_session`
|
|
92
|
+
- `agnt_schedules_create` / `agnt_schedules_update` → `agnt_schedules_write`, action `create` / `update`
|
|
93
|
+
|
|
94
|
+
`agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
|
|
95
|
+
server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
|
|
96
|
+
|
|
53
97
|
## More
|
|
54
98
|
|
|
55
99
|
- Cron syntax, cadence discipline, timezones: [schedules.md](schedules.md)
|
|
56
100
|
- Event triggers instead of clocks: the automations skill
|
|
57
|
-
-
|
|
101
|
+
- Setup guide, every client: https://www.superagnt.com/install
|
|
58
102
|
|
|
59
103
|
<!-- skill_id: task-agents · source: https://github.com/superagnt/plugins -->
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superagnt-workspace-db
|
|
3
|
-
description: This skill should be used when an agent workflow needs durable state: "save these results", "track status across runs", "remember this between sessions", building a pipeline, queue, or CRM-like table, or logging events over time. Covers table design in the superagnt workspace Postgres (agnt_db_*): schema patterns for pipelines, HITL queues, KPI events, and audit logs, plus
|
|
3
|
+
description: This skill should be used when an agent workflow needs durable state: "save these results", "track status across runs", "remember this between sessions", building a pipeline, queue, or CRM-like table, or logging events over time. Covers table design in the superagnt workspace Postgres (agnt_db_*): schema patterns for pipelines, HITL queues, KPI events, and audit logs, plus dashboard-ready column rules. Prefer it over local files or scratch JSON for anything a later run must read.
|
|
4
4
|
version: 0.2.0
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -9,12 +9,14 @@ 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
|
|
17
|
-
schedule, or a
|
|
19
|
+
schedule, or a dashboard view must read belongs here.
|
|
18
20
|
|
|
19
21
|
## Schema patterns
|
|
20
22
|
|
|
@@ -34,9 +36,23 @@ schedule, or a canvas must read belongs here.
|
|
|
34
36
|
- Migrations through `agnt_db_apply_migration` with a short descriptive
|
|
35
37
|
name; ad-hoc DDL through `execute_sql` gets lost.
|
|
36
38
|
- Ask before destructive SQL (drop/truncate/mass delete) — always.
|
|
37
|
-
- Design for the
|
|
38
|
-
stable status strings are exactly what
|
|
39
|
-
|
|
39
|
+
- Design for the dashboard from day one: timestamptz + numeric measures +
|
|
40
|
+
stable status strings are exactly what dashboard views chart (see the
|
|
41
|
+
dashboards skill).
|
|
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.
|
|
40
56
|
|
|
41
57
|
## More
|
|
42
58
|
|
|
@@ -44,6 +60,6 @@ schedule, or a canvas must read belongs here.
|
|
|
44
60
|
process at row scale with the data-pipelines skill.
|
|
45
61
|
- Tables are the hand-off surface to task agents and schedules (task-agents
|
|
46
62
|
skill): a hosted run has no chat history, it reads state from here.
|
|
47
|
-
-
|
|
63
|
+
- Setup guide, every client: https://www.superagnt.com/install
|
|
48
64
|
|
|
49
65
|
<!-- skill_id: workspace-db · source: https://github.com/superagnt/plugins -->
|
|
@@ -1,45 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: superagnt-canvas
|
|
3
|
-
description: This skill should be used when the user asks for a "dashboard", "shareable report", "KPI page", or "live chart", or wants results as a URL someone else can open. Covers superagnt canvases: widgets bound to workspace-database queries (KPI rows, trends, funnels, tables, kanban), layout discipline, and share links. Use after data lands in the workspace database; see workspace-db for table design.
|
|
4
|
-
version: 0.2.0
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Canvases: results as a living page
|
|
8
|
-
|
|
9
|
-
A canvas is a hosted page of widgets, each bound to a SQL query over the
|
|
10
|
-
workspace database. It stays current as the data changes, and a share link
|
|
11
|
-
opens for anyone — no account needed on the viewer's side.
|
|
12
|
-
|
|
13
|
-
## Procedure
|
|
14
|
-
|
|
15
|
-
1. Data first. Widgets bind to tables; if the table does not exist yet, the
|
|
16
|
-
workspace-db skill's patterns come first.
|
|
17
|
-
2. `agnt_canvas_introspect_schema` to see what is bindable, then
|
|
18
|
-
`agnt_canvas_preview_query` BEFORE `agnt_canvas_put_widget` — previews
|
|
19
|
-
are capped at 50 rows, so aggregate in SQL (`group by date_trunc`), never
|
|
20
|
-
in the widget.
|
|
21
|
-
3. Build the page: `agnt_canvas_put_widget` per widget,
|
|
22
|
-
`agnt_canvas_set_layout` once at the end.
|
|
23
|
-
4. Share: `agnt_canvas_share_create` returns the public link;
|
|
24
|
-
`agnt_canvas_share_revoke` kills it. Confirm with the user before
|
|
25
|
-
creating a share link — it makes the page reachable outside the
|
|
26
|
-
workspace.
|
|
27
|
-
|
|
28
|
-
## Layout discipline
|
|
29
|
-
|
|
30
|
-
- Lead with a KPI row (3–5 single numbers), then trends, then detail tables.
|
|
31
|
-
- One measure per widget; failed/error series in the danger tone, never the
|
|
32
|
-
accent.
|
|
33
|
-
- Time widgets need `event_at`/`created_at` timestamptz columns; funnels and
|
|
34
|
-
kanbans bind to stable status strings — schema rules in workspace-db.
|
|
35
|
-
- If the canvas family is not enabled: `agnt_tools_enable(['canvas'])` —
|
|
36
|
-
sold under the Database & Canvas module (free trial, `confirm_url` to the
|
|
37
|
-
human on `requires_upgrade`).
|
|
38
|
-
|
|
39
|
-
## More
|
|
40
|
-
|
|
41
|
-
- A canvas over a table a task agent keeps fresh is a live dashboard with
|
|
42
|
-
zero upkeep — pair with the task-agents skill.
|
|
43
|
-
- Worked examples with real dashboards: https://superagnt.com/skills
|
|
44
|
-
|
|
45
|
-
<!-- skill_id: canvas · source: https://github.com/superagnt/plugins -->
|