Tools overview

A tool is one capability the agent’s model can call during a conversation: look up an order, book a slot, write a lead to your CRM. The model sees a name, a description and a json_schema; when it calls the tool, the tool’s operation tree runs. Tools belong to the workspace, have their own draft and published versions, and can be attached to any number of agents.

Create one

This tool reads an order’s status over HTTP and speaks the answer itself.

curl -X POST https://api.talqing.com/v1/tools \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_order_status",
    "description": "Look up where a customer order is. Use it once the caller has given their order number and asks where it is or when it will arrive.",
    "json_schema": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The order number the caller read out, digits only, e.g. 4417029. Ask for it if they have not said it."
        }
      },
      "required": ["order_id"]
    },
    "operations": [
      {
        "kind": "http",
        "config": {
          "method": "GET",
          "url": "https://api.example.com/orders/{{args.order_id}}",
          "headers": { "Authorization": "Bearer {{secrets.SHOP_API_KEY}}" },
          "timeout": 10
        },
        "silent": true,
        "publish_fields": [
          { "path": "status", "store": "tooldata" },
          { "path": "estimated_delivery", "key": "eta", "store": "tooldata" }
        ]
      },
      {
        "kind": "say",
        "config": { "text": "Order {{args.order_id}} is {{tooldata.status}}, and should reach you {{tooldata.eta}}." }
      }
    ]
  }'

const tool = await talqing.tools.create({
  createToolRequest: {
    name: "check_order_status",
    description:
      "Look up where a customer order is. Use it once the caller has given their order number and asks where it is or when it will arrive.",
    json_schema: {
      type: "object",
      properties: {
        order_id: {
          type: "string",
          description:
            "The order number the caller read out, digits only, e.g. 4417029. Ask for it if they have not said it.",
        },
      },
      required: ["order_id"],
    },
    operations: [
      {
        kind: "http",
        config: {
          method: "GET",
          url: "https://api.example.com/orders/{{args.order_id}}",
          headers: { Authorization: "Bearer {{secrets.SHOP_API_KEY}}" },
          timeout: 10,
        },
        silent: true,
        publish_fields: [
          { path: "status", store: "tooldata" },
          { path: "estimated_delivery", key: "eta", store: "tooldata" },
        ],
      },
      {
        kind: "say",
        config: { text: "Order {{args.order_id}} is {{tooldata.status}}, and should reach you {{tooldata.eta}}." },
      },
    ],
  },
});

tool = talqing.tools.create(
    name="check_order_status",
    description=(
        "Look up where a customer order is. Use it once the caller has given their "
        "order number and asks where it is or when it will arrive."
    ),
    json_schema={
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": (
                    "The order number the caller read out, digits only, e.g. 4417029. "
                    "Ask for it if they have not said it."
                ),
            }
        },
        "required": ["order_id"],
    },
    operations=[
        {
            "kind": "http",
            "config": {
                "method": "GET",
                "url": "https://api.example.com/orders/{{args.order_id}}",
                "headers": {"Authorization": "Bearer {{secrets.SHOP_API_KEY}}"},
                "timeout": 10,
            },
            "silent": True,
            "publish_fields": [
                {"path": "status", "store": "tooldata"},
                {"path": "estimated_delivery", "key": "eta", "store": "tooldata"},
            ],
        },
        {
            "kind": "say",
            "config": {"text": "Order {{args.order_id}} is {{tooldata.status}}, and should reach you {{tooldata.eta}}."},
        },
    ],
)

SHOP_API_KEY must exist as a workspace secret before the tool can be published. The only operation that returns a result is silent, so the tool is silent: the agent speaks the say line and adds nothing after it. Publish the tool, then attach it to an agent by id and publish the agent:

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": "First version"}'

curl -X PATCH https://api.talqing.com/v1/agents/9c1e6f42-7b30-4a55-9d18-2f0a6c4b8e31 \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"tools": [{"tool_id": "2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44"}]}}'

tools is sent whole, so include every tool the agent already has — see updating an agent. An unpublished tool cannot be attached, and publishing the agent pins the tool version live at that moment: a later tool publish reaches calls only after the agent is published again. See testing and publishing.

Fields

