Flow Invocation Schemas

Agent Flow schema and MCP server are preview features

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 when they are expressed as tools.

Invocation schema

To make a flow compatible with LLM calls, the LLM must understand the structure 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 like this:

{
  "first": "string",
  "last": "string"
}

The shape of the request can be expressed with JSON schema, which is a standard way to describe the shape of JSON data:

Example invocation schema in JSON

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$comment": "Given a first and last name of a person, search for matching people in Acme CRM",
  "properties": {
    "first": { "description": "A person's first name", "type": "string" },
    "last": { "description": "A person's last name", "type": "string" }
  },
  "title": "search-people",
  "type": "object"
}

The response that your flow returns can also be described using JSON schema. Here, we describe a response that returns an array of people records, each with an id, name, and address.

Example result schema in JSON

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$comment": "Returns any people records that match the search query",
  "properties": {
    "people": {
      "description": "An array of people who match the query",
      "items": {
        "properties": {
          "address": {
            "description": "Address of person in Acme CRM",
            "type": "string"
          },
          "id": {
            "description": "ID of a person in Acme CRM",
            "type": "number"
          },
          "name": {
            "description": "Full name of a person in Acme CRM",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "title": "search-people-result",
  "type": "object"
}

Adding invocation schema to a flow

To add an invocation schema to a flow, click on the flow's trigger and select the Schemas tab.

Note that invoke schemas are required but result schemas are optional.

Your agent flows must be synchronous

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 first and last properties, fetches users from JSON Placeholder, and returns a list of users whose names match the searched strings.

When an AI client like Claude invokes this flow, it translates a human language prompt like:

Search people in Acme CRM whose first name includes "Clem"

Into an HTTP request to the agent flow's webhook URL with a payload of { "first": "Clem" }.

Querying for invocation schemas

The flows you build that have invocation schemas are considered agent flows. As a Prismatic organization user, you can programmatically query for agent flows that are associated with test instances (the instances used when testing an integration in the low-code designer). Customer users, on the other hand, can only query for agent flows that are associated with instances deployed to the customer they are logged in as.

Information about these flows, including webhook URL and invokeSchema / resultSchema can be fetched from the Prismatic API using the ai { agentFlows } query:

Query for deployed agent flows

query agentFlows {
  ai {
    agentFlows {
      nodes {
        id
        name
        description
        webhookUrl
        apiKeys
        invokeSchema
        resultSchema
      }
    }
  }
}

The above query, when run by an organization team member, will return information about all agent flows for your test instances.

If you are querying as a customer user using an embedded JWT, on the other hand, you will see only agent flows deployed to the customer you're logged in as.

Agent flows response

{
  "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\"}}}"
          }
        ]
      }
    }
  }
}

Once you have the invokeSchema and webhookUrl, you can create tools for AI agents (like OpenAI or Claude) to consume.