@vantageos/agent-engine 0.1.0-alpha.7 → 0.1.0-alpha.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 +127 -49
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
# @vantageos/agent-engine
|
|
2
2
|
|
|
3
|
-
A reusable [Convex component](https://www.convex.dev/components) that
|
|
4
|
-
a durable **agent engine**: sessions, delegation, tool approvals,
|
|
5
|
-
"habits", bounded spending "mandates", and long-task survival —
|
|
6
|
-
top of
|
|
7
|
-
|
|
3
|
+
A reusable [Convex component](https://www.convex.dev/components) that
|
|
4
|
+
provides a durable **agent engine**: sessions, delegation, tool approvals,
|
|
5
|
+
scheduled "habits", bounded spending "mandates", and long-task survival —
|
|
6
|
+
all built on top of
|
|
7
|
+
[`@convex-dev/workflow`](https://www.npmjs.com/package/@convex-dev/workflow)
|
|
8
|
+
and
|
|
9
|
+
[`@convex-dev/workpool`](https://www.npmjs.com/package/@convex-dev/workpool).
|
|
8
10
|
|
|
9
11
|
**An agent is a data aggregate, not compiled code.** Creating an agent means
|
|
10
12
|
writing a row (plus child rows for skills, tool approvals, connections,
|
|
@@ -77,61 +79,137 @@ scoped by `orgId` first, deny-by-default.
|
|
|
77
79
|
### API surface (component/, current release)
|
|
78
80
|
|
|
79
81
|
```
|
|
80
|
-
components.agentEngine.engine.agents.create({
|
|
82
|
+
components.agentEngine.engine.agents.create({
|
|
83
|
+
orgId, createdBy, name, description?, instructions, model,
|
|
84
|
+
reasoningEffort?, modelProvider?, maxSubagents?,
|
|
85
|
+
maxInputTokensPerSession?,
|
|
86
|
+
}) -> Id<"agents">
|
|
81
87
|
components.agentEngine.engine.agents.get({ orgId, agentId }) -> agent | null
|
|
82
88
|
|
|
83
|
-
components.agentEngine.engine.directory.listByOrg({ orgId })
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
components.agentEngine.engine.sessions.
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
components.agentEngine.engine.sessions.
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
89
|
+
components.agentEngine.engine.directory.listByOrg({ orgId })
|
|
90
|
+
-> { _id, name, status, model, createdAt }[]
|
|
91
|
+
|
|
92
|
+
components.agentEngine.engine.resolvers.resolveManifest({
|
|
93
|
+
orgId, sessionId,
|
|
94
|
+
}) -> { agentId, name, instructions, model, toolApprovals[] }
|
|
95
|
+
|
|
96
|
+
components.agentEngine.engine.sessions.start({
|
|
97
|
+
orgId, agentId, createdBy,
|
|
98
|
+
}) -> { sessionId: Id<"sessions">, workflowId: string }
|
|
99
|
+
components.agentEngine.engine.sessions.sendTurn({
|
|
100
|
+
orgId, sessionId, input,
|
|
101
|
+
}) -> null
|
|
102
|
+
components.agentEngine.engine.sessions.appendReasoning({
|
|
103
|
+
orgId, sessionId, chunk,
|
|
104
|
+
}) -> null
|
|
105
|
+
components.agentEngine.engine.sessions.requestToolCall({
|
|
106
|
+
orgId, sessionId, toolName, argsJson,
|
|
107
|
+
}) -> { authorized, approvalPending, denied }
|
|
108
|
+
components.agentEngine.engine.sessions.completeToolCall({
|
|
109
|
+
orgId, sessionId, toolName, resultJson,
|
|
110
|
+
}) -> null
|
|
111
|
+
components.agentEngine.engine.sessions.completeTurn({
|
|
112
|
+
orgId, sessionId,
|
|
113
|
+
}) -> null
|
|
114
|
+
components.agentEngine.engine.sessions.listEvents({
|
|
115
|
+
orgId, sessionId,
|
|
116
|
+
}) -> sessionEvent[]
|
|
117
|
+
|
|
118
|
+
components.agentEngine.engine.toolApprovals.respond({
|
|
119
|
+
orgId, sessionId, toolName,
|
|
120
|
+
decision: "approved"|"denied",
|
|
121
|
+
updatePolicy?: "always"|"once"|"never",
|
|
122
|
+
}) -> null
|
|
123
|
+
|
|
124
|
+
components.agentEngine.engine.wakeup.enqueue({
|
|
125
|
+
orgId, agentId, mandateScope, cost, reason,
|
|
126
|
+
workFunctionHandle, workflowId, awaitedEventName,
|
|
127
|
+
}) -> Id<"wakeableWork"> (action)
|
|
98
128
|
components.agentEngine.engine.wakeup.cancel({ orgId, wakeableWorkId }) -> null
|
|
99
|
-
components.agentEngine.engine.wakeup.getStatus({
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
129
|
+
components.agentEngine.engine.wakeup.getStatus({
|
|
130
|
+
orgId, wakeableWorkId,
|
|
131
|
+
}) -> { status, resultSummary?, ... }
|
|
132
|
+
|
|
133
|
+
components.agentEngine.engine.durableJob.start({
|
|
134
|
+
orgId, kind, stepFunctionHandle, totalSteps, maxAttemptsPerStep,
|
|
135
|
+
}) -> Id<"durableJobs">
|
|
136
|
+
components.agentEngine.engine.durableJob.getStatus({ orgId, jobId })
|
|
137
|
+
-> { status, cursor, totalSteps, lastError?, abandonedAtStep? }
|
|
103
138
|
components.agentEngine.engine.durableJob.cancel({ orgId, jobId }) -> null
|
|
104
139
|
|
|
105
|
-
components.agentEngine.engine.mandates.set({
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
components.agentEngine.engine.mandates.
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
140
|
+
components.agentEngine.engine.mandates.set({
|
|
141
|
+
orgId, agentId, scope, kind, rate, period, capacity?,
|
|
142
|
+
}) -> Id<"mandates">
|
|
143
|
+
components.agentEngine.engine.mandates.get({
|
|
144
|
+
orgId, agentId, scope,
|
|
145
|
+
}) -> mandate | null
|
|
146
|
+
components.agentEngine.engine.mandates.spend({
|
|
147
|
+
orgId, agentId, scope, cost, reason,
|
|
148
|
+
}) -> { ok, approvalId? }
|
|
149
|
+
components.agentEngine.engine.mandates.listApprovals({
|
|
150
|
+
orgId, agentId,
|
|
151
|
+
}) -> approvalRequest[]
|
|
152
|
+
components.agentEngine.engine.mandates.resolveApproval({
|
|
153
|
+
orgId, approvalId, resolvedBy, status: "approved"|"denied",
|
|
154
|
+
}) -> null
|
|
155
|
+
components.agentEngine.engine.mandates.usageCount({
|
|
156
|
+
orgId, agentId, scope,
|
|
157
|
+
}) -> number
|
|
158
|
+
|
|
159
|
+
components.agentEngine.engine.habits.create({
|
|
160
|
+
orgId, agentId, name, cronExpression, prompt,
|
|
161
|
+
}) -> Id<"habits">
|
|
113
162
|
components.agentEngine.engine.habits.get({ orgId, habitId }) -> habit | null
|
|
114
163
|
components.agentEngine.engine.habits.listForAgent({ orgId, agentId }) -> habit[]
|
|
115
|
-
components.agentEngine.engine.habits.updateSchedule({
|
|
164
|
+
components.agentEngine.engine.habits.updateSchedule({
|
|
165
|
+
orgId, habitId, cronExpression,
|
|
166
|
+
}) -> null
|
|
116
167
|
components.agentEngine.engine.habits.disable({ orgId, habitId }) -> null
|
|
117
168
|
components.agentEngine.engine.habits.enable({ orgId, habitId }) -> null
|
|
118
169
|
components.agentEngine.engine.habits.listRuns({ orgId, habitId }) -> habitRun[]
|
|
119
170
|
|
|
120
|
-
components.agentEngine.engine.sandboxCallback.startRun({
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
components.agentEngine.engine.sandboxCallback.
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
components.agentEngine.engine.
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
components.agentEngine.engine.
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
components.agentEngine.engine.
|
|
133
|
-
|
|
134
|
-
|
|
171
|
+
components.agentEngine.engine.sandboxCallback.startRun({
|
|
172
|
+
orgId, workflowId, awaitedEventName, timeoutMs,
|
|
173
|
+
}) -> Id<"sandboxRuns">
|
|
174
|
+
components.agentEngine.engine.sandboxCallback.attachSandboxId({
|
|
175
|
+
orgId, sandboxRunId, sandboxId,
|
|
176
|
+
}) -> null
|
|
177
|
+
components.agentEngine.engine.sandboxCallback.getStatus({
|
|
178
|
+
orgId, sandboxRunId,
|
|
179
|
+
}) -> { status, resultSummary?, ... }
|
|
180
|
+
components.agentEngine.engine.sandboxCallback.processCallback({
|
|
181
|
+
orgId, sandboxRunId, deliveryId, status, resultSummary?,
|
|
182
|
+
}) -> { outcome: "woke"|"duplicate" }
|
|
183
|
+
components.agentEngine.engine.sandboxCallback.deadLetterMalformed({
|
|
184
|
+
orgId?, deliveryId, reason, rawBody,
|
|
185
|
+
}) -> null
|
|
186
|
+
|
|
187
|
+
components.agentEngine.engine.delegation.declareSubagent({
|
|
188
|
+
orgId, parentAgentId, childAgentId, toolName, description?,
|
|
189
|
+
}) -> Id<"subagents">
|
|
190
|
+
components.agentEngine.engine.delegation.listSubagents({
|
|
191
|
+
orgId, parentAgentId,
|
|
192
|
+
}) -> subagent[]
|
|
193
|
+
components.agentEngine.engine.delegation.delegateToSubagent({
|
|
194
|
+
orgId, subagentId, ...,
|
|
195
|
+
}) -> null (action)
|
|
196
|
+
components.agentEngine.engine.delegation.invokeAgentClone({
|
|
197
|
+
orgId, agentId, ...,
|
|
198
|
+
}) -> null (action; root-only, non-recursive by construction)
|
|
199
|
+
|
|
200
|
+
components.agentEngine.engine.vpConnection.get({
|
|
201
|
+
orgId, agentId,
|
|
202
|
+
}) -> vpConnection | null
|
|
203
|
+
components.agentEngine.engine.vpConnection.getToggles({
|
|
204
|
+
orgId, agentId,
|
|
205
|
+
}) -> { memoryEnabled, tasksEnabled, messagesEnabled, notesEnabled }
|
|
206
|
+
components.agentEngine.engine.vpConnection.setToggles({
|
|
207
|
+
orgId, agentId, memoryEnabled?, tasksEnabled?,
|
|
208
|
+
messagesEnabled?, notesEnabled?,
|
|
209
|
+
}) -> Id<"vpConnections">
|
|
210
|
+
components.agentEngine.engine.vpConnection.invokeVpTool({
|
|
211
|
+
orgId, agentId, tool, vpFunctionHandle, argsJson,
|
|
212
|
+
}) -> null (action)
|
|
135
213
|
```
|
|
136
214
|
|
|
137
215
|
### Concepts
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vantageos/agent-engine",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.8",
|
|
4
4
|
"description": "Reusable Convex component: durable agent engine. Agent = data aggregate (root sheet + child tables), never compiled code. Built on @convex-dev/workflow + @convex-dev/workpool (+ @convex-dev/agent). Eve parity by design.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "FSL-1.1-Apache-2.0",
|