@collective-intelligence/extensions-sdk 0.3.2 → 0.3.4
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 +38 -34
- package/dist/access/dataset-policy.d.ts +38 -0
- package/dist/access/index.d.ts +3 -1
- package/dist/access/manifest.d.ts +31 -1
- package/dist/access/readers.d.ts +19 -1
- package/dist/components/base.d.ts +1 -1
- package/dist/components/connector-instances.d.ts +14 -1
- package/dist/components/document-collections.d.ts +9 -1
- package/dist/components/metadata-authoring.d.ts +11 -3
- package/dist/documents.js +2 -2
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -3
- package/dist/package/primitive-readers.d.ts +18 -0
- package/dist/release/stored-manifest.d.ts +16 -4
- 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 +68 -15
- 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 +12 -8
- package/docs/guide/platform/access.md +82 -17
- package/docs/guide/platform/architecture.md +27 -18
- package/docs/guide/platform/entrypoints.md +128 -47
- 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 +2 -2
|
@@ -41,6 +41,24 @@ export declare const primitives: {
|
|
|
41
41
|
lifecycle?: import("../index.js").LifecycleOptions;
|
|
42
42
|
nodes: Readonly<Record<string, import("../index.js").AccessCapabilityNodeDeclaration>>;
|
|
43
43
|
}> & JsonObject>;
|
|
44
|
+
accessDatasetDataPolicy: ReadValue<Readonly<{
|
|
45
|
+
description?: string;
|
|
46
|
+
displayName: string;
|
|
47
|
+
fqn: string;
|
|
48
|
+
icon?: string;
|
|
49
|
+
kind: "accessDatasetDataPolicy";
|
|
50
|
+
tags?: readonly string[];
|
|
51
|
+
version: string;
|
|
52
|
+
}> & Readonly<{
|
|
53
|
+
axes?: readonly import("../index.js").AccessDatasetPolicyAxis[];
|
|
54
|
+
capability: import("../index.js").AccessCapabilityRequirement;
|
|
55
|
+
dataset: string;
|
|
56
|
+
lifecycle?: import("../index.js").LifecycleOptions;
|
|
57
|
+
limits?: import("../index.js").AccessDatasetLimits;
|
|
58
|
+
otherAxes?: "unscoped";
|
|
59
|
+
readableFields?: import("../index.js").AccessFieldSelection;
|
|
60
|
+
where?: import("../index.js").AccessCondition;
|
|
61
|
+
}> & JsonObject>;
|
|
44
62
|
accessDocumentDataPolicy: ReadValue<import("../index.js").AccessDocumentDataPolicyDeclaration>;
|
|
45
63
|
accessGrantAxis: ReadValue<Readonly<{
|
|
46
64
|
description?: string;
|
|
@@ -6,18 +6,30 @@ import type { ExtensionReleaseManifest } from "./manifest.js";
|
|
|
6
6
|
* a Studio App Template stored as `studioApp`.
|
|
7
7
|
*/
|
|
8
8
|
export declare const storedPrimitiveKind: (stored: unknown) => string | undefined;
|
|
9
|
+
/** Options of the stored-release spelling map. */
|
|
10
|
+
export type StoredPrimitiveReadOptions = Readonly<{
|
|
11
|
+
/**
|
|
12
|
+
* Maps the keys renamed with Personal Automations (see `withFormerNames`).
|
|
13
|
+
* Defaults to `true`. A reader of a declaration that is not stored, such as
|
|
14
|
+
* a development declaration, passes `false` so that the manifest reader
|
|
15
|
+
* refuses each former key with `<key> is now <name>`.
|
|
16
|
+
*/
|
|
17
|
+
formerNames?: boolean;
|
|
18
|
+
}>;
|
|
9
19
|
/**
|
|
10
20
|
* Returns one stored primitive declaration with the current spelling that
|
|
11
21
|
* {@link withCurrentPrimitiveKinds} gives each primitive of a stored release.
|
|
12
22
|
* A reader of a stored definition baseline calls it after the digest check.
|
|
13
23
|
*/
|
|
14
|
-
export declare const withCurrentPrimitive: (primitive: JsonObject) => JsonObject;
|
|
24
|
+
export declare const withCurrentPrimitive: (primitive: JsonObject, options?: StoredPrimitiveReadOptions) => JsonObject;
|
|
15
25
|
/**
|
|
16
26
|
* Returns a stored release manifest whose retained primitive declarations use
|
|
17
27
|
* the current spelling: current kind names, a Studio App Template in place of
|
|
18
28
|
* a `studioApp` without the Declared Studio App lifecycle, an Agent `audience` in place of
|
|
19
|
-
* `invokingApplicationFqns` or of the retired audience ceiling,
|
|
20
|
-
*
|
|
29
|
+
* `invokingApplicationFqns` or of the retired audience ceiling, the current
|
|
30
|
+
* names of the keys renamed with Personal Automations (see
|
|
31
|
+
* {@link withFormerNames}), and Organization Group names in place of
|
|
32
|
+
* Organization Team names. Historical
|
|
21
33
|
* Entity Relation Field cardinalities map one/many to many_to_one/many_to_many;
|
|
22
34
|
* valid redundant scalar maxItems is removed. Every other relation setting is
|
|
23
35
|
* retained. Components of a kind retired with Record Relations or with Access
|
|
@@ -28,6 +40,6 @@ export declare const withCurrentPrimitive: (primitive: JsonObject) => JsonObject
|
|
|
28
40
|
* executes the release archive compares the verbatim stored JSON with the
|
|
29
41
|
* archive before it calls this function.
|
|
30
42
|
*/
|
|
31
|
-
export declare const withCurrentPrimitiveKinds: (stored: JsonObject) => JsonObject;
|
|
43
|
+
export declare const withCurrentPrimitiveKinds: (stored: JsonObject, options?: StoredPrimitiveReadOptions) => JsonObject;
|
|
32
44
|
/** Parses an immutable stored release manifest with current primitive spelling. */
|
|
33
45
|
export declare const parseStoredExtensionReleaseManifest: (stored: unknown) => ExtensionReleaseManifest;
|
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)
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
# Studio
|
|
2
|
+
|
|
3
|
+
How Organization members work in the Studio desktop app, how a package ships Studio apps, forms and widgets, and how Studio shares one solution with your external application.
|
|
4
|
+
|
|
5
|
+
Studio is the CI app where the people of an Organization do their work. They chat with agents, use Skills, open Studio apps, fill forms, decide approvals and find Documents. Admins set up the Organization in the Dashboard, and members use what it offers them in Studio. A package can ship a complete Studio app, and the `next-effect-app` template ships one: the Sales desk, which lists the same Leads that the template's web app reads and writes. This page uses the Sales desk as the running example.
|
|
6
|
+
|
|
7
|
+
## Install and connect Studio
|
|
8
|
+
|
|
9
|
+
Studio is a desktop app. Each Organization has a Studio install page in the Dashboard at `/get-studio/<organization-id>`, and nobody types a backend URL:
|
|
10
|
+
|
|
11
|
+
1. Open the install page and pick a platform: macOS (Apple Silicon or Intel), Windows or Linux. The page detects one for you.
|
|
12
|
+
2. Download and install Studio, then keep it open.
|
|
13
|
+
3. Click Connect Studio on the install page. The browser asks to open Collective Intelligence; choose Open.
|
|
14
|
+
4. If the button does not work, click Copy connect link and paste the link in Studio under "Connect button didn't work?".
|
|
15
|
+
|
|
16
|
+
The connect link is signed, and the backend verifies it before Studio stores the connection. When the page says "Studio setup isn't finished for this organization", an Organization admin must complete the Studio setup first.
|
|
17
|
+
|
|
18
|
+
After it connects, Studio shows the Organization's name, cover and logo on its loading and login screens, also offline. Before it opens the workspace, Studio checks the Organization's Stable and Minimum desktop versions, and it saves the open tabs before it installs an update.
|
|
19
|
+
|
|
20
|
+
## Who can open Studio
|
|
21
|
+
|
|
22
|
+
A member uses Studio only through the `studio` entry capability. The built-in Studio user profile holds it, together with the platform capabilities for conversations, agents, Knowledge, workflows, datasets and notifications. A guest acts only through the entry of an external application, so a guest cannot use Studio.
|
|
23
|
+
|
|
24
|
+
> **Warning:** The template's Sales rep and Sales manager profiles do not allow
|
|
25
|
+
> `core.studio`. Before a Sales member can open the Sales desk, check that the
|
|
26
|
+
> member also holds the Studio user profile or another profile that allows
|
|
27
|
+
> `core.studio`. [Access](../platform/access.md) explains profiles and grants.
|
|
28
|
+
|
|
29
|
+
What a person sees inside Studio still follows the grants. A Studio user reads no Knowledge record until a Knowledge Data Policy or a profile opens it, and a Studio app or page with an empty audience is offered to nobody.
|
|
30
|
+
|
|
31
|
+
## What a Studio app holds
|
|
32
|
+
|
|
33
|
+
A Studio app is a set of sections and pages in a left sidebar. Each page holds views. Admins build apps in the Dashboard builder, and a package can declare one. These built-in pages are available to every app:
|
|
34
|
+
|
|
35
|
+
| Page | What it does |
|
|
36
|
+
| --------------- | --------------------------------------------------------------- |
|
|
37
|
+
| Chat | The conversational workspace with agents and Skills |
|
|
38
|
+
| Agents | Lists the agents offered to the person and starts conversations |
|
|
39
|
+
| Skills | Lists the Skills the person can use in chat |
|
|
40
|
+
| Approvals | Lists pending approval decisions |
|
|
41
|
+
| Notifications | Shows Studio notifications, including approval requests |
|
|
42
|
+
| Activity Center | The person's work inbox of activities in progress and done |
|
|
43
|
+
| Documents | Browses, searches and downloads Documents |
|
|
44
|
+
|
|
45
|
+
The built-in views are tabs, a responsive grid, a report, a schema list and a schema entity detail for Knowledge records, a Skill form, a trigger form, an agent form, workflow runs, agent runs and a Dataset area. Their references have the form `builtin:view.<name>`, for example `builtin:view.schema-list`, and pages use `builtin:page.<name>`.
|
|
46
|
+
|
|
47
|
+
## Chat with agents
|
|
48
|
+
|
|
49
|
+
The Agents page lists every agent whose audience includes the person, and each one opens a conversation. When an agent is missing, check its audience first. The template's Lead qualifier has `audience: { applications: [application] }`, so the web app can call it and no Sales member sees it in Studio. To offer it to Sales members too, pass the Sales audience into the agent's declaration and keep the application:
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
declareAgent({
|
|
53
|
+
definition: {
|
|
54
|
+
audience: { ...audience, applications: [application] }
|
|
55
|
+
// ...
|
|
56
|
+
}
|
|
57
|
+
// ...
|
|
58
|
+
})
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The template already passes `audience` (the Sales Group) into `leadQualificationComponents` for the tool and the Skill, so `leadQualifierAgent` needs that parameter as well. A tool binding with an approval mode pauses a chat turn until a person decides. [AI primitives](index.md) explains agents, Skills, tools and approvals in detail.
|
|
62
|
+
|
|
63
|
+
## Ship a Studio app from a package
|
|
64
|
+
|
|
65
|
+
`declareStudioApp` declares a Declared Studio App, which CI creates and publishes when it installs the package. `declareStudioAppTemplate` instead declares a starting point that the builder copies into a new app, and the copy keeps no link to the package. These rules apply to a Declared Studio App:
|
|
66
|
+
|
|
67
|
+
- Its `lifecycle` is always `{ deployMode: "upsert", readonly: true }`, and the SDK refuses other values.
|
|
68
|
+
- The app and each page take an `audience`. Without one, CI offers them to nobody. Sections show while one of their pages is offered, and views follow their page.
|
|
69
|
+
- Studio never shows a page that the person cannot access, and it shows no empty placeholder for it.
|
|
70
|
+
- A later release finds the app by its FQN, so a new slug moves the same app.
|
|
71
|
+
- A missing workflow, trigger, agent, schema, component or audience reference makes the install write nothing.
|
|
72
|
+
- The builder shows the app as package-owned and read-only. Change it through a new release.
|
|
73
|
+
- An uninstall disables the app, and a new install enables it again.
|
|
74
|
+
|
|
75
|
+
The Sales desk has one section and one Leads page, offered to the Sales Group. The page places a Knowledge schema list and the Lead score card widget, both bound to the Lead schema:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
export const salesDeskApp = declareStudioApp({
|
|
79
|
+
definition: {
|
|
80
|
+
audience: salesMembers,
|
|
81
|
+
definition: {
|
|
82
|
+
name: "Sales desk",
|
|
83
|
+
slug: "acme-sales-desk",
|
|
84
|
+
sections: [
|
|
85
|
+
{
|
|
86
|
+
fqn: `${salesDeskAppFqn}.sections.sales`,
|
|
87
|
+
label: "Sales",
|
|
88
|
+
slug: "sales",
|
|
89
|
+
orderIndex: 0,
|
|
90
|
+
pages: [
|
|
91
|
+
{
|
|
92
|
+
audience: salesMembers,
|
|
93
|
+
fqn: `${salesDeskAppFqn}.pages.leads`,
|
|
94
|
+
label: "Leads",
|
|
95
|
+
slug: "leads",
|
|
96
|
+
kind: "generic",
|
|
97
|
+
routeSegment: "leads",
|
|
98
|
+
orderIndex: 0,
|
|
99
|
+
// No `mutations`: the list is read-only; the web app writes Leads.
|
|
100
|
+
views: [
|
|
101
|
+
{
|
|
102
|
+
componentRef: "builtin:view.schema-list",
|
|
103
|
+
dataBinding: { kind: "schema", schema: leadSchemaFqn },
|
|
104
|
+
fqn: `${salesDeskAppFqn}.views.leads-list`,
|
|
105
|
+
orderIndex: 0,
|
|
106
|
+
slot: "main"
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
componentRef: leadScoreCardComponentFqn,
|
|
110
|
+
dataBinding: { kind: "schema", schema: leadSchemaFqn },
|
|
111
|
+
fqn: `${salesDeskAppFqn}.views.lead-score`,
|
|
112
|
+
orderIndex: 1,
|
|
113
|
+
slot: "main"
|
|
114
|
+
}
|
|
115
|
+
]
|
|
116
|
+
}
|
|
117
|
+
]
|
|
118
|
+
}
|
|
119
|
+
]
|
|
120
|
+
},
|
|
121
|
+
lifecycle: { deployMode: "upsert", readonly: true }
|
|
122
|
+
},
|
|
123
|
+
manifest: { fqn: salesDeskAppFqn, version: VERSION },
|
|
124
|
+
presentation: {
|
|
125
|
+
displayName: "Sales desk",
|
|
126
|
+
description: "Leads of the Acme CRM with the Lead score card."
|
|
127
|
+
}
|
|
128
|
+
})
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
To let Sales members edit Leads in Studio, set `props.mutations.create`, `update` or `delete` on the schema list to `true`. A schema entity detail view becomes editable when `update` is on. Each write still passes the Lead write policy, which in the template requires CRM `manage`.
|
|
132
|
+
|
|
133
|
+
## Forms
|
|
134
|
+
|
|
135
|
+
Three built-in views collect input and start a run. Each one runs as the Studio user who submits it:
|
|
136
|
+
|
|
137
|
+
| Form | Declared with | What it runs |
|
|
138
|
+
| ----------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
139
|
+
| Trigger form, `builtin:view.trigger-form` | `withStudioTriggerForm(trigger, { organizationGroup, fields })` on an On-demand trigger | The workflow, once every field holds a valid value |
|
|
140
|
+
| Agent form, `builtin:view.agent-form` | `withStudioAgentForm(agent, { fields })` | The declared agent, with the field values as its task |
|
|
141
|
+
| Skill form, `builtin:view.skill-form` | The Dashboard builder | One Skill with structured input |
|
|
142
|
+
|
|
143
|
+
### Trigger form fields
|
|
144
|
+
|
|
145
|
+
A trigger form shows and runs only for members of its `organizationGroup`, including subgroups. Its fields can be `text`, `textarea`, `number`, `boolean`, `enum`, `json` with a JSON Schema, `rich_text`, `file` (PDF, JPEG or PNG up to 10 MiB by default), `entities` (Knowledge records of one schema that the person can read) and `user_select` (Organization members). Workflow nodes read a value as `{{ trigger.form.<key> }}`. A link can open the form prefilled through the query parameter `prefill.<triggerRef>`, so put no secrets in such a link.
|
|
146
|
+
|
|
147
|
+
### Agent forms
|
|
148
|
+
|
|
149
|
+
An agent form names its agent by FQN in `props.agentRef` and runs it inline within the agent's audience. The optional `props.resultWidget` names a widget that renders the agent's output. Agent form fields of type `file` or `entities` have no input yet: the view shows "This field cannot be filled in an agent form yet." and keeps Run disabled.
|
|
150
|
+
|
|
151
|
+
### Form runs and approvals
|
|
152
|
+
|
|
153
|
+
A run from an agent form or a Skill form keeps its history, result, follow-ups, retries, cancellation and approvals together. A Skill form set to `ask_always` asks a person to approve every installed tool call, even on bindings set to `never`, and `automatic` skips approval. The other authorization checks still apply.
|
|
154
|
+
|
|
155
|
+
## Run lists, Documents and datasets
|
|
156
|
+
|
|
157
|
+
The workflow runs view (`props.workflows`) and the agent runs view (`props.agents`) list the runs of the workflows or agents they name, for the people who can see the view. A retry starts a new run as the person who retries it, with the original input. A workflow retry needs an On-demand trigger on that version. The lists show status, times and error codes, and never inputs, outputs or messages.
|
|
158
|
+
|
|
159
|
+
The Documents page is a finder. A person browses the Document Collections and folders they can read, searches filenames and document content in one field, downloads the stored file of a Document Version, or opens a cloud file in its Microsoft or Google app. Studio has no built-in document viewer. [Documents](../data/documents.md) explains collections and versions.
|
|
160
|
+
|
|
161
|
+
The Dataset area lists the datasets a person can see, with each dataset's definition, policy, health, freshness and lineage. Its query workspace offers only the fields and operations that the dataset policy allows, and the create panel appears only for a person who can administer datasets. [Datasets](../data/datasets.md) explains the policies.
|
|
162
|
+
|
|
163
|
+
## Approvals
|
|
164
|
+
|
|
165
|
+
The Approvals page lists the decisions that wait for the person. A notification for an approval shows the facts of the pending action, such as what it sends, to whom, and which Skill or workflow asks. CI freezes those facts when the request opens and shows secrets as omitted. The reviewer decides and never becomes the identity that runs the call.
|
|
166
|
+
|
|
167
|
+
## Widgets from packages
|
|
168
|
+
|
|
169
|
+
A widget is a React component that a package ships and a Studio page places. The template's Lead score card needs four pieces:
|
|
170
|
+
|
|
171
|
+
1. A backend declaration in the package's `components`: `declareStudioComponent` with `category: "widget"`, a `propsSchema` and a `sourceRef` that names the package's Studio contribution.
|
|
172
|
+
2. A frontend declaration: `declareFrontendComponent` with a `load` callback and a `studio_component` target, returned by the package's `loadFrontendCatalog`.
|
|
173
|
+
3. A hosted contribution for the Studio host in `declarePackage({ hostedContributions })`.
|
|
174
|
+
4. A view of a Studio app that places the widget by its FQN in `componentRef`, as the Sales desk does.
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
declareFrontendCatalogContribution({
|
|
178
|
+
compatibility: { react: "^19.0.0" },
|
|
179
|
+
fqn: leadScoreCardContributionFqn,
|
|
180
|
+
host: "studio",
|
|
181
|
+
load: async () => await import("./studio")
|
|
182
|
+
})
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Every placed widget gets a `context` prop with the app, page, view and published revision ids. The prop is `null` in the builder preview and before the app is published, so a widget renders an inert state then. The Lead score card shows a Preview badge in that case.
|
|
186
|
+
|
|
187
|
+
A widget holds no CI credentials. It calls CI through the Studio API client from `@collective-intelligence/extensions-sdk-frontend-react/studio-api`, which Studio binds to its own signed-in connection, so each request runs with the signed-in person's permissions. The client covers the view-data search, read and update calls and the reads of the two run-list views. The Lead score card reads the Leads of its own view:
|
|
188
|
+
|
|
189
|
+
```tsx
|
|
190
|
+
const leads = useQuery({
|
|
191
|
+
...studioViewDataSearchOptions({
|
|
192
|
+
...studioViewScope(context),
|
|
193
|
+
body: { limit: SEARCH_LIMIT }
|
|
194
|
+
}),
|
|
195
|
+
select: leadsOf
|
|
196
|
+
})
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
A widget writes through a `fromEffect` XState actor from `@collective-intelligence/extensions-sdk-frontend-react/effect` and mounts `EffectRuntimeProvider` at its root. Package widgets render in the Studio desktop app, which downloads and verifies the package release.
|
|
200
|
+
|
|
201
|
+
> **Note:** The Lead score card shows the stored `score` field of each Lead, or "Not
|
|
202
|
+
> scored yet" when the field is empty. People set that field in the web app's
|
|
203
|
+
> Lead form. The card runs no agent, and nothing in the template writes the Lead
|
|
204
|
+
> qualifier's score back to the Lead.
|
|
205
|
+
|
|
206
|
+
> **Warning:** An install of a package with a Studio contribution waits until a Studio
|
|
207
|
+
> desktop app of that Organization reports the release ready. A pipeline has no
|
|
208
|
+
> Studio, so pass `--skip-studio-readiness` to `ci deploy`, as the template
|
|
209
|
+
> does. A Studio that connects later loads the release then.
|
|
210
|
+
|
|
211
|
+
## Studio and your external application
|
|
212
|
+
|
|
213
|
+
The template's package installs everything that Studio and the web app share. Studio people and web app users are the same CI users, and both sides read the same Lead records:
|
|
214
|
+
|
|
215
|
+
```mermaid
|
|
216
|
+
flowchart LR
|
|
217
|
+
pkg["Extension package"] -->|installs| org["Organization"]
|
|
218
|
+
org --> desk["Sales desk in Studio"]
|
|
219
|
+
org --> app["External application and BFF"]
|
|
220
|
+
desk -->|reads| leads["Lead records"]
|
|
221
|
+
app -->|reads and writes| leads
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
One `ci deploy` installs the Lead schema, the Sales Group and its grants, the external application, the convert-lead workflow, the Lead qualifier with its Skill and tool, and the Sales desk with its widget. The Sales Group's grants decide what a Sales member does in the web app, and the same Group is the audience of the Sales desk. A Lead that a Sales manager edits in the web app is the record that the Sales desk lists. The web app cuts each user's access to the application's Max Privileges, and Studio sessions have no such cut, so the same person can see more in Studio than through the app.
|
|
225
|
+
|
|
226
|
+
Workflows and agents can start from either side:
|
|
227
|
+
|
|
228
|
+
| Primitive | From the web app | From Studio |
|
|
229
|
+
| --------- | ----------------------------------------------------------------------------- | ------------------------------------------- |
|
|
230
|
+
| Workflow | An External application trigger, started by the server's Fixed workflow route | An On-demand trigger with a trigger form |
|
|
231
|
+
| Agent | `agents.invoke` or `conversations.continue` from the app server | The Agents and Chat pages, or an agent form |
|
|
232
|
+
| Audience | `applications: [application]` | `groups`, `profiles` or `organization` |
|
|
233
|
+
|
|
234
|
+
A trigger form needs a trigger that people start, so an External application trigger cannot back it. One workflow can declare both triggers when the same work must start from both sides. The template's convert-lead workflow has only the External application trigger.
|
|
235
|
+
|
|
236
|
+
A run acts as the identity that started it, and every tool call in the run uses that identity's current grants. A Sales manager who starts a workflow from Studio runs it as themselves when the workflow's `runIdentity` is `triggering_user`, and as the workflow's run-as service principal when it is `service_principal`. A run that no person starts acts as that service principal. [AI primitives](index.md) lists every case.
|
|
237
|
+
|
|
238
|
+
## Related pages
|
|
239
|
+
|
|
240
|
+
- [AI primitives](index.md)
|
|
241
|
+
- [Access](../platform/access.md)
|
|
242
|
+
- [Extensions](../develop/extensions.md)
|
|
243
|
+
- [External apps](../develop/external-apps.md)
|
|
244
|
+
- [Documents](../data/documents.md)
|
|
245
|
+
- [Datasets](../data/datasets.md)
|