Write a custom action

At the end of this page, you have a deployed custom action, and an AI Agent gambit in your flow can call it. The example builds an Order Lookup toolkit with one action, Get order status, that returns the status of an order number.

Before you start

Before you start, sign in to the dashboard and select the organization you want to work in.

You need a role that can manage resources, such as Admin or Member.
If the action will call a third-party toolkit such as Gmail, connect it first. See Connect a toolkit.
For what a CodeKit toolkit is and how secrets and deployment fit together, read CodeKit overview.

Create a CodeKit toolkit

Open Tools and select New custom tool

The Create Custom Tool dialog opens.

Enter a Name, such as Order Lookup

Letters, numbers, spaces, underscores, and parentheses are allowed. The name cannot start with a number, and no other tool in your organization can have it.

Optional: fill in Description, then select Create Tool

A “Order Lookup” created message confirms, and the toolkit page opens.

To copy a toolkit from another organization instead, open the Import from file tab of the same dialog. See Export and import. The new toolkit holds one Greeting action as a starting point. It is switched off and not deployed. Edit it into your first action, or delete it.

The Create Custom Tool dialog on Start from scratch, with the Import from file option beside it, the empty Name and Description fields, and the Create Tool button

The toolkit page

The toolkit page holds everything its actions share. Save stores the toolkit name, description, and logo.

Card	Controls
Toolkit Info	The Logo dropzone, Drop logo or click, takes an image file. The field below it takes a pasted logo URL instead. Name and Description edit the toolkit. The Name field warns This name is already taken by another tool if any other tool in your organization has that name, connected toolkits included.
Environment Variables	Secrets shared by every action in the toolkit. Add Secret creates one. See Add secrets.
Log privacy	The Enable redaction switch reveals Redact inputs and Redact outputs. Redacted values never reach execution logs in plain text.
Used by	The agents that currently use this toolkit in their flow. Check it before you delete anything.
Delete Toolkit	Shown to organization admins only. Its Delete button removes the toolkit and all of its actions after a confirmation. Agents that use them stop working, and the deletion cannot be undone.

The Actions list

The Actions heading shows the count of actions. Search actions filters the list, and Add Action creates a new one. An empty toolkit shows No actions yet with a Create your first action button. Each row shows the action’s name, type, deployment status, description, and enable switch. Duplicate action and delete controls sit beside it. Select the row to open the editor.

Deploy dot	Meaning
Green	The action is deployed.
Spinner	A build or deployment is running.
Red alert	The last deployment failed.

An action that was never deployed shows no dot. Every new action starts with its enable switch off. The switch stays disabled until the action is deployed, and its tooltip reads Deploy this action before enabling it. A change to the switch applies at once, without Save. The toolkit card on the Connected tab of the Tools page counts enabled actions.

Duplicate an action or a toolkit

Duplicate action on a row adds a copy of the action to the same toolkit. A "" duplicated message confirms. To copy a CodeKit toolkit, select More actions → Duplicate on its card in the Connected tab. It copies the toolkit with its actions, toolkit secrets, logo, and log privacy settings, then opens the copy. Every copied action starts switched off and not deployed. Deploy each copy before you turn it on.

Export and import

The more-options menu at the top of the toolkit page holds Export toolkit and Import actions. The same menu on an action page holds Export action.

Export toolkit downloads the toolkit and its actions as a .codekit.json file. Secret values are not included, only their keys. Admins, Members, and Auditors can export toolkits they can read.
Import actions adds the actions from a CodeKit export to this toolkit. The file can be up to 1 MB.
Import from file, in the Create Custom Tool dialog, creates a new toolkit from an export.

After an import, the dialog lists the secrets to fill in. Deploy each imported action before an agent uses it.

Publish an integration

Some components accept your own system in place of a built-in one. For example, the Meeting Scheduler can book through your calendar system instead of Google Calendar or Microsoft Outlook. You build that from CodeKit actions, one action per role of a contract.

Give each action the matching Action type

See Action types.

Deploy and enable both actions

See Save and deploy.

Open Integrations in the more-options menu

