Flow Invocation Schemas
Agent flow schema and hosted MCP servers are preview features that require Prismatic Support to enable the feature for you. Please contact Prismatic Support if you'd like to opt-in to the MCP Preview.
Similar to other remote web services and APIs, Prismatic Flows can be invoked by AI agents by expressing them as tools.
Invocation schema
To make a flow compatible with LLM calls, the LLM must know the shape of requests that the flow expects. For example, if you have a flow that fetches a person given their first and last name, it may expect a request body of
{
"first": "string",
"last": "string"
}
That schema can be expressed in the YAML definition of an integration's flow like this
schemas:
invoke:
title: search-people
$comment: Given a first and last name of a person, search for matching people in Acme CRM
type: object
properties:
first:
description: A person's first name
type: string
last:
description: A person's last name
type: string
result:
title: search-people-result
$comment: Returns any people records that match the search query
type: object
properties:
people:
description: An array of people who match the query
type: array
items:
type: object
properties:
id:
type: number
description: ID of a person in Acme CRM
name:
type: string
description: Full name of a person in Acme CRM
address:
type: string
description: Address of person in Acme CRM
Adding invocation schema to a flow
Currently, you must add invocation schema to a flow by downloading your integration's YAML definition, editing it manually, and re-importing the YAML definition.
We'll have a proper UI and CNI support for this in the future!
Note that invoke schemas are required but result schemas are optional.
In order to return a pertinent response to an AI agent, your flow must respond synchronously. As a reminder, a synchronous flow will return the results of the last step of the flow to the caller, and must complete its work within 30 seconds.
This very simple example integration receives a request with a name property, fetches users from JSON Placeholder, and returns a list of users whose names include the search string.
name: People Fetcher
category: ""
configPages:
- elements: []
name: Configuration
defaultInstanceProfile: Default Instance Profile
definitionVersion: 7
description: ""
documentation: ""
endpointType: flow_specific
flows:
- name: Search for People
endpointSecurityType: customer_optional
isSynchronous: true
schemas:
invoke:
title: search-people
$comment: Given a name of a person, search for matching people in Acme CRM
type: object
properties:
name:
description: A person's full name to search
type: string
steps:
- action:
key: webhook
component:
isPublic: true
key: webhook-triggers
version: LATEST
description: ""
inputs:
body:
type: value
value: ""
contentType:
type: value
value: ""
headers:
type: complex
value: []
statusCode:
type: value
value: ""
isTrigger: true
name: Trigger
- action:
key: httpGet
component:
isPublic: true
key: http
version: LATEST
description: ""
inputs:
connection:
type: configVar
value: ""
debugRequest:
type: value
value: "false"
headers:
type: complex
value: []
ignoreSslErrors:
type: value
value: "false"
includeFullResponse:
type: value
value: "false"
maxRetries:
type: value
value: "0"
queryParams:
type: complex
value: []
responseType:
type: value
value: json
retryDelayMS:
type: value
value: "0"
retryOnAllErrors:
type: value
value: "false"
timeout:
type: value
value: ""
url:
type: value
value: "https://jsonplaceholder.typicode.com/users"
useExponentialBackoff:
type: value
value: "false"
name: Get Users
- action:
key: runCode
component:
isPublic: true
key: code
version: LATEST
description: ""
inputs:
code:
type: value
value: |
module.exports = async ({ logger, configVars }, stepResults) => {
const users = stepResults.getUsers.results;
const nameSearch = stepResults.trigger.results.body.data.name;
return {
data: users
.filter((user) =>
user.name.toLowerCase().includes(nameSearch.toLowerCase()),
)
.map(({ id, name, email }) => ({ id, name, email })),
};
};
name: Filter users by name
When an AI client like Claude invokes this flow, it translates a human language prompt like:
Search people in Acme CRM whose name includes "Clem"
Into an HTTP request to the agent flow's webhook URL with with a payload of { "name": "Clem" }.
Querying for invocation schemas
Once you publish an integration and deploy an instance to a customer, the flows with invocation schemas are considered agent flows.
Information about these flows, including webhook URL and invokeSchema / resultSchema can be fetched from the Prismatic API using the ai { agentFlows } query:
query agentFlows {
ai {
agentFlows {
nodes {
id
name
description
webhookUrl
apiKeys
invokeSchema
resultSchema
}
}
}
}
The above query will return information about all agent flows that are deployed to customers. If you are an organization user, this will return agent flow endpoints for all customers. If you are querying as a customer user using an embedded JWT, you will see only agent flows deployed to the customer you're logged in as.
{
"data": {
"ai": {
"agentFlows": {
"nodes": [
{
"id": "SW5zdGFuY2VGbG93Q29uZmlnOmI2N2EzMjU2LWMzOTgtNDRkMy04Mzg0LWExZDkyMjZkN2JhYg==",
"name": "search-people",
"description": "Given a first and last name of a person, search for matching people in Acme CRM",
"webhookUrl": "https://hooks.dev.prismatic-dev.io/trigger/SW5zdGFuY2VGbG93Q29uZmlnOmI2N2EzMjU2LWMzOTgtNDRkMy04Mzg0LWExZDkyMjZkN2JhYg==",
"apiKeys": [],
"invokeSchema": "{\"type\": \"object\", \"title\": \"search-people\", \"$comment\": \"Given a first and last name of a person, search for matching people in Acme CRM\", \"properties\": {\"last\": {\"type\": \"string\", \"description\": \"A person's last name\"}, \"first\": {\"type\": \"string\", \"description\": \"A person's first name\"}}}",
"resultSchema": "{\"type\": \"object\", \"title\": \"search-people-result\", \"$comment\": \"Returns any people records that match the search query\", \"properties\": {\"people\": {\"type\": \"array\", \"items\": {\"type\": \"object\", \"properties\": {\"id\": {\"type\": \"number\", \"description\": \"ID of a person in Acme CRM\"}, \"name\": {\"type\": \"string\", \"description\": \"Full name of a person in Acme CRM\"}}}, \"description\": \"An array of people who match the query\"}}}"
}
]
}
}
}
}
With invokeSchema and a webhookUrl in hand, you can now create tools for AI agents (like OpenAI or Claude) to consume.