Run tools in your code

A Bare tool set gives your code the last word. Cadenya validates the arguments and pauses the tool call. Your application or a person performs the work, submits the result, and lets the objective continue. This pattern keeps private services private. Cadenya never needs an inbound route to your network. This guide uses the dashboard to create the tool set and define its tool. Code enters the flow only after an objective calls that tool and waits for content.

What you need

A Cadenya workspace where you can create tool sets.
A published agent variation that can use the tool set.
The Cadenya SDK, with your API key in CADENYA_API_KEY and workspace ID in CADENYA_WORKSPACE_ID.
An internal order service URL in ORDERS_API_URL and its token in ORDERS_API_KEY for the content example.

Choose a configuration

Pattern	Configure	Use it when
Human response	A Bare tool whose arguments describe the question	A person supplies text, a decision, or another result through your application
Private worker	A Bare tool whose parameter schema matches your internal function	The work runs inside a VPC, against a private database, or on a machine Cadenya cannot reach
Bounded wait	Content timeout on the Bare adapter	A missing response should stop waiting after a set number of seconds

Step 1: Create a Bare tool set

In the workspace sidebar:

Select Tool Sets, then click Create Tool Set.
Under Adapter type, select Bare.
Leave Content timeout blank for this lesson. To bound the wait, enter the number of seconds Cadenya should wait for content.
Click Continue.

Bare tool set connection form with the Content timeout field left blank — The Bare adapter selected in the connection step

On Basics, enter:

Name: Private Orders
Description: Look up order details through a private worker.

Click Continue, confirm that the adapter is Bare on Review, then click Create tool set.

Step 2: Define the tool

The new tool set starts empty. On its Tools tab, click Add Tool, then enter:

Name: lookup_order
Description: Look up an order in the private order database.
Requires Approval: Not required
Tool Name: LookupOrder

For Parameters, click Convert a JSON payload to a schema and paste an example call:

{
  "orderId": "A-1007"
}

Click Convert, review the inferred schema, then click Accept.

Add Tool form with lookup_order details, parameter schema, and LookupOrder tool name — A Bare tool configured to look up a private order

Click Create tool. The Tools tab now lists lookup_order as Available.

Requires Approval and Bare content solve different problems. Approval asks whether a call may proceed. Bare content supplies the call’s result. A tool can use both, which puts approval before the wait for content.

Step 3: Assign the set and run an objective

Assign Private Orders to an agent variation and publish the agent. Dispatch an objective that asks the agent to look up an order. When the agent calls LookupOrder, the tool call enters TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT. The objective stays Running while it waits.

Step 4: Send the content

The dashboard setup is complete. Your application now finds calls waiting for content, performs the private work, and sends each result to Cadenya:

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'] });
const workspaceId = process.env['CADENYA_WORKSPACE_ID']!;
const objectiveId = process.env['CADENYA_OBJECTIVE_ID']!;

async function lookupOrder(orderId: string) {
  const url = new URL(`/orders/${encodeURIComponent(orderId)}`, process.env['ORDERS_API_URL']);
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env['ORDERS_API_KEY']}` },
  });

  if (!response.ok) {
    throw new Error(`Order lookup failed with status ${response.status}`);
  }

  return response.json();
}

const waiting = await client.objectives.toolCalls.list(objectiveId, {
  workspaceId,
  executionStatus: 'TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT',
});

for await (const call of waiting) {
  const { orderId } = call.data.arguments as { orderId: string };
  const result = await lookupOrder(orderId);

  await client.objectives.toolCalls.setContent(
    objectiveId,
    call.metadata.id,
    {
      workspaceId,
      content: [{ type: 'text', text: { text: JSON.stringify(result) } }],
    },
  );
}

Set CADENYA_OBJECTIVE_ID to the objective you dispatched. Replace lookupOrder with the work your application needs. It can call an internal service, query a database, wait for a person, or run local code. The worker filters for TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT, reads the validated orderId argument, and passes the tool call ID to setContent. Once setContent succeeds, the agent receives the result and continues.

Content can contain text, image, and audio blocks. See Set a Bare tool call’s content for the complete block shapes and limits.

Handle timeouts

If the application does not submit content before the configured Content timeout, Cadenya records a system result that says no content arrived and lets the objective continue. Choose a value long enough for the runtime:

A private worker often needs minutes.
A person may need hours.
A workflow that must finish within a request window needs a shorter bound.

What you built

You created a hand-defined tool whose runtime stays in your application. The same pattern supports human answers, private service calls, local scripts, and other work that should not expose an HTTP or MCP endpoint. Next, see the tool sets SDK guide for the broader lifecycle and stream objective events when you want to react to waiting calls instead of polling.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

Run tools in your code

What you need

Choose a configuration

Step 1: Create a Bare tool set

Step 2: Define the tool

Step 3: Assign the set and run an objective

Step 4: Send the content

Handle timeouts

What you built

​What you need

​Choose a configuration

​Step 1: Create a Bare tool set

​Step 2: Define the tool

​Step 3: Assign the set and run an objective

​Step 4: Send the content

​Handle timeouts

​What you built

What you need

Choose a configuration

Step 1: Create a Bare tool set

Step 2: Define the tool

Step 3: Assign the set and run an objective

Step 4: Send the content

Handle timeouts

What you built