Field	Type	Default	Meaning
`name`	string	required	The function name the model sees. `^[a-zA-Z_][a-zA-Z0-9_]*$`, unique in the workspace, not reserved
`description`	string	`""`	When the model should call it. See schema and description
`json_schema`	object	`{}`	The arguments the model supplies. `{}` means none
`operations`	array	`[]`	The operation tree. A tool with no operations cannot be published
`long_running_task`	boolean	`false`	Let the agent keep talking while a slow tree runs
`silent`	boolean	`false`	Tell the model nothing after the tool runs
`disable_interruptions`	boolean	`false`	The caller cannot interrupt the agent while the tool runs

`long_running_task`

On voice and video, a long_running_task tool that has not finished after one second hands the turn back: the model is told the work has started, and the agent keeps talking while the tree runs. When the tree finishes, its result — or its failure — arrives as the tool’s result and the agent shares it. A run that finishes inside the first second behaves like an ordinary tool.

There is no fixed acknowledgement line. Steer what the agent says in the tool’s description, and write it conditionally: “If it is still running, say you are on it; if the result is already there, give it.”
The model can cancel a background tool that is still running if the caller changes their mind.
Text agents always wait for the result; the flag has no effect there.
A background tool is cancelled when the call ends or the agent hands off, so its side effects can be half applied. Work that must finish belongs behind a webhook and your own queue.

Refused at publish: a long_running_task tool containing a transfer or a handoff, and one that is also silent. For fire-and-forget with no result, set background_execution on the operation instead. disable_interruptions on a long_running_task tool publishes with a warning, because it has no effect.

`silent`

The model is handed nothing after the tool runs, so it does not speak on top of it. A tool is already silent when no operation in it can return a response, and any run that ends the call is silent — see what the model is told. Set the flag when the tree does return a result and you do not want it narrated.

`disable_interruptions`

The caller cannot barge in on the agent’s speech while the tool runs. Use it for a tool that runs long enough for a caller to say “hello?” into the silence, or for a disclosure that must be heard in full.

File parameters

A parameter can be a file the person sent on WhatsApp, in a chat or as a photo on a web call: {"type": "string", "format": "attachment"}, or File in the dashboard’s type list. The model passes the file’s id, which it sees next to the file. When the tool runs, the id is replaced with the file itself:

{"id": "…", "url": "https://…", "url_expires_at": "…", "filename": "cv.pdf",
 "mime_type": "application/pdf", "bytes": 81234, "kind": "document"}

So a tool that submits a CV to an ATS sends the link with {{args.cv.url}} and the name with {{args.cv.filename}}. The link lives one hour and is minted at call time; it never enters the conversation, and the stored tool call keeps only the id. An id that is not a file in this conversation is a tool error the model can correct. The agent can pass a file it cannot open itself, such as a voice note. On the Test button there is no conversation, so a File parameter takes an https URL to a file. A File parameter must be a top-level string; publishing refuses format: "attachment" anywhere else.

One capability per tool

The model picks book_appointment more reliably than it sequences check_availability, create_booking and send_confirmation. Chain the steps inside one tree, where the order is yours. The exception is transfers: build one tool per destination, see transfer.

Defining a tool inline

An entry in an agent’s tools can carry {"tool": {...}} — a whole tool in place of a tool_id — so an agent and its tools are created in one request. The write creates the tool, publishes it at version 1 and stores {"tool_id": "…"} in its place; from then on it is an ordinary tool. One entry cannot carry both tool and tool_id.

In the dashboard

Tools live under Build → Tools. The editor has Configuration, Arguments and Operations cards, with Save, Validate, Test and Publish across the top. ToolCoPilot builds and edits trees from a description.

Schema and description

The fields that decide whether the model calls the tool correctly.

The operation tree

The twelve operation kinds, on_error and branches.

Testing and publishing

Run the draft for real, publish, and the pin rule.

Get started

Build

Guides

Create one

Fields

`long_running_task`

`silent`

`disable_interruptions`

File parameters

One capability per tool

Defining a tool inline

In the dashboard

Next

Schema and description

The operation tree

Testing and publishing

​Create one

​Fields

​long_running_task

​silent

​disable_interruptions

​File parameters

​One capability per tool

​Defining a tool inline

​In the dashboard

​Next

Schema and description

The operation tree

Testing and publishing

Create one

Fields

`long_running_task`

`silent`

`disable_interruptions`

File parameters

One capability per tool

Defining a tool inline

In the dashboard

Next