Select Publish integration. The Publish integration dialog opens.

Choose the contract and an action for each role

Pick the Contract, then set an action for every required role. Fill in Name and Integration ID, then select Publish.

Each publish creates a new version. Existing components keep their selected version, even after you publish a fix. To update a Meeting Scheduler, select the new version on its Integration step. Revoke withdraws a version. Calls from components that still use that version fail until you select an available version. See Book meetings with the Meeting Scheduler. For a complete Availability and Booking example, follow Build a custom scheduling integration.

Create an action

Select Add Action

The Create Action dialog opens.

Enter a Name, such as Get order status

A Slug preview updates below the field as you type, for example get_order_status.

Enter a Description, then select Create Action

Description is required. It tells the model what the action does. The action editor opens.

The Create Action dialog over the Order Lookup toolkit, with the Name field set to Get order status, the get_order_status slug preview, and its description filled in

The action editor

The editor page has a Configure rail on the left and the code editor on the right. The back button returns to the toolkit, and the heading shows the action name. The status bar below the code shows Not deployed, Changes not deployed, Deploying, Deployed, or Deploy failed. It also shows the bundle size and last deployment time when available. Hover over Deploy for deployment details.

Button	What it does
Reset code	Replaces the editor content with the starter template. A confirmation dialog appears first. Nothing is stored until you save.
Reset everything	Deletes every action-level secret at once, and resets the code and schema in the editor. A confirmation dialog appears first. Toolkit-level secrets are not affected.
Save	Stores the code, schema, details, and connected toolkits. An Action saved message confirms.
Deploy	Saves, then builds and releases the action. A Deployment started message confirms.

Reset everything deletes action-level secrets immediately, before you save. Neither reset button rolls back to the deployed version.

Details

Field	What it holds
Display name	The name shown in the toolkit and in the builder.
Action ID	The slug your code and the model use. It follows the name until you edit it by hand.
Description	What the action does. The model reads it to decide when to call the action.
Action type	General action, or a role of a platform contract, such as Scheduling · Availability or Scheduling · Booking. See Action types.

Action types

A General action is any action an agent or a flow step calls. A contract role makes the action one half of an integration. The Scheduling contract has two required roles: Availability returns open slots, and Booking books one. Scheduling actions return their role contract objects directly, without a successful, data, and error wrapper. Use the role’s documented outcomes for failures. See Build a custom scheduling integration. Picking a type applies its starter code and schemas. Contract guide, beside the type, opens the guide for the selected type. It shows the input, the output, an example, starter code, and the rules and limits. Copy agent instructions copies text you can paste into an agent’s instructions. Changing the type of an edited action asks first, because it replaces the code, the schema, and the caller fields with the new type’s starter.

Define inputs and outputs

The Input / Output Schema card shows one chip per property. Hover a chip to see its type, whether it is required, and how to read it in code, such as input.orderNumber. Select Edit schema to open the Input / Output dialog. Each tab has Form and JSON buttons that switch between a structured form and the raw JSON Schema. Both views edit the same schema. Form is disabled while the JSON has errors or a field has no type. On the Inputs tab in the form, Add parameter adds a row. Each row takes a parameter name, a type, and a description, plus a Required switch. The types are string, number, integer, boolean, array, object, and null. An object parameter takes its own list of properties, and an array parameter takes an item type. The description is required so the model understands the parameter. Confirm the row with the check button, then select Done. A saved row offers Edit, Duplicate, and Delete. The form shows up to five levels of nesting, and deeper levels are kept for the JSON view. In the JSON view, Supported schema opens a guide to the accepted types and keywords, with an example. Its copy button copies the guide as Markdown. Anything outside the supported subset is flagged. The maximize button opens the editor in the Edit schema JSON dialog. For a General action, successful and error are fixed on the Outputs tab. You pick the type of data and describe what the action returns. That description is required too. An object type lets you list the properties of data, so later steps can reference them by name. For the example, add one required string parameter named orderNumber with the description “The order number the customer received in their confirmation email, for example ORD-1042”. On Outputs, set data to object with the description “Order status and delivery details”. Add string properties orderNumber, status, carrier, estimatedDelivery, and summary, each with a description of its value. Keep the fixed successful and error fields. These are the fields returned by the code below and available for mapping in Workflow Mode.

