findIntent
Desktop Agent bridging message exchange for a findIntent
API call on the DesktopAgent
. Generated by API call:
Message Exchange Type: Request Response (collated)
E.g. An application with appId: "agentA-app1"
and instanceId: "c6ad5174-6f78-4582-8e96-728d93a4d7d7"
makes the following API call:
let appIntent = await fdc3.findIntent("StartChat", context);
Message exchange
Request format
Request message schemas
- https://fdc3.finos.org/schemas/2.1/bridging/findIntentAgentRequest.schema.json
- https://fdc3.finos.org/schemas/2.1/bridging/findIntentBridgeRequest.schema.json
Example
Outward message to the DAB:
// agent-A -> DAB
{
"type": "findIntentRequest",
"payload": {
"intent": "StartChat",
"context": {/*contextObj*/}
},
"meta": {
"requestUuid": "<requestUuid>",
"timestamp": "2020-03-...",
"source": {
"appId": "agentA-app1",
"instanceId": "c6ad5174-6f78-4582-8e96-728d93a4d7d7"
}
}
}
The DAB fills in the source.desktopAgent
field and forwards the request to the other Desktop Agents (agent-B AND agent-C):
// DAB -> agent-B
// DAB -> agent-C
{
"type": "findIntentRequest",
"payload": {
"intent": "StartChat",
"context": {/*contextObj*/}
},
"meta": {
"requestUuid": "<requestUuid>",
"timestamp": "2020-03-...",
"source": {
"appId": "agentA-app1",
"instanceId": "c6ad5174-6f78-4582-8e96-728d93a4d7d7",
"desktopAgent": "agent-A" //added by DAB
}
}
}
Note that the source.desktopAgent
field has been populated with the id of the agent that raised the requests, enabling the routing of responses.
Response format
Response message schemas
- https://fdc3.finos.org/schemas/2.1/bridging/findIntentAgentResponse.schema.json
- https://fdc3.finos.org/schemas/2.1/bridging/findIntentAgentErrorResponse.schema.json
- https://fdc3.finos.org/schemas/2.1/bridging/findIntentBridgeResponse.schema.json
- https://fdc3.finos.org/schemas/2.1/bridging/findIntentBridgeErrorResponse.schema.json
Example
Normal response from agent-A, where the request was raised.
{
"intent": { "name": "StartChat" },
"apps": [
{ "appId": "myChat" }
]
}
DA agent-B would produce the following response if the request was generated locally:
{
"intent": { "name": "StartChat" },
"apps": [
{ "appId": "Skype", "title": "Skype" /* other AppMetadata fields may be included */},
{ "appId": "Symphony", "title": "Symphony" },
{ "appId": "Symphony",
"instanceId": "93d2fe3e-a66c-41e1-b80b-246b87120859",
"title": "Symphony" },
{ "appId": "Slack", "title": "Slack" }
]
}
Hence, the response it sends to the bridge is encoded as follows:
// agent-B -> DAB
{
"type": "findIntentResponse",
"payload": {
"appIntent": {
"intent": { "name": "StartChat" },
"apps": [
{ "appId": "Skype", "title": "Skype" /* other AppMetadata fields may be included */ },
{ "appId": "Symphony", "title": "Symphony" },
{ "appId": "Symphony",
"instanceId": "93d2fe3e-a66c-41e1-b80b-246b87120859",
"title": "Symphony" },
{ "appId": "Slack", "title": "Slack" }
]
}
},
"meta": {
"requestUuid": "<requestUuid>",
"responseUuid": "<responseUuidAgentB>",
"timestamp": "2020-03-...",
}
}
Note the response UUID generated by the agent-B and the reference to the request UUID produced by agent-A where the request was originated. Further, note that the AppMetadata
elements in the AppIntent
do not have a desktopAgent
field yet, and the meta
element does not contain a sources
element, both of which the bridge will add.
DA agent-C would produce the following response locally:
{
"intent": { "name": "StartChat" },
"apps": [
{ "appId": "WebIce"}
]
}
which is sent back over the bridge as a response to the request message as:
// agent-C -> DAB
{
"type": "findIntentResponse",
"payload": {
"appIntent": {
"intent": { "appId": "StartChat" },
"apps": [
{ "appId": "WebIce"}
]
}
},
"meta": {
"requestUuid": "<requestUuid>",
"responseUuid": "<responseUuidAgentC>",
"timestamp": "2020-03-...",
}
}
The bridge receives and collates the responses, producing the following collated response which is sends back to agent-A:
// DAB -> agent-A
{
"type": "findIntentResponse",
"payload": {
"intent": "StartChat",
"appIntent": {
"intent": { "name": "StartChat" },
"apps": [
{ "appId": "Skype", "title": "Skype", "desktopAgent": "agent-B" }, //desktopAgent added by DAB
{ "appId": "Symphony", "title": "Symphony", "desktopAgent": "agent-B" },
{ "appId": "Symphony",
"instanceId": "93d2fe3e-a66c-41e1-b80b-246b87120859",
"title": "Symphony",
"desktopAgent": "agent-B" },
{ "appId": "Slack", "title": "Slack", "desktopAgent": "agent-B" },
{ "appId": "WebIce", "desktopAgent": "agent-C"}
]
}
},
"meta": {
"requestUuid": "<requestUuid>",
"responseUuid": "<responseUuidDAB>",
"timestamp": "2020-03-...",
"sources": [ //added by DAB
{ "desktopAgent": "agent-A" },
{ "desktopAgent": "agent-B" },
]
}
}
In the event that an agent referred to in the API call is not connected to the bridge, an agent that was connected times out or returns an error, its DesktopAgentIdentifier
should be added to the meta.errorSources
element instead of meta.sources
and the appropriate error (ResolveError.DesktopAgentNotFound
, BridgingError.ResponseTimedOut
or BridgingError.AgentDisconnected
) should be added to meta.errorDetails
.
Finally, agent-A combines the data received from the bridge, with its own local response to produce the response to the requesting application:
// agent-A -> requesting App
{
"intent": { "name": "StartChat", "displayName": "Chat" },
"apps": [
// local to this agent
{ "appId": "myChat" },
//agent-B responses
{ "appId": "Skype", "title": "Skype", "desktopAgent": "agent-B" },
{ "appId": "Symphony", "title": "Symphony", "desktopAgent": "agent-B" },
{ "appId": "Symphony",
"instanceId": "93d2fe3e-a66c-41e1-b80b-246b87120859",
"title": "Symphony",
"desktopAgent": "agent-B" },
{ "appId": "Slack", "title": "Slack", "desktopAgent": "agent-B" },
//agent-C responses
{ "appId": "WebIce", "desktopAgent": "agent-C"}
]
}