Working with Actions


In the Maven AGI platform, Actions allow your app to perform specific tasks in response to user questions. You can define as many Actions as necessary, each identified by a unique ID (e.g., get-balance).

Actions are visible within the Maven Dashboard and can be deactivated by customers.

How Actions Work

When the Maven platform decides to call an action, it triggers the executeAction function in your serverless code, providing details about the Action that was called and information about the currently authenticated user.

For instance, if the get-balance action is triggered, your serverless code can call a third-party API to retrieve the user’s balance. The result of this action should be returned in markdown format (e.g., The user's balance is $5). This markdown response is then passed to a Large Language Model (LLM), which transforms it into a natural language response for the user.

Requiring User Data

When creating an Action, your code can specify certain User context that must be present. If a question is asked and the required User context is not available, your Action will not be called.

For example, if your app requires the user’s email to look up their balance, this can be added to the requiredUserContextFieldNames parameter. If the user asking the question is anonymous, or if the authenticated user does not have an email, the Action will not be available to answer the question.

User data is only created by Maven Apps, the LLM does not have write access, and so it can be treated as trusted data.

Getting Additional Information from the User

Actions can also request additional information from the user if it is not present in the stored User context.

On surfaces that support forms (e.g., Chat, Search, Slack), the end user will be shown a form asking for any missing information. The platform will attempt to autofill this form to minimize manual entry.

On surfaces that do not support forms (e.g., SMS, Email), the platform will collect any necessary user information using followup questions.

Form data can be provided by the LLM or the end user, and so it should not be used for sensitive data. Example: User specific IDs should only come from the User data.

Requiring User Confirmation

Some Actions, like get-balance, are safe to be called automatically by the platform. More destructive Actions, like delete-account, should set the userInteractionRequired field to true. This will require the end user to click a button confirming the Action before it is executed.

Note that this does prevent these Actions from being executed on surfaces that do not support forms.

Handling Actions a Serverless Maven App

executeAction is required in order to handle Action execution requests. In addition, it is recommended to implement both preInstall and postInstall methods within your typescript interface.


In preInstall, typically the authentication of the external API is checked. This API should return quickly and surface any validation errors to the user.


In postInstall, Action Sets and Actions should be created.


Within executeAction call the relevant external API to return data.

Best Practices

Format of the markdown response

Coming soon!

Example Maven Apps

Was this page helpful?