# Functions

<figure><img src="https://4270573731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPD5pBqGI9shvhtXlZ9t2%2Fuploads%2FCn4CgX6VSj7bUqbl8onT%2FScreenshot%202024-10-05%20at%203.32.17%E2%80%AFPM.png?alt=media&#x26;token=2d9be6b6-424c-4479-923d-9ddc62710fed" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Functions are only  available when you select the text output. Functions can be long running so function responses are sent to your [configured api web hook url](https://docs.vorsto.io/api/api-web-hook)
{% endhint %}

To configure a function, you need to define the function name, description, api and parameters.

The parameters are sent to the function api in a POST request.

The function API field requires your system api . See below the expected response of your api:

## API request format

**Sample Request  from the Agent**

**When a function is configured, the agent sends hooks to the api which includes configured input parameters from the agent gotten from an interaction with a user .**\
\
**Each function can have different apis or same api as long as each request and response is handled properly**

{% tabs %}
{% tab title="Request with parameters" %}

```javascript
// Request with parameters

{
    "function": "create_user"
    "name": "name",
    "email": "email"
}
```

{% endtab %}

{% tab title="Request with no parameter" %}

```
// Request with no parameters

{
    "function": "refresh_cache"
}
```

{% endtab %}
{% endtabs %}

## API response format

| Name                | Type                    | Required | Description                                                                                                            |
| ------------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `type`              | string                  | no       | Setting this allows the AI to process your response and determine the next step in your process.                       |
| `message`           | string                  | yes      | Response message from your api. This will be returned as a response                                                    |
| `data`              | Array of [items](#item) | no       | <p>JSON Array of items from your software<br>See data response parameter for actionable <a href="#item"> items</a></p> |
| data\_display\_type | string                  | no       | <p>Default is card.<br>This currently only supports "card" display for the embedded chat tool</p>                      |

{% hint style="warning" %}
The "type" field is uses the message field to instruct the agent on next steps for chain processes.  Hence, do not set the "type"  field when the data field is being returned.
{% endhint %}

### item

| Name        | Type   | Required | Decription                                        |
| ----------- | ------ | -------- | ------------------------------------------------- |
| title       | string | yes      | name of the item                                  |
| image       | string | no       | public image url of the item                      |
| information | string | no       | information/description of item                   |
| metadata    | Array  | no       | Array of key value pair of additional information |
| actions     | Array  | no       | Array of text-url pair of clickable actions       |

**Sample Response  to the Agent**

{% tabs %}
{% tab title="Text Response  " %}

<pre class="language-javascript"><code class="lang-javascript"><strong>//Text Response
</strong>{
  "message": "User profile registered"
}
</code></pre>

{% endtab %}

{% tab title="Text Response  passed with additional instructions to the agent" %}

```json
//Text Response  passed with additional instriuctions to the agent
{
  "type": "instruct",
  "message": "User profile registered, is the user eligible for credit?"
}
```

{% endtab %}

{% tab title="Response with custom data" %}

<pre class="language-javascript"><code class="lang-javascript">//Response with data from your platform
<strong>{
</strong>  "message": "here is a list of items in our inventory",
  "data_display_type": "card",
  "data": [
              {
                "title": "My First Item",
                "image": "https://link/to/my/image.extension",
                "information": "Brief information", 
                "metadata": [
                  {
                    "key1": "value1"
                  },
                  {
                    "key2": "value2"
                  }
                ], 
                "actions": [
<strong>                    {
</strong>                      "text": "Select",
                      "instruct": "User selected My First Item, Proceed to next instruction",
                    },
<strong>                    {
</strong>                      "text": "Select",
                      "link": "http://link/to/item",
                    }
                ], 
              }
          ]
}
</code></pre>

{% endtab %}
{% endtabs %}

Next, explore how to setup your function parameters for your software.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vorsto.io/getting-started/functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.