> This page is for User Guide.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.credal.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.credal.ai/_mcp/server.

# Credal Open Source Actions

> **Credal Actions SDK is open source**
>
> Browse existing actions, open issues, or submit a PR on GitHub:
> **[github.com/credal-ai/actions-sdk](https://github.com/credal-ai/actions-sdk)**

## Overview

Credal's Open Source Actions Framework lets you add custom [actions](/user-guide/platform/governed-actions/overview) to Credal Agents via LLM function calling. The full source lives at **[credal-ai/actions-sdk](https://github.com/credal-ai/actions-sdk)** — all contributions, bug reports, and feature requests should go there.

For more information about Credal's Agent platform, visit [here](https://www.credal.ai/products/agent-platform).

## Contributing a New Action

To add or update an action, clone the [actions-sdk repo](https://github.com/credal-ai/actions-sdk) and follow these steps:

1. **Schema Update**: Add or update the action in `src/actions/schema.yaml`. This is the first step in defining your action.

2. **Type Generation**: Run `npm run generate:types` to generate the new types. This step is crucial for ensuring that your action has the correct type definitions.

3. **Code Formatting**: Run `npm run prettier-format` to format the new files. Consistent formatting helps maintain code readability and quality.

4. **Provider Function Creation**: Create a new provider function in `src/actions/providers/<provider>/<action>.ts` (e.g., `src/actions/providers/math/add.ts`). This function should export a function using the generated types.

5. **Action Mapping**: If you are adding a new action or provider, update `src/actions/actionMapper.ts` and `src/actions/groups.ts`. This ensures that your action is correctly mapped and grouped within the framework.

Once your changes are ready, open a pull request on [github.com/credal-ai/actions-sdk](https://github.com/credal-ai/actions-sdk).

## Coming Soon Improvements

* **Schema Standardization**: We are working on defining a standard for action outputs. While we have loosely followed a structure where outputs contain success and error, standardizing this can improve consistency.

* **Automating File Generation**: We plan to automate steps 2-5 with a script. This script could run `npm run generate:types` and `npm run prettier-format`, create necessary files, and update mappings, allowing users to focus on filling in the generated files.

* **Auth Tokens**: We aim to clarify expectations for auth token generation, especially for services with short-lived tokens, and document the type of authorization needed for each action.

## Usage

To invoke an action, use the following code snippet:

```ts
import { runAction } from "@credal/actions";

const result = await runAction(
  "listConversations",
  "slack",
  { authToken: "xoxb-..." },
  {},
);
```

## Running a Basic Test for `runAction`

To run a basic test for `runAction`, execute the following command:

```
npx ts-node -r tsconfig-paths/register --project tsconfig.json tests/testRunMathAction.ts
```

If you have questions or run into issues, open a GitHub issue at [credal-ai/actions-sdk](https://github.com/credal-ai/actions-sdk/issues).