Add secrets

API keys and tokens belong in secrets, not in code. Your code reads a secret as env.KEY.

Where you add it	Scope	Badge in the editor
Add on the Secrets card in the action editor	This action only. The dialog is Add action secret.	A, Action-only
Add Secret under Environment Variables on the toolkit page	Every action in the toolkit. The dialog is Add Secret.	T, Toolkit-wide

Both dialogs take a Key, a masked Value, and an optional Description. As you type, the key is converted to uppercase and spaces become underscores. It must start with a letter and can contain only uppercase letters, numbers, and underscores, such as IP_API_KEY. Save secret stores it. Values are encrypted at rest. Select any secret chip to open the Secrets dialog, which lists both scopes with a Toolkit or Action badge and a delete button. Deleting a toolkit secret removes it from every action.

Connect toolkits

A custom action can call the toolkits your organization has already connected. Select Connect on the Connected Toolkits card to open the Connect Toolkits dialog.

Pick a toolkit on the left. Toolkits that are not connected are dimmed. On the right, check the actions your code needs, or use Select all and Clear. Select Done to keep the selection, then save the action. To pick actions from several toolkits, select Save Selection before you switch to the next toolkit. Each connected toolkit appears as a chip with a connection dot and the count of selected actions. Its tooltip shows the call shape. For a Gmail toolkit the namespace is toolkits.gmail, and the Types dialog shows the exact input and output of each action.

Write the code

The tab above the editor is named after the Action ID, such as get_order_status.ts.

Control	What it does
Panel toggle	Collapses the Configure rail so the editor fills the page.
Error count	Appears as a red pill, such as 2 errors, while the code has TypeScript errors.
Beautify	Formats the code. The shortcut is Shift+Alt+F.
Types	Opens the Available types dialog with the definitions behind IntelliSense, and a Copy button.

The General action starter code imports from tars and defines one run function that returns successful, data, and error. Your job is the body of run. Cmd+S on Mac or Ctrl+S on Windows saves from inside the editor. The tars module gives you:

Import	What it does
`Input` and `Output`	Types generated from your schema, so the editor suggests `input.orderNumber` as you type.
`env`	Your secrets, as `env.IP_API_KEY`.
`http`	A client with `get`, `post`, `put`, `patch`, `delete`, and `request`. A failed request returns `success`, `status`, `data`, `error`, and `headers` instead of throwing. An invalid address or a private host throws.
`toolkits`	The connected toolkits you selected, as `toolkits.gmail`.
`storage`	A key-value store shared by all custom actions in your organization, as `storage.main.get`, `storage.main.put`, `storage.main.delete`, and `storage.main.list`. `get`, `put`, and `delete` also take batch forms, capped at 128 items.

This example uses a fixed set of demo orders and makes no external requests. Use ORD-1042 for the successful test and ORD-9999 for the failed test. The example action:

import { type Input, type Output } from 'tars'

const ORDERS: Record<string, { status: string; carrier: string; eta: string }> = {
  'ORD-1042': { status: 'Shipped', carrier: 'DHL Express', eta: '2026-10-23' },
  'ORD-1043': { status: 'Processing', carrier: 'Not assigned yet', eta: '2026-10-26' },
  'ORD-1044': { status: 'Delivered', carrier: 'FedEx', eta: '2026-10-19' },
}

async function run(input: Input): Promise<Output> {
  console.log('Validating order number')
  const orderNumber = input.orderNumber?.trim().toUpperCase()
  if (!orderNumber) {
    console.warn('Order number is required')
    return { successful: false, data: null, error: 'orderNumber is required.' }
  }

  console.log(`Looking up ${orderNumber}`)
  const order = ORDERS[orderNumber]
  if (!order) {
    console.warn(`No order found for ${orderNumber}`)
    return { successful: false, data: null, error: `No order found for ${orderNumber}.` }
  }

  console.log(`Found ${orderNumber}: ${order.status}`)
  return {
    successful: true,
    error: null,
    data: {
      orderNumber,
      status: order.status,
      carrier: order.carrier,
      estimatedDelivery: order.eta,
      summary: `${orderNumber} is ${order.status.toLowerCase()} via ${order.carrier}, expected ${order.eta}.`,
    },
  }
}

For a General action, return successful: false with a clear error for every failure you can foresee. The AI Agent gambit reads that message and can tell the end user what went wrong.

Save and deploy

Deploying releases the action to your whole organization. While the deployment runs, and after a failed deployment, agent calls to the action fail.

Select Deploy

The action is saved first. The status bar reads Deploying while the build and deployment run.

Wait for Deployed in the status bar

The bundle size and last deployment time appear beside it. The row on the toolkit page shows a green dot.

Turn on the action's switch on the toolkit page

The switch is available only after the first deployment.

Save and Deploy stay disabled while a blocker exists, and the tooltip names it. The last blocker applies to Deploy only.

Tooltip	Cause
Action name is required	Display name is empty.
Name cannot start with a number	Display name starts with a digit.
Only letters, numbers, spaces, underscores, and parentheses are allowed	Display name holds another character.
Action slug is required	The Action ID field was cleared.
Action description is required	Description is empty.
Code cannot be empty	The editor holds no code.
Fix 2 errors in the code	The editor reports TypeScript errors, with the live count.
A deployment is already in progress	A deployment for this action is still running. While a build runs, the Deploy button shows a spinner and stays disabled.

If the status bar reads Deploy failed, the failure message appears in a red banner under the header. Fix the code and select Deploy again. Agents cannot call the action until a deployment succeeds.

Use the action from an agent

Open your agent's Make page and select the Tools tab in the gambit palette

CodeKit is listed under Connected.

Drag CodeKit onto the builder

A tool gambit appears and its editor opens.

Under Tool Selection, pick your toolkit in the CodeKit dropdown

The gambit takes the toolkit’s name and logo. Configure opens the toolkit page in a new browser tab.

Under Sub-tools, turn on the actions this gambit offers

The section badge counts the included actions.

Connect the tool gambit to an AI Agent gambit

Drag from the tool gambit’s handle to the tool handle on the left of the AI Agent gambit.

The tool gambit editor for a CodeKit tool gambit connected to an AI Agent gambit, with the Order Lookup toolkit picked in the CodeKit dropdown under Tool Selection and the Sub-tools section showing Get order status turned on

The tool gambit shows as a badge in the agent’s Tools & Capabilities region with a Ready dot. For the other ways to wire a tool gambit to an AI Agent gambit, see Enable and use actions. To run the action as a fixed flow step instead, turn on Workflow Mode in the tool gambit editor. Workflow Mode needs the object type for data in the output schema, with at least one property. See Workflow Mode.

Verify

Select Test in the builder toolbar and ask something that needs the action, such as “Where is my order ORD-1042?”. The agent calls Get order status and replies with the status, carrier, and expected delivery date.

Welcome

Core concepts

Guides

Developer

Write a custom action

Before you start

Create a CodeKit toolkit

The toolkit page

The Actions list

Duplicate an action or a toolkit

Export and import

Publish an integration

Create an action

The action editor

Header

Details

Action types

Define inputs and outputs

Add secrets

Connect toolkits

Write the code

Save and deploy

Use the action from an agent

Verify

​Before you start

​Create a CodeKit toolkit

​The toolkit page

​The Actions list

​Duplicate an action or a toolkit

​Export and import

​Publish an integration

​Create an action

​The action editor

​Header

​Details

​Action types

​Define inputs and outputs

​Add secrets

​Connect toolkits

​Write the code

​Save and deploy

​Use the action from an agent

​Verify

​Related pages

Before you start

Create a CodeKit toolkit

The toolkit page

The Actions list

Duplicate an action or a toolkit

Export and import

Publish an integration

Create an action

The action editor

Header

Details

Action types

Define inputs and outputs

Add secrets

Connect toolkits

Write the code

Save and deploy

Use the action from an agent

Verify

Related pages