Skip to content

(WIP) Get sub agent proposal placeholder #1580

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
kriswest wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

(WIP) Get sub agent proposal placeholder #1580

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c42e799
Placeholders for getSubAgent and close content in docs
kriswest Apr 17, 2025
aa6737f
Add placeholders for getSubAgent in FDC3 for Web specs
kriswest Apr 17, 2025
3bdfe7b
adding placeholders to DesktopAgent and CHANGELOG for getSubAgent
kriswest Apr 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased]

### Added
<!-- TODO: add details of the getSubAgent changes to the changelog -->

### Changed

Expand Down
3 changes: 3 additions & 0 deletions packages/fdc3-standard/src/api/DesktopAgent.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -547,6 +547,9 @@ export interface DesktopAgent {
*/
getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;

// TODO: add getSubAgent definition
Copy link
Contributor

@Roaders Roaders Apr 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/**

Suggested change
// TODO: add getSubAgent definition
* @param {string} params Required parameters object, which must include
* at least a fully qualified appId or appD URL for the application to
* indicate the app's identity.
* @param {string} params.appId The fully qualified appId
* (in the form appid@<appd origin> for the application
* @param {URL} params.appDUrl The URL to the appD record providing the
* app's identity, used as an alternative to a fully qualified appId.
*
* @return A promise that resolves to a DesktopAgent implementation or
* rejects if the app identity could not be validated.
*/
getSubAgent (params: GetSubAgentParams): Promise<DesktopAgent>;

// TODO: add close or disconnect definition

//---------------------------------------------------------------------------------------------
// Deprecated function signatures
//---------------------------------------------------------------------------------------------
Expand Down
10 changes: 10 additions & 0 deletions website/docs/api/ref/DesktopAgent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ interface DesktopAgent {
open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
findInstances(app: AppIdentifier): Promise<Array<AppIdentifier>>;
getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;
// TODO: add getSubAgent
Copy link
Contributor

@Roaders Roaders Apr 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// TODO: add getSubAgent
getSubAgent (params: GetSubAgentParams): Promise<DesktopAgent>;

// TODO: add a close or disconnect function (for subAgents or maybe all agents?)

// context
broadcast(context: Context): Promise<void>;
Expand Down Expand Up @@ -412,6 +414,10 @@ _desktopAgent.Broadcast(instrument);

- [addContextListener](#addcontextlistener)

### `close`

<!-- TODO: add close or disconnect content -->

### `createPrivateChannel`

<Tabs groupId="lang">
Expand Down Expand Up @@ -1105,6 +1111,10 @@ var redChannel = userChannels.First(c => c.Id == "red");

- [`Channel`](Channel)

### `getSubAgent`

<!-- TODO: add getSubAgent content -->

### `joinUserChannel`

<Tabs groupId="lang">
Expand Down
14 changes: 14 additions & 0 deletions website/docs/api/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,8 @@ An FDC3 Standard compliant Desktop Agent implementation **MUST**:
- Provide details of whether they implement optional features of the Desktop Agent API in the `optionalFeatures` property of the [`ImplementationMetadata`](ref/Metadata#implementationmetadata) object returned by the [`fdc3.getInfo()`](ref/DesktopAgent#getinfo) function.
- Allow, by default, at least a 15 second timeout for an application, launched via [`fdc3.open`](../api/ref/DesktopAgent#open), [`fdc3.raiseIntent`](../api/ref/DesktopAgent#raiseintent) or [`fdc3.raiseIntentForContext`](../api/ref/DesktopAgent#raiseintentforcontext) to add any context listener (via [`fdc3.addContextListener`](../api/ref/DesktopAgent#addcontextlistener)) or intent listener (via [`fdc3.addIntentListener`](../api/ref/DesktopAgent#addintentlistener)) necessary to deliver context or intent and context to it on launch. This timeout only applies to listeners needed to receive context on launch; further intent and context listeners not required on launch MAY be added later.

<!-- TODO: add any new requirements for subAgents or disconnection functions -->

An FDC3 Standard compliant Desktop Agent implementation **SHOULD**:

- Support connection to one or more App Directories meeting the [FDC3 App Directory Standard](../app-directory/overview).
Expand All @@ -132,6 +134,8 @@ An FDC3 Standard compliant Desktop Agent implementation **SHOULD**:
- Prevent external apps from listening or publishing on a [`PrivateChannel`](ref/PrivateChannel) that they did not request or provide.
- Enforce compliance with the expected behavior of intents (where Intents specify a contract that is enforceable by schema, for example, return object types) and return an error if the interface is not met.

<!-- TODO: add any new recommendations for subAgents or disconnection functions -->

An FDC3 Standard compliant Desktop Agent implementation **MAY**:

- Make the Desktop Agent API available through modules, imports, or other means.
Expand Down Expand Up @@ -234,6 +238,12 @@ Additional metadata for an application can be retrieved via the [`fdc3.getAppMet

Identifiers for instances of an application may be retrieved via the [`fdc3.findInstances(appIdentifier)`](ref/DesktopAgent#findinstances) function.

### Start sub-applications with their own identity

<!-- TODO: Describe the use-case for sub-agents without being overly focused on a particular platform (could make sense in web apps and monolithic apps built in other languages.
Ensure routing of channel messages and intent resolution are covered.
-->

Copy link
Contributor

@Roaders Roaders Apr 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In some scenarios, it may be necessary to load more than one `DesktopAgent` into the context of a single application or browser window (for web-based applications). This is particularly relevant in the context of micro-frontends, where different applications within the same window may need to communicate with each other.
Using a single `DesktopAgent` per window does not allow separate applications within the same browser window to communicate with each other (this limitation does not apply if the application is loaded into an iframe which is considered to be a different browser window).
To address this, sub-applications can use **sub-agents**. Sub-agents allow different sub-applications within a single window to communicate with each other. Here's an example of how to create and use a sub-agent:
```ts
const subAgent: DesktopAgent = await (await getAgent()).getSubAgent({appId: "[email protected]"});
subAgent.raiseIntent("StartChat", context);

This approach enables seamless communication between sub-agents in the same window.

## Raising Intents

Raising an Intent is a method for an application to request functionality from another application and, if desired, defer the discovery and launching of the destination app to the Desktop Agent.
Expand Down Expand Up @@ -843,3 +853,7 @@ To facilitate context linking in such situations it is recommended that applicat
### Originating App Metadata

Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation to registered context handlers on all types of channel. As this metadata is optional, apps making use of it MUST handle cases where it is not provided.

## Sub-applications

<!-- Add content describing how sub applications are created with their own identity -->
4 changes: 4 additions & 0 deletions website/docs/api/specs/browserResidentDesktopAgents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,3 +263,7 @@ Communication between the `DesktopAgentProxy` and the iframes it injects is achi
A further set of messages are provided for working with the injected user interfaces over their `MessageChannel` as part of the DACP, these are: `Fdc3UserInterfaceRestyle`, `Fdc3UserInterfaceDrag`, `Fdc3UserInterfaceChannels`, `Fdc3UserInterfaceChannelSelected`, `Fdc3UserInterfaceResolve` and `Fdc3UserInterfaceResolveAction`.

See the [Desktop Agent Communication Protocol](./desktopAgentCommunicationProtocol) (DACP) for more details.

## Requesting a sub-agent for an embedded application

<!-- Add content on how sub agent requests are handled through the WCP and DACP - include a diagram of the process -->
8 changes: 8 additions & 0 deletions website/docs/api/specs/desktopAgentCommunicationProtocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,10 @@ Request and response used to implement the [`getUserChannels()`](../ref/DesktopA
- [`getUserChannelsRequest`](pathname:///schemas/next/api/getUserChannelsRequest.schema.json)
- [`getUserChannelsResponse`](pathname:///schemas/next/api/getUserChannelsResponse.schema.json)

#### `getSubAgent()`

<!-- Add details of any DACP messages used by getSubAgent -->

#### `joinUserChannel()`

Request and response used to implement the [`joinUserChannel()`](../ref/DesktopAgent#joinuserchannel) API call:
Expand Down Expand Up @@ -463,6 +467,10 @@ Additional procedures are defined in the [Browser Resident Desktop Agents specif

:::

### Requesting a sub-agent

<!-- Discuss DACP role in requesting a subagent and attachment of of another port to the message, before switching to WCP. Other languages will need to handle that handover somehow -->

### Controlling Injected User Interfaces

Desktop Agent implementations, such as those based on the [Browser Resident Desktop Agents specification](./browserResidentDesktopAgents) and [Web Connection Protocol](./webConnectionProtocol), may either provide their own user interfaces (or other appropriate mechanisms) for the selection of User Channels or Intent Resolution, or they may work with implementations injected into the application (for example, as described in the [Web Connection Protocol](./webConnectionProtocol#providing-channel-selector-and-intent-resolver-uis) and implemented in [`getAgent()`](../ref/GetAgent)).
Expand Down
4 changes: 4 additions & 0 deletions website/docs/api/specs/preloadDesktopAgents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,7 @@ However, implementors SHOULD also ensure that the global is made available as so
Prior to FDC3 2.2, apps were advised to check for the existence of the FDC3 API at `window.fdc3` and then add a listener for the `fdc3Ready` event if it was not found. This has since been superseded by the recommendation to use `getAgent()`, which handles those steps internally, alongside supporting FDC3 in web browsers ( via the [Browser Resident Desktop Agent spec](./browserResidentDesktopAgents)).

:::

## Requesting a sub-agent for an embedded application

<!-- Add content on how sub agent requests should be handled by preload DAs -->
4 changes: 4 additions & 0 deletions website/docs/api/specs/webConnectionProtocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -393,3 +393,7 @@ The WCP allows applications to indicate to the `getAgent()` implementation wheth
- [`WCP3Handshake`](pathname:///schemas/next/api/WCP3Handshake.schema.json): Response sent by the Desktop Agent and incorporating `payload.intentResolverUrl` and `payload.channelSelectorUrl` fields, which should be set to the URL for each UI implementation that should be loaded into an iframe to provide the UI (defaults to URLs for reference UI implementations provided by the FDC3 project), or set to `false` to indicate that the respective UI is not needed. Setting these fields to `true` will cause the `getAgent()` implementation to use its default URLs representing a reference implementation of each UI.

When UI iframes are created, the user interfaces may use the `Fdc3UserInterface` messages incorporated into the [Desktop Agent Communication Protocol (DACP)](./desktopAgentCommunicationProtocol#controlling-injected-user-interfaces) to communicate with the `getAgent()` implementation and through it the Desktop Agent.

### Requesting a sub-agent

<!-- Add content on WCP message (re)use in requesting and connecting a subagent -->
Loading