AI action structure

Sema4.ai actions are Python code packages with natural-language descriptions that help AI agents understand the purpose, inputs, and outputs of each action.

Action packages are accessible through an API endpoint. Agents use their own function-calling capabilities to determine when to call an action and with what inputs. The Sema4.ai actions framework empowers you to build a secure and versatile action inventory that enables agents to interact with any system or data source.

Each action package consists of four main elements contained within a specific folder structure:

• Package configuration file (package.yaml)
• Action Python code (actions.py)
• Test data inputs (.json files)
• Package icon (package.png)

Package configuration

Let's first have a look at what you can find in the package configuration file named package.yaml:

1. Metadata - Description and documentation link displayed in Studio and Control Room.
2. Python environment - Python environment and dependencies definitions for both local and Control Room deployments.
3. Packaging - Any additional packaging instructions, such as files ignored for publishing.

Find a detailed specification of the package.yaml format in the Sema4.ai guide (opens in a new tab).

[[index]]
url = "https://url.to.your.private.package.index"
default = true

Action source code

Here are details about individual sections of a Sema4.ai action code:

1. @action decorator: Makes your function an action. You can control the action's behavior with arguments like is_consequential and assign it a human-readable name. One Python file may contain multiple actions, and a package may contain multiple Python files.
2. Function signature: Includes type hints for input arguments and secrets used by the action. Type hints create an OpenAPI specification to help the AI calling the action provide the correct types of inputs. Secrets use a built-in type for access management.
3. Docstring: Describes your action and helps the agent’s LLM AI understand what it can do with it. The Sema4.ai action docstrings follow the Google docstring (opens in a new tab) formatting and are automatically included in the OpenAPI specification.
4. Code: Implementing the core functionality of your action.

Test data inputs

Each action requires a test data input file that mirrors its input arguments. Locate the devdata folder next to action.py and open the input_your_function_name.json file inside it.

The framework uses this file for debugging. Name it after the function; for example, if your action function is find_company, name the file input_find_company.json.

{
    "query": "Acme Corp"
}

Package icon

A package icon makes it easier to recognize your actions in Sema4.ai Studio, Control Room, and agent chats. The icon file needs to be in the root of the action package, named package.png, and have a resolution of 512×512 px.