Testing and publishing

A tool has a draft you edit and immutable published versions that calls run. Three endpoints take a draft to production:

Step	Endpoint	Role	Effect
Validate	`POST /v1/tools/{tool_id}/validate`	any member	Reports what publish would refuse. Opens no connections
Test run	`POST /v1/tools/{tool_id}/run`	editor	Runs the draft against your real endpoints with your real secrets
Publish	`POST /v1/tools/{tool_id}/publish`	editor	Freezes the draft as the next version

Test run

Runs the draft once with the arguments you supply and reports every step. Nothing is saved, no webhook fires, and nothing is billed — but http and code operations execute for real: a tool that books a slot books one.

curl -X POST https://api.talqing.com/v1/tools/2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44/run \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": { "order_id": "4417029" },
    "userdata": { "customer_name": "Priya" },
    "vars": { "api_domain": "acme.example.com" },
    "timezone": "Asia/Kolkata"
  }'

const run = await talqing.tools.run({
  tool_id: "2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44",
  runToolRequest: {
    arguments: { order_id: "4417029" },
    userdata: { customer_name: "Priya" },
    vars: { api_domain: "acme.example.com" },
    timezone: "Asia/Kolkata",
  },
});

run = talqing.tools.run(
    "2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44",
    arguments={"order_id": "4417029"},
    userdata={"customer_name": "Priya"},
    vars={"api_domain": "acme.example.com"},
    timezone="Asia/Kolkata",
)

Request

Field	Default	Meaning
`arguments`	`{}`	The tool call’s arguments, checked against `json_schema` first exactly as a model’s call is
`userdata`	`{}`	The session state the run starts from
`vars`	`{}`	The whole `{{vars.*}}` bag. There is no agent behind a test, so no declared defaults are merged in
`timezone`	`"UTC"`	IANA zone for `{{system_vars.now}}`, `.date` and `.time`

The phone keys of system_vars resolve empty: there is no call. Operations that need a live conversation are simulated — say, generate_reply, add_message, end_call, handoff, transfer, send_dtmf and frontend_rpc report their resolved config instead of acting. Nobody’s phone rings. A background_execution operation runs in line so you can see it, without publishing. The whole run is capped at 60 seconds.

Response

Field	Meaning
`ok`	Whether the run finished without an unhandled failure
`duration_ms`	Wall clock for the run
`error`, `error_type`	The failure, and whose problem it is (below)
`llm_response`	The exact string the model would be handed, or `null` when it would be told nothing: a silent tool, a run that ended the call, or a failed run
`responses`	The operation outputs that make up `llm_response`
`tooldata`, `userdata`	Both stores as they stood when the run ended, even after a failure
`steps`	One entry per operation that ran
`ended_call`, `handed_off`	Whether the run reached an `end_call` or `transfer`, or a `handoff`

Each step:

{
  "path": "1.else.0",
  "kind": "http",
  "status": "ok",
  "duration_ms": 412,
  "detail": {
    "request": { "method": "GET", "url": "https://api.example.com/orders/4417029", "headers": {}, "query": {}, "body": null, "timeout": 10 },
    "response": { "status": 200, "body": { "status": "shipped" } }
  },
  "published": [{ "store": "tooldata", "key": "status", "value": "shipped" }],
  "error": null
}

path is the operation’s index, joined to its parent by .then. or .else.: 1.else.0 is the first operation in the else of the second.
status is ok, failed or simulated.
detail is per kind: http has request and response, code has logs and result, if has both resolved sides, op and the branch taken, a simulated kind has its resolved config.
published is what the step wrote — the fastest way to find a path one level too deep. Secret values are redacted everywhere.

Error types

`error_type`	Meaning
`tool_config`	The operation’s config was unusable: a bad URL, an `if` that could not compare, a `publish_fields` path missing from the result
`tool_auth`	A referenced secret does not exist
`endpoint_error`	Your endpoint answered with a status of 400 or more, or a body that is not JSON
`endpoint_unreachable`	Your endpoint could not be reached: DNS, refused connection, network error
`timeout`	An operation or the whole run ran out of time
`code_error`	A `code` operation threw or exceeded its limits
`platform`	The code-execution service could not be reached. Retry, then contact hello@talqing.com
`unknown`	None of the above; read `error` and `steps`

In the dashboard, Test opens a panel with Arguments, User Data and Variables and a Run tool button; the run uses your browser’s timezone. The flowchart marks each operation as succeeded, failed, simulated or not reached.

Validate

curl -X POST https://api.talqing.com/v1/tools/2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44/validate \
  -H "Authorization: Bearer $TALQING_API_KEY"

{
  "errors": [
    "tool 'check_order' / operations[0] / http: {{args.order_number}} is not a declared tool parameter"
  ],
  "warnings": [
    "tool 'check_order' / operations[2] / say: reads userdata.customer_name before this tool publishes it; ensure session userdata contains 'customer_name' before this tool is called"
  ]
}

Errors block publish; warnings do not. The full list of template rules is in templating and data; the tool-level rules are in the overview. TypeScript is compiled during validation, so a code operation that does not compile is an error here.

Publish

curl -X POST https://api.talqing.com/v1/tools/2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44/publish \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"changelog": "Handle the not-found case"}'

{
  "tool_id": "2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44",
  "version": 4,
  "published_at": "2026-08-30T11:02:19.418Z",
  "warnings": []
}

Publish validates first. On any error nothing is published and you get a 400 whose errors lists every problem. A tool with no operations is refused. The version freezes the name, description, json_schema, the three flags and the tree, plus the compiled JavaScript of each code operation. silent is frozen as your flag or the silence derived from the tree; the draft keeps your own flag. Versions count up from 1 and are never reused.

Versions and rollback

Call	Effect
`GET /v1/tools/{tool_id}`	The draft, plus `versions` with each changelog and publish time
`GET /v1/tools/{tool_id}/versions/{version}`	One version’s frozen definition, in the same shape as the draft
`POST /v1/tools/{tool_id}/versions/{version}/rollback`	Makes that version the published one and replaces the draft with it

Rollback discards unpublished draft edits and creates no new version. Agents that pinned another version keep running it until they are republished.

The pin rule

A tool with no published version cannot be attached to an agent.
Publishing an agent pins, for each attached tool and lifecycle hook, the tool version published at that moment.
Publishing the tool again changes nothing on live calls until the agent is published again.

So the fix loop for a tool a live agent uses is: edit, run, publish the tool, then publish the agent. An agent’s draft follows the tool’s current published version. Agent tasks never pin: every task run uses each tool’s current published version.

Agent versions

Publishing and pinning from the agent’s side.

When a tool fails

Reading a failure on a live call.

Get started

Build

Guides

Testing and publishing

Test run

Request

Response

Error types

Validate

Publish

Versions and rollback

The pin rule

Next

Agent versions

When a tool fails

​Test run

​Request

​Response

​Error types

​Validate

​Publish

​Versions and rollback

​The pin rule

​Next

Agent versions

When a tool fails

Test run

Request

Response

Error types

Validate

Publish

Versions and rollback

The pin rule

Next