@collective-intelligence/external-apps-server-sdk 0.3.2 → 0.3.3
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 +10 -2
- package/dist/admin.d.ts +3 -3
- package/dist/chunks/{index-vf83jqc8.js → index-hzx6hj46.js} +2 -2
- package/dist/effect.d.ts +270 -2
- package/dist/effect.js +1 -1
- package/dist/index.d.ts +270 -2
- package/dist/index.js +1 -1
- package/docs/guide/ai/index.md +36 -17
- package/docs/guide/ai/studio.md +245 -0
- package/docs/guide/data/connectors.md +81 -18
- package/docs/guide/data/datasets.md +6 -17
- package/docs/guide/data/documents.md +235 -0
- package/docs/guide/data/index.md +62 -0
- package/docs/guide/data/knowledge.md +21 -18
- package/docs/guide/develop/extensions.md +15 -14
- package/docs/guide/develop/external-apps.md +48 -14
- package/docs/guide/develop/infrastructure.md +135 -0
- package/docs/guide/develop/sdks.md +2 -2
- package/docs/guide/index.md +11 -7
- package/docs/guide/platform/access.md +82 -17
- package/docs/guide/platform/architecture.md +27 -18
- package/docs/guide/platform/entrypoints.md +125 -48
- package/docs/guide/scenarios/index.md +69 -46
- package/docs/guide/template/index.md +22 -9
- package/docs/guide/template/state-machines.md +1 -1
- package/package.json +4 -4
package/dist/index.d.ts
CHANGED
|
@@ -64,6 +64,47 @@ export declare class MemberSessionExchangeError extends MemberSessionExchangeErr
|
|
|
64
64
|
}>, options: Schema.MakeOptions | undefined);
|
|
65
65
|
get message(): string;
|
|
66
66
|
}
|
|
67
|
+
export type Suspend1 = {
|
|
68
|
+
fieldId: string;
|
|
69
|
+
kind: "predicate";
|
|
70
|
+
operator: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "is_null" | "is_not_null" | "contains" | "starts_with";
|
|
71
|
+
values: Array<{
|
|
72
|
+
kind: "null";
|
|
73
|
+
} | {
|
|
74
|
+
kind: "boolean";
|
|
75
|
+
value: boolean;
|
|
76
|
+
} | {
|
|
77
|
+
kind: "string";
|
|
78
|
+
value: string;
|
|
79
|
+
} | {
|
|
80
|
+
kind: "int64";
|
|
81
|
+
value: string;
|
|
82
|
+
} | {
|
|
83
|
+
kind: "float64";
|
|
84
|
+
value: number;
|
|
85
|
+
} | {
|
|
86
|
+
kind: "decimal";
|
|
87
|
+
value: string;
|
|
88
|
+
} | {
|
|
89
|
+
kind: "date";
|
|
90
|
+
value: string;
|
|
91
|
+
} | {
|
|
92
|
+
kind: "timestamp";
|
|
93
|
+
value: string;
|
|
94
|
+
} | {
|
|
95
|
+
kind: "duration";
|
|
96
|
+
value: string;
|
|
97
|
+
} | {
|
|
98
|
+
kind: "json";
|
|
99
|
+
value: unknown;
|
|
100
|
+
}>;
|
|
101
|
+
} | {
|
|
102
|
+
filters: Array<Suspend1>;
|
|
103
|
+
kind: "and" | "or";
|
|
104
|
+
} | {
|
|
105
|
+
filter: Suspend1;
|
|
106
|
+
kind: "not";
|
|
107
|
+
};
|
|
67
108
|
export type AccessExplanation = {
|
|
68
109
|
cut: {
|
|
69
110
|
credential: {
|
|
@@ -171,6 +212,191 @@ export type AccessExplanation = {
|
|
|
171
212
|
}>;
|
|
172
213
|
recordId: string;
|
|
173
214
|
schemaId: string;
|
|
215
|
+
} | {
|
|
216
|
+
datasetId: string;
|
|
217
|
+
kind: "dataset";
|
|
218
|
+
admitted: true;
|
|
219
|
+
audienceEntry: {
|
|
220
|
+
kind: "organization";
|
|
221
|
+
} | {
|
|
222
|
+
kind: "user";
|
|
223
|
+
userId: string;
|
|
224
|
+
} | {
|
|
225
|
+
coverage: "direct" | "inherited";
|
|
226
|
+
groupId: string;
|
|
227
|
+
kind: "group";
|
|
228
|
+
} | {
|
|
229
|
+
kind: "profile";
|
|
230
|
+
profileId: string;
|
|
231
|
+
} | {
|
|
232
|
+
applicationId: string;
|
|
233
|
+
kind: "application";
|
|
234
|
+
} | {
|
|
235
|
+
applicationId: string;
|
|
236
|
+
kind: "anonymous";
|
|
237
|
+
} | {
|
|
238
|
+
capabilityId: string;
|
|
239
|
+
kind: "capability";
|
|
240
|
+
mode: "manage" | "on" | "read";
|
|
241
|
+
};
|
|
242
|
+
policies: Array<{
|
|
243
|
+
grants: Array<{
|
|
244
|
+
grantId: string;
|
|
245
|
+
profileId: string;
|
|
246
|
+
}>;
|
|
247
|
+
policy: {
|
|
248
|
+
fqn: string;
|
|
249
|
+
id: string;
|
|
250
|
+
kind: "dataset_data_policy";
|
|
251
|
+
} | {
|
|
252
|
+
id: string;
|
|
253
|
+
kind: "core_admin" | "core_default" | "core_tenant";
|
|
254
|
+
};
|
|
255
|
+
}>;
|
|
256
|
+
readableFields: Array<string> | null;
|
|
257
|
+
rowRule: {
|
|
258
|
+
kind: "all";
|
|
259
|
+
} | {
|
|
260
|
+
filter: Suspend1;
|
|
261
|
+
kind: "filter";
|
|
262
|
+
};
|
|
263
|
+
} | {
|
|
264
|
+
datasetId: string;
|
|
265
|
+
kind: "dataset";
|
|
266
|
+
admitted: false;
|
|
267
|
+
reason: "not_in_audience";
|
|
268
|
+
} | {
|
|
269
|
+
datasetId: string;
|
|
270
|
+
kind: "dataset";
|
|
271
|
+
admitted: false;
|
|
272
|
+
audienceEntry: {
|
|
273
|
+
kind: "organization";
|
|
274
|
+
} | {
|
|
275
|
+
kind: "user";
|
|
276
|
+
userId: string;
|
|
277
|
+
} | {
|
|
278
|
+
coverage: "direct" | "inherited";
|
|
279
|
+
groupId: string;
|
|
280
|
+
kind: "group";
|
|
281
|
+
} | {
|
|
282
|
+
kind: "profile";
|
|
283
|
+
profileId: string;
|
|
284
|
+
} | {
|
|
285
|
+
applicationId: string;
|
|
286
|
+
kind: "application";
|
|
287
|
+
} | {
|
|
288
|
+
applicationId: string;
|
|
289
|
+
kind: "anonymous";
|
|
290
|
+
} | {
|
|
291
|
+
capabilityId: string;
|
|
292
|
+
kind: "capability";
|
|
293
|
+
mode: "manage" | "on" | "read";
|
|
294
|
+
};
|
|
295
|
+
reason: "no_active_revision" | "no_policy";
|
|
296
|
+
} | {
|
|
297
|
+
datasetId: string;
|
|
298
|
+
kind: "dataset";
|
|
299
|
+
admitted: false;
|
|
300
|
+
audienceEntry: {
|
|
301
|
+
kind: "organization";
|
|
302
|
+
} | {
|
|
303
|
+
kind: "user";
|
|
304
|
+
userId: string;
|
|
305
|
+
} | {
|
|
306
|
+
coverage: "direct" | "inherited";
|
|
307
|
+
groupId: string;
|
|
308
|
+
kind: "group";
|
|
309
|
+
} | {
|
|
310
|
+
kind: "profile";
|
|
311
|
+
profileId: string;
|
|
312
|
+
} | {
|
|
313
|
+
applicationId: string;
|
|
314
|
+
kind: "application";
|
|
315
|
+
} | {
|
|
316
|
+
applicationId: string;
|
|
317
|
+
kind: "anonymous";
|
|
318
|
+
} | {
|
|
319
|
+
capabilityId: string;
|
|
320
|
+
kind: "capability";
|
|
321
|
+
mode: "manage" | "on" | "read";
|
|
322
|
+
};
|
|
323
|
+
reason: "not_lowerable";
|
|
324
|
+
refusal: {
|
|
325
|
+
detail: string;
|
|
326
|
+
policyId: string;
|
|
327
|
+
reason: "operator" | "json_field" | "unknown_field" | "literal_type" | "operand" | "value_limit";
|
|
328
|
+
};
|
|
329
|
+
} | {
|
|
330
|
+
collectionId: string;
|
|
331
|
+
kind: "collection";
|
|
332
|
+
admitted: true;
|
|
333
|
+
audienceEntry: {
|
|
334
|
+
kind: "organization";
|
|
335
|
+
} | {
|
|
336
|
+
kind: "user";
|
|
337
|
+
userId: string;
|
|
338
|
+
} | {
|
|
339
|
+
coverage: "direct" | "inherited";
|
|
340
|
+
groupId: string;
|
|
341
|
+
kind: "group";
|
|
342
|
+
} | {
|
|
343
|
+
kind: "profile";
|
|
344
|
+
profileId: string;
|
|
345
|
+
} | {
|
|
346
|
+
applicationId: string;
|
|
347
|
+
kind: "application";
|
|
348
|
+
} | {
|
|
349
|
+
applicationId: string;
|
|
350
|
+
kind: "anonymous";
|
|
351
|
+
} | {
|
|
352
|
+
capabilityId: string;
|
|
353
|
+
kind: "capability";
|
|
354
|
+
mode: "manage" | "on" | "read";
|
|
355
|
+
};
|
|
356
|
+
opens: {
|
|
357
|
+
kind: "all";
|
|
358
|
+
} | {
|
|
359
|
+
folderIds: Array<string>;
|
|
360
|
+
kind: "folders";
|
|
361
|
+
};
|
|
362
|
+
policies: Array<{
|
|
363
|
+
folderId: string | null;
|
|
364
|
+
id: string;
|
|
365
|
+
kind: "core_admin" | "core_default" | "core_tenant" | "document_data_policy";
|
|
366
|
+
}>;
|
|
367
|
+
} | {
|
|
368
|
+
collectionId: string;
|
|
369
|
+
kind: "collection";
|
|
370
|
+
admitted: false;
|
|
371
|
+
reason: "not_in_audience";
|
|
372
|
+
} | {
|
|
373
|
+
collectionId: string;
|
|
374
|
+
kind: "collection";
|
|
375
|
+
admitted: false;
|
|
376
|
+
audienceEntry: {
|
|
377
|
+
kind: "organization";
|
|
378
|
+
} | {
|
|
379
|
+
kind: "user";
|
|
380
|
+
userId: string;
|
|
381
|
+
} | {
|
|
382
|
+
coverage: "direct" | "inherited";
|
|
383
|
+
groupId: string;
|
|
384
|
+
kind: "group";
|
|
385
|
+
} | {
|
|
386
|
+
kind: "profile";
|
|
387
|
+
profileId: string;
|
|
388
|
+
} | {
|
|
389
|
+
applicationId: string;
|
|
390
|
+
kind: "application";
|
|
391
|
+
} | {
|
|
392
|
+
applicationId: string;
|
|
393
|
+
kind: "anonymous";
|
|
394
|
+
} | {
|
|
395
|
+
capabilityId: string;
|
|
396
|
+
kind: "capability";
|
|
397
|
+
mode: "manage" | "on" | "read";
|
|
398
|
+
};
|
|
399
|
+
reason: "no_policy";
|
|
174
400
|
};
|
|
175
401
|
};
|
|
176
402
|
export type AccessExplainRequest = {
|
|
@@ -196,6 +422,12 @@ export type AccessExplainRequest = {
|
|
|
196
422
|
kind: "record";
|
|
197
423
|
operation: "read" | "write";
|
|
198
424
|
recordId: string;
|
|
425
|
+
} | {
|
|
426
|
+
datasetId: string;
|
|
427
|
+
kind: "dataset";
|
|
428
|
+
} | {
|
|
429
|
+
collectionId: string;
|
|
430
|
+
kind: "collection";
|
|
199
431
|
};
|
|
200
432
|
};
|
|
201
433
|
export type AccessGrantAxis = {
|
|
@@ -512,6 +744,20 @@ export type AccessMemberPage = {
|
|
|
512
744
|
items: Array<AccessMember>;
|
|
513
745
|
next: string | null;
|
|
514
746
|
};
|
|
747
|
+
export type AccessMemberHoldersRequest = {
|
|
748
|
+
axis: string;
|
|
749
|
+
profile: string | {
|
|
750
|
+
id: string;
|
|
751
|
+
};
|
|
752
|
+
value: {
|
|
753
|
+
knowledgeEntity: {
|
|
754
|
+
field: string;
|
|
755
|
+
value: string;
|
|
756
|
+
};
|
|
757
|
+
} | string;
|
|
758
|
+
after?: string;
|
|
759
|
+
limit?: number;
|
|
760
|
+
};
|
|
515
761
|
export type ExternalApplicationsGetContextErrors = {
|
|
516
762
|
/**
|
|
517
763
|
* Error
|
|
@@ -618,6 +864,7 @@ export type ApplicationAccessMembersListData = {
|
|
|
618
864
|
after?: string;
|
|
619
865
|
email?: string;
|
|
620
866
|
limit?: string;
|
|
867
|
+
name?: string;
|
|
621
868
|
};
|
|
622
869
|
url: "/application/v1/access/members";
|
|
623
870
|
};
|
|
@@ -631,6 +878,16 @@ export type ApplicationAccessMembersCreateData = {
|
|
|
631
878
|
query?: never;
|
|
632
879
|
url: "/application/v1/access/members";
|
|
633
880
|
};
|
|
881
|
+
export type ApplicationAccessMembersListHoldersData = {
|
|
882
|
+
body: AccessMemberHoldersRequest;
|
|
883
|
+
headers: {
|
|
884
|
+
authorization?: string;
|
|
885
|
+
"x-organization-id": string;
|
|
886
|
+
};
|
|
887
|
+
path?: never;
|
|
888
|
+
query?: never;
|
|
889
|
+
url: "/application/v1/access/members/holders";
|
|
890
|
+
};
|
|
634
891
|
export type ApplicationAccessMembersDeleteData = {
|
|
635
892
|
body?: never;
|
|
636
893
|
headers: {
|
|
@@ -1787,6 +2044,7 @@ declare const createApplicationAccessApi: (client: Client$1) => {
|
|
|
1787
2044
|
members: {
|
|
1788
2045
|
create: (options: EndpointOptions<Options$1<ApplicationAccessMembersCreateData, false, unknown>>) => Promise<AccessMemberCreated>;
|
|
1789
2046
|
get: (options: EndpointOptions<Options$1<ApplicationAccessMembersGetData, false, unknown>>) => Promise<AccessMember>;
|
|
2047
|
+
holders: (options: EndpointOptions<Options$1<ApplicationAccessMembersListHoldersData, false, unknown>>) => Promise<AccessMemberPage>;
|
|
1790
2048
|
list: (options: EndpointOptions<Options$1<ApplicationAccessMembersListData, false, unknown>>) => Promise<AccessMemberPage>;
|
|
1791
2049
|
remove: (options: EndpointOptions<Options$1<ApplicationAccessMembersDeleteData, false, unknown>>) => Promise<void>;
|
|
1792
2050
|
resume: (options: EndpointOptions<Options$1<ApplicationAccessMembersResumeData, false, unknown>>) => Promise<void>;
|
|
@@ -1901,8 +2159,9 @@ export interface ServerAccessService {
|
|
|
1901
2159
|
/**
|
|
1902
2160
|
* Members and guests. `create` needs `admin.grants` at manage and Grant
|
|
1903
2161
|
* Authority over each grant; reads need `admin.users` at read for
|
|
1904
|
-
* members and `admin.guests` at read for guests;
|
|
1905
|
-
*
|
|
2162
|
+
* members and `admin.guests` at read for guests; `holders` also needs
|
|
2163
|
+
* `admin.grants` at read; changes need the same at manage. An app server
|
|
2164
|
+
* sees and changes only the guests it created.
|
|
1906
2165
|
*/
|
|
1907
2166
|
readonly members: Readonly<{
|
|
1908
2167
|
create: Method<WithBody<Api["members"]["create"]>, Api["members"]["create"]>;
|
|
@@ -1911,6 +2170,15 @@ export interface ServerAccessService {
|
|
|
1911
2170
|
email: string;
|
|
1912
2171
|
}>, ServerAccessMember | null>;
|
|
1913
2172
|
get: Method<WithPath<Api["members"]["get"]>, Api["members"]["get"]>;
|
|
2173
|
+
/**
|
|
2174
|
+
* The members that hold the profile (FQN or `{ id }`) on the Axis Value
|
|
2175
|
+
* of the Grant Axis `axis` (its slug) or on a value below it, through
|
|
2176
|
+
* their own or a Group grant; a grant above the value holds nothing
|
|
2177
|
+
* there. A suspended member is listed with `suspended: true`. A page in
|
|
2178
|
+
* user id order; pass `next` as `after` for the next.
|
|
2179
|
+
*/
|
|
2180
|
+
holders: Method<WithBody<Api["members"]["holders"]>, Api["members"]["holders"]>;
|
|
2181
|
+
/** A page of members, by `email`, or by a `name` that holds the text without case; pass `next` as `after` for the next. */
|
|
1914
2182
|
list: Method<ServerAccessContext & QueryOf<Api["members"]["list"]>, Api["members"]["list"]>;
|
|
1915
2183
|
remove: Method<WithPath<Api["members"]["remove"]>, Api["members"]["remove"]>;
|
|
1916
2184
|
resume: Method<WithPath<Api["members"]["resume"]>, Api["members"]["resume"]>;
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{ServerAccessError2,MemberSessionExchangeError2,CiError2,CiTransportError2,FederatedAuthError2,serverSdkRuntime2,createServerClient2,exchangeMemberSession2,runAsApplication2,uuidV72}from"./chunks/index-
|
|
1
|
+
import{ServerAccessError2,MemberSessionExchangeError2,CiError2,CiTransportError2,FederatedAuthError2,serverSdkRuntime2,createServerClient2,exchangeMemberSession2,runAsApplication2,uuidV72}from"./chunks/index-hzx6hj46.js";var CiError=CiError2;var ServerAccessError=ServerAccessError2;var CiTransportError=CiTransportError2;var FederatedAuthError=FederatedAuthError2;export{CiError,CiTransportError,FederatedAuthError,MemberSessionExchangeError2 as MemberSessionExchangeError,ServerAccessError,createServerClient2 as createServerClient,exchangeMemberSession2 as exchangeMemberSession,runAsApplication2 as runAsApplication,serverSdkRuntime2 as serverSdkRuntime,uuidV72 as uuidV7};
|
package/docs/guide/ai/index.md
CHANGED
|
@@ -2,17 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
Tools, Skills, Agents, workflows and Studio chat, how they compose, and how audiences, approvals, models, runs and timeouts behave.
|
|
4
4
|
|
|
5
|
-
The `next-effect-app` template ships two AI features. Its Lead qualifier Agent scores how ready a Lead is to convert, and its convert-lead workflow
|
|
5
|
+
The `next-effect-app` template ships two AI features. Its Lead qualifier Agent scores how ready a Lead is to convert, and its convert-lead workflow is the smallest workflow that the web app can start. That workflow only sets a workflow variable and writes no Lead record, so it is a starting point for your own steps. Both are built from the same small set of AI primitives, and a new demo feature usually starts as a copy of one of them. This page explains each primitive through those two features and ends with a table that helps you choose between them.
|
|
6
6
|
|
|
7
7
|
## The building blocks
|
|
8
8
|
|
|
9
|
-
| Building block | What it is | Model inside | How it starts
|
|
10
|
-
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
|
|
11
|
-
| Tool | A typed, callable capability, such as a Knowledge query, a message send, a web search or your own package code. Tools are grouped in tool collections. | No | A Skill, an Agent, a workflow node or a chat turn calls it.
|
|
12
|
-
| Skill | Versioned instructions with model settings, permissions and a bounded set of tools, for one AI task. | Yes | Studio chat, a Studio Skill Form, the public Skill API, MCP, a workflow Skill node, or an Agent that holds it.
|
|
13
|
-
| Agent | An Organization-owned actor with a Role, held Skills, its own tools and an optional typed output. | Yes | Your server invokes it, a
|
|
14
|
-
| Workflow | A durable graph of steps with triggers, versions, runs, pauses and approvals. | Only in Prompt and Skill nodes | A trigger fires: webhook, schedule, Knowledge record event, external application, MCP operation or on demand.
|
|
15
|
-
| Studio chat | The
|
|
9
|
+
| Building block | What it is | Model inside | How it starts |
|
|
10
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| Tool | A typed, callable capability, such as a Knowledge query, a message send, a web search or your own package code. Tools are grouped in tool collections. | No | A Skill, an Agent, a workflow node or a chat turn calls it. |
|
|
12
|
+
| Skill | Versioned instructions with model settings, permissions and a bounded set of tools, for one AI task. | Yes | Studio chat, a Studio Skill Form, the public Skill API, MCP, a workflow Skill node, or an Agent that holds it. |
|
|
13
|
+
| Agent | An Organization-owned actor with a Role, held Skills, its own tools and an optional typed output. | Yes | Your server invokes it, a person talks to it in Studio, or an event or a delegation from another Agent starts it. |
|
|
14
|
+
| Workflow | A durable graph of steps with triggers, versions, runs, pauses and approvals. | Only in Prompt and Skill nodes | A trigger fires: webhook, schedule, Knowledge record event, external application, MCP operation or on demand. |
|
|
15
|
+
| Studio chat | The conversation in [Studio](studio.md) in which Organization members use the agents, tools and Skills offered to them. | Yes | A member sends a message. |
|
|
16
16
|
|
|
17
17
|
The template's Lead qualifier composes three of these. A package declares the Lead score tool, a Lead scoring Skill that binds it, and an Agent that holds the Skill and is offered to the external application:
|
|
18
18
|
|
|
@@ -67,7 +67,7 @@ declareTool({
|
|
|
67
67
|
|
|
68
68
|
`usageScopes` decides where the tool can appear: in a Skill, in chat, or in automation. The template needs `automation` so that the Lead qualifier Agent can use the tool. When you omit `usageScopes`, the tool appears in all three places, and an explicit empty list makes it unavailable everywhere. The model reads `toolGuidance.useWhen` and `toolGuidance.inputRequirementsSummary` to decide when to call the tool and what to pass, so write both for the model.
|
|
69
69
|
|
|
70
|
-
A
|
|
70
|
+
A package can also bind built-in tools for web search (Exa or Tavily, which need an API key), website scraping, image generation, email, notifications, OCR, speech transcription and synthesis, and report building. External applications can use `publish-run-event`.
|
|
71
71
|
|
|
72
72
|
## Skills
|
|
73
73
|
|
|
@@ -84,7 +84,7 @@ Score one Lead with the Lead score tool. Never guess a score.
|
|
|
84
84
|
`
|
|
85
85
|
```
|
|
86
86
|
|
|
87
|
-
The package passes these instructions to `declareSkill({ definition: { audience, instructions, lifecycle, tools } })`, and the template's `tools` list holds only the Lead score tool. CI stores each Skill as a versioned package, and runtime always uses the active approved version.
|
|
87
|
+
The package passes these instructions to `declareSkill({ definition: { audience, instructions, lifecycle, uses: { tools } } })`, and the template's `uses.tools` list holds only the Lead score tool. CI stores each Skill as a versioned package, and runtime always uses the active approved version.
|
|
88
88
|
|
|
89
89
|
The same Skill can run in Studio chat, in a Studio Skill Form, through the public Skill API (`skills_invoke`, then `runs_get` or `runs_stream`), through MCP `run_skill`, in a workflow Skill node, and inside an Agent that holds it. A Skill version can pin a model. Without a pin, it uses the model that the running Organization sets for Skill turns, which defaults to the `balanced` tier. A pinned model that does not resolve is a configuration error, and CI does not fall back to another model.
|
|
90
90
|
|
|
@@ -122,9 +122,9 @@ Held Skills load on demand. At first the Agent sees only the catalog. When it ca
|
|
|
122
122
|
|
|
123
123
|
`output: { schema }` takes a codec, so the app can keep one runtime schema in its contracts package. A succeeded run returns `{ message, output? }`. `message` is the final answer, and `output` is the structured Agent Output, already valid against the schema. `output` is absent when the run saved none, for example when the Agent asked a clarifying question.
|
|
124
124
|
|
|
125
|
-
An Agent without `activity` is idle and runs only when something triggers it: an invoke call, a conversation turn, an event or a delegation. `activity: { heartbeat, schedule }
|
|
125
|
+
An Agent without `activity` is idle and runs only when something triggers it: an invoke call, a conversation turn, an event or a delegation. The SDK also accepts `activity: { heartbeat, schedule }`. Before a demo depends on a package Agent that runs on a schedule or a heartbeat, confirm it with one trial run. Every Agent that a package declares is an Organization Agent.
|
|
126
126
|
|
|
127
|
-
FQN string references are not type-checked when you build. Install resolves them and rolls the package back when one is missing: each held Skill must be approved, each Agent or Skill tool must be an enabled tool of the Organization, and each audience reference must exist. Only
|
|
127
|
+
FQN string references are not type-checked when you build. Install resolves them and rolls the package back when one is missing: each held Skill must be approved, each Agent or Skill tool must be an enabled tool of the Organization, and each audience reference must exist. Only a person can install a package that declares Agents or Skills; an install with no signed-in user fails.
|
|
128
128
|
|
|
129
129
|
## Audiences
|
|
130
130
|
|
|
@@ -167,7 +167,7 @@ uses: {
|
|
|
167
167
|
|
|
168
168
|
`name`, `description` and `approval` work the same way for every tool. The model sees the Binding Description in place of the tool's own description. `settings` holds the tool's own options, and the tool's Binding Settings Form defines them, so install fails on a key that the form does not define. A field that the form marks with `x-fqn-of` takes FQNs, and install translates each FQN into the id of the installing Organization's record. Install fails when an FQN names no record of that Organization, and the error names every such FQN of the binding. A binding has no tool-specific property.
|
|
169
169
|
|
|
170
|
-
`approval` has three modes. `"never"` makes no approval request for the binding. `"always"` pauses for an explicit decision by the user who started the call, and that user's eligibility to approve does not approve the call. `{ rule: "<rule name>" }` uses an approval rule of the installing Organization, with that rule's reviewers and expiry. Install fails when no rule has the name, so create the rule in the target Organization before you install a
|
|
170
|
+
`approval` has three modes. `"never"` makes no approval request for the binding. `"always"` pauses for an explicit decision by the user who started the call, and that user's eligibility to approve does not approve the call. `{ rule: "<rule name>" }` uses an approval rule of the installing Organization, with that rule's reviewers and expiry. Install fails when no rule has the name, so create the rule in the target Organization before you install a package that uses one.
|
|
171
171
|
|
|
172
172
|
Approval pauses the call and leaves the tool visible. With `"always"`, the model still sees the tool definition and can decide to call it, and the call then waits for a person.
|
|
173
173
|
|
|
@@ -190,7 +190,7 @@ The same binding behaves differently for each kind of caller:
|
|
|
190
190
|
|
|
191
191
|
An approval authorizes one attempt. It does not check the tool input and cannot make the call succeed: an approved Knowledge Query `search` call still fails when it has no `entitySchemaId`.
|
|
192
192
|
|
|
193
|
-
The reviewer never becomes the identity that runs the tool. After approval, the call resumes as the
|
|
193
|
+
The reviewer never becomes the identity that runs the tool. After approval, the call resumes as the identity that started it, which can be a person, a service principal or an app server. CI rechecks that identity's current Organization authority, so a changed action, a rejection, an expiry or revoked access blocks the call. When the recipients or destination of a send change between approval and send, CI does not send. It opens a fresh approval request under the same identity, and that request needs a new decision. Reviewers see the facts of the pending action in Studio Notifications. CI freezes those facts when the request opens and shows secrets as omitted.
|
|
194
194
|
|
|
195
195
|
## Models
|
|
196
196
|
|
|
@@ -257,7 +257,25 @@ Its one action node sets a fixed patch and declares how it behaves on dry runs,
|
|
|
257
257
|
}
|
|
258
258
|
```
|
|
259
259
|
|
|
260
|
-
A
|
|
260
|
+
A workflow with a trigger needs a run-as service principal, and CI publishes it only with one. The template declares `servicePrincipal({ fqn: convertLeadRunnerFqn, groups: [], name: "Convert lead runner", version })` and selects it with `runIdentity: { mode: "service_principal", servicePrincipal: convertLeadRunnerFqn }` on the workflow.
|
|
261
|
+
|
|
262
|
+
### Who a run acts as
|
|
263
|
+
|
|
264
|
+
Every tool call in a run uses the current grants of the identity that the run acts as. A workflow's `runIdentity` decides that identity for a person's start. In `triggering_user` mode, the default, the run acts as the person who starts it. In `service_principal` mode, a production run that a person starts from Studio or the Dashboard acts as the workflow's run-as service principal. A test run from the workflow editor always keeps its author's identity. A workflow that runs with no person, from a schedule, an event or an app call in service mode, needs `service_principal` mode, and CI refuses to publish an Organization workflow whose schedule or event trigger has no identity to run as.
|
|
265
|
+
|
|
266
|
+
| How the run starts | The run acts as |
|
|
267
|
+
| --------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
268
|
+
| A Studio trigger form, or Run in the Dashboard, in `triggering_user` mode | The signed-in person |
|
|
269
|
+
| A Studio trigger form, or Run in the Dashboard, in `service_principal` mode | The run-as service principal |
|
|
270
|
+
| A test run from the workflow editor | The author |
|
|
271
|
+
| An external application call with the user's delegated token | The signed-in user |
|
|
272
|
+
| An external application call in service mode or with `runAsApplication` | The run-as service principal |
|
|
273
|
+
| A schedule, a webhook, a Knowledge record event or an MCP operation | The run-as service principal |
|
|
274
|
+
| An Invoke Workflow node (a child workflow) | The identity of the run that started the child |
|
|
275
|
+
|
|
276
|
+
An external application call with a delegated token acts as the user in both modes. The template's web app calls convert-lead with the user's delegated token, so a convert run from the web app acts as the signed-in Sales manager and not as `convertLeadRunner`, although the workflow is in `service_principal` mode. Agents follow the same rule: an Agent run acts as the person or app that started it, and an Agent that delegates to another Agent passes on that identity. An approval reviewer never becomes the identity of a run.
|
|
277
|
+
|
|
278
|
+
A service principal has no user identity in the tool catalog, which means user-scoped tool bindings never match it. Give it a tool through an Organization binding or through a Group it belongs to.
|
|
261
279
|
|
|
262
280
|
Each trigger has an invocation mode: `attach`, `detach`, or `await_result` with a `timeoutMs`. `detach` answers at once with a durable 202, and `await_result` waits up to its timeout. The convert-lead trigger uses `{ mode: "await_result", timeoutMs: 90_000 }`. The web app starts it from its server with `createFixedWorkflowRoute` from `@collective-intelligence/external-apps-server-sdk/next`. The server owns the workflow FQN, and the browser sends only the Lead id:
|
|
263
281
|
|
|
@@ -338,12 +356,12 @@ const dataAccess = {
|
|
|
338
356
|
| --------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
339
357
|
| Model inside | No | Yes | Yes | Only in Prompt and Skill nodes |
|
|
340
358
|
| Who decides the steps | Your code | The model, guided by the instructions | The model, guided by the Role and held Skills | The graph you build |
|
|
341
|
-
| How it starts | Another primitive or a chat turn calls it | Chat, Skill Form, API, MCP, workflow node or Agent | Your server, a conversation, an event
|
|
359
|
+
| How it starts | Another primitive or a chat turn calls it | Chat, Skill Form, API, MCP, workflow node or Agent | Your server, a Studio conversation, an event or a delegation | Webhook, schedule, record event, external application, MCP or on demand |
|
|
342
360
|
| Human approval | Set on its binding | The run pauses for a decision | Approved by default and recorded | Approval node |
|
|
343
361
|
| Output | Typed by its output schema | The run's result | `message` plus typed `output` | The declared output contract |
|
|
344
362
|
| Pick it when | You need one deterministic, typed action such as score, fetch or send | One AI task with a bounded tool set must run in several places | You need a long-lived Role with an audience, typed output, conversation history or unattended runs | The steps are fixed and you need triggers, approvals or a typed result |
|
|
345
363
|
|
|
346
|
-
Most
|
|
364
|
+
Most features combine these primitives. The Lead qualifier uses a deterministic tool, a Skill that tells the model how to use it, and an Agent that holds the Skill for the external application. Convert-lead is a workflow because its one step is fixed and the web app waits for the result, so it needs no model. When a workflow step needs AI, use a Prompt or Skill node. [Scenarios](../scenarios/index.md) walks through more demo cases.
|
|
347
365
|
|
|
348
366
|
## Not covered here
|
|
349
367
|
|
|
@@ -351,6 +369,7 @@ This page does not cover Personal Agents (admins create them in the Dashboard),
|
|
|
351
369
|
|
|
352
370
|
## Related pages
|
|
353
371
|
|
|
372
|
+
- [Studio](studio.md)
|
|
354
373
|
- [Knowledge](../data/knowledge.md)
|
|
355
374
|
- [Datasets](../data/datasets.md)
|
|
356
375
|
- [Extensions](../develop/extensions.md)
|