Custom tools

A custom tool starts as a definition in the tool editor and then needs an implementation: either an Agentic implementation backed by a Workflow agent, or an Edge implementation that runs on your own infrastructure.

Define the tool

Create the tool under Tools → Create Tool and fill in the definition: Title, Description, Call when, Prerequisites, Limitations, Side effects, and the Arguments schema in the JSON-schema builder. Keep the tool in Draft while you build the implementation; switch it to Live once testing succeeds.

Agentic implementation

Select Agentic and pick a Workflow agent from your organization. When an agent calls the tool, the platform runs the selected workflow agent with the tool arguments as input and returns the agent’s output as the tool result. This requires no code — build the logic in the agent editor using phases, tools, and input/output data types.

Edge implementation

Select Edge (Organization connector) to run the tool on your own edge deployments. You write the handler in TypeScript, package it into a tool bundle with the Edge Connector CLI, and assign the bundle to a deployment. Enable Exclusive execution if the tool must only run on one specific deployment.

Authenticate the CLI:
Terminal window
```
edge-connector auth
```
By default this runs interactively; use -b, --browser for the device-code browser flow or -t, --token <token> to pass a JWT directly.
Generate a scaffold for your tool:
Terminal window
```
edge-connector generate -t <tool>
```
This fetches the tool’s definition from the server and scaffolds a TypeScript project (default output ./custom-implementations) with one file per tool at tools/<toolName>.ts, containing a typed handler plus generated Args and Result types derived from your Arguments schema.
Implement the handler. It receives the validated arguments and must resolve to a result object:
```
{
  status: 'success' | 'error',
  data?: unknown,
  error?: { message: string, isRetryable?: boolean }
}
```
Set isRetryable: true for transient failures (timeouts, temporary outages) so the platform may retry the call.
Package the implementation:
Terminal window
```
edge-connector package
```
The bundle layout requires one source file per tool under tools/ — a single index.ts entrypoint is not supported. The command builds the project and produces edge-bundle-<orgId>-<timestamp>.tgz in ./artifacts.
Upload the bundle:
Terminal window
```
edge-connector upload -f <bundle.tgz>
```
Bundles may be at most 50 MB.
Assign the bundle to a deployment, either with edge-connector bundle assign <id> --deployment <id> or in the deployment detail page. Deployments follow the Latest bundle version by default or can be pinned to a specific version.

Test the result from the tool editor’s Test Console: enter JSON arguments, pick the deployment under Select Deployment, and execute. See the Edge Connector CLI reference for all commands and flags, and Configuration for authentication and runtime details.