Flow Invocation Schemas

Similar to other remote web services and APIs, Prismatic flows can be invoked by AI agents when they are expressed as tools.

To make a flow compatible with LLM calls, you must do two things:

1. Give the flow an invocation schema
2. Mark the flow as tool-enabled

See the low-code and code-native guides for instructions specific to your integration type.

Invocation schema

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",
  "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" }
  }
}

Optional: 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",
  "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",
      "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"
    }
  }
}

Your agent flows must be synchronous

Your flow must respond synchronously to return a pertinent response to an AI agent. A synchronous flow returns the results of the last step to the caller and must complete its work within 30 seconds.

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.