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 Create 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.

Optional: fill in Description, then select Create Tool

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

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 with the Name field set to Order Lookup and a short description filled in

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 A toolkit with this name already exists if another toolkit has that name.
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, a deploy dot, its description, an enable switch, a Duplicate action button, a trash icon, and a chevron. 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. Duplicate toolkit is the copy icon on a CodeKit toolkit card on 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.

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 with the Name field set to Get order status 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 link carries the toolkit name, and the heading shows the action name. A badge tracks the deployment: Draft, Building, Deploying, Built, Deployed, or Error. After a build, the bundle size and the last build time appear beside the badge.

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.

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.order_number. Select Edit schema to open the Input / Output dialog.

The Input / Output dialog on the Inputs tab in the Form view, with the Form and JSON buttons, a saved order_number row showing its string type, Required badge, description, and Edit, Duplicate, and Delete buttons, and Add parameter below it

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. On the Outputs tab, successful and error are fixed. 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 order_number with the description “The order number the customer received in their confirmation email, for example ORD-1042”.

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 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.order_number` 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.

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-08-18' },
  'ORD-1043': { status: 'Processing', carrier: 'Not assigned yet', eta: '2026-08-21' },
  'ORD-1044': { status: 'Delivered', carrier: 'FedEx', eta: '2026-08-12' },
}

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

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

  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}.`,
    },
  }
}

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 badge moves through Building and Deploying.

Wait for the Deployed badge

The bundle size and build 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 two blockers apply 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.
Building…	A build is still running.

If the badge ends in Error, 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, 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