Overview

An agent task takes named inputs (vars), works with a model and its tools, and returns a typed result (output). This section covers tasks you run on their own — POST /v1/task-runs, one at a time or in batches of up to 1000, or an email batch drafting each row. The same task can also be entered by an agent mid-conversation and hand its result back as a JSON tool result; that is documented in agent tasks. Use a task when the work has an input and an answer rather than a conversation: research a company from a domain, classify an inbound message, extract terms from a document, draft an opening line.

{
  "config": {
    "name": "Classify an inbound message",
    "prompt": "You triage inbound support messages.\n\nRead {{vars.message}} and decide which queue it belongs in.",
    "llm": { "provider": "openai", "model": "gpt-5.6-luna" },
    "vars": [
      { "name": "message", "description": "The raw text of the message", "required": true }
    ],
    "output": [
      { "name": "queue", "type": "string", "description": "One of: billing, technical, sales, other." },
      { "name": "is_urgent", "type": "boolean", "description": "True if the sender is blocked right now or reports an outage." }
    ],
    "submit_result_description": "Submit the queue and urgency once you have read the whole message. Calling this is how the result is produced."
  }
}

Only name is required to save a draft. Publishing additionally needs at least one output field and a provider key for the model.

How a task differs from an agent

A task has an agent’s prompt, llm, tools, mcps, faqs, vars, timezone and lifecycle hooks (on_enter, on_exit, on_user_turn_completed; the last fires only when an agent entered the task). It has none of an agent’s session fields, and sending one is a 422:

Not on a task	Why
`channel`, `stt`, `tts`, `realtime`, `language`, `turn_handling`, `avatar`	A task uses the media of the call that entered it, or none.
`greeting`	It opens by working, not by greeting.
`handoffs`	It returns to whoever entered it. Attached tools containing a `handoff` operation are refused too.
`recording`, `analysis`, `conversation`	These belong to a call.

What the prompt can read

Token	Resolves to
`{{vars.name}}`	The value this run was given, else the variable’s `default`.
`{{system_vars.now}}`, `.date`, `.time`	The clock in the task’s `timezone`; using one without `timezone` set is a save error.
`{{system_vars.human_phone_number}}`, `.agent_phone_number`, `.direction`, `.channel`	Empty on a standalone run; saves with a warning.
`{{userdata.…}}`	The calling session’s state when an agent entered the task; empty on a standalone run.

{{secrets.…}}, {{args.…}} and {{tooldata.…}} are refused in a prompt. See variables.

Config reference

Field	Type	Default	Bound	Meaning
`name`	string	—	required, unique in workspace (`409`)	For people, not the model.
`prompt`	string	`""`	—	The system prompt. Empty saves with a warning.
`llm`	object	`openai` / `gpt-5.6-luna`	—	Same shape as an agent’s: `provider`, `model`, `fallback`, `reasoning_effort`, `priority`, `builtin_tools`. See models.
`tools`	array	`[]`	published tools only	See tools and MCP servers.
`mcps`	array	`[]`	MCP-capable integrations	See tools and MCP servers.
`faqs`	array	`[]`	at most 10	`{"faq_id": "…"}` or an inline FAQ. See FAQs.
`vars`	array	`[]`	—	Inputs. See inputs and output.
`output`	array	`[]`	at most 25; at least 1 to publish	The typed result.
`submit_result_description`	string	starter sentence	non-empty	Description of the generated `submit_result` tool.
`finish_without_result_description`	string	starter sentence	non-empty	Description of `finish_without_result`; used only when an agent entered the task.
`max_steps`	integer	`25`	1–50	Model → tools → model rounds per attempt, standalone runs only.
`timeout_seconds`	integer	`300`	10–600	Wall-clock budget for the whole run.
`timezone`	string \| null	`null`	IANA name	Needed only if the prompt or a tool reads the clock.

Talqing charges no platform fee on task runs. A run’s cost is your own provider spend, reported as provider_cost.

Create, publish and run

Every write lands on a draft; runs use the published version. See versions.

TASK_ID=$(curl -sS -X POST https://api.talqing.com/v1/tasks \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "name": "Classify an inbound message",
      "prompt": "You triage inbound support messages.\n\nRead {{vars.message}} and decide which queue it belongs in.",
      "vars": [{ "name": "message", "description": "The raw text of the message", "required": true }],
      "output": [
        { "name": "queue", "type": "string", "description": "One of: billing, technical, sales, other." },
        { "name": "is_urgent", "type": "boolean", "description": "True if the sender is blocked right now or reports an outage." }
      ]
    }
  }' | jq -r .id)

curl -sS -X POST "https://api.talqing.com/v1/tasks/$TASK_ID/publish" \
  -H "Authorization: Bearer $TALQING_API_KEY"

curl -sS -X POST "https://api.talqing.com/v1/task-runs" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 330 \
  -d '{ "task_id": "'"$TASK_ID"'", "vars": { "message": "Our card was charged twice this morning." } }'

import { TalqingClient } from "@talqing/sdk";

const talqing = new TalqingClient({
  baseUrl: "https://api.talqing.com",
  token: process.env.TALQING_API_KEY,
});

const task = await talqing.tasks.create({
  createTaskRequest: {
    config: {
      name: "Classify an inbound message",
      prompt:
        "You triage inbound support messages.\n\nRead {{vars.message}} and decide which queue it belongs in.",
      vars: [{ name: "message", description: "The raw text of the message", required: true }],
      output: [
        { name: "queue", type: "string", description: "One of: billing, technical, sales, other." },
        {
          name: "is_urgent",
          type: "boolean",
          description: "True if the sender is blocked right now or reports an outage.",
        },
      ],
    },
  },
});

await talqing.tasks.publish({ task_id: task.id });

const run = await talqing.taskRuns.create({
  createTaskRunRequest: {
    task_id: task.id,
    vars: { message: "Our card was charged twice this morning." },
  },
});
console.log(run.status, run.output);

import os
from talqing import Talqing

# A run blocks until it finishes; the client timeout must exceed timeout_seconds.
with Talqing(os.environ["TALQING_API_KEY"], base_url="https://api.talqing.com", timeout=330.0) as talqing:
    task = talqing.tasks.create(
        config={
            "name": "Classify an inbound message",
            "prompt": (
                "You triage inbound support messages.\n\n"
                "Read {{vars.message}} and decide which queue it belongs in."
            ),
            "vars": [{"name": "message", "description": "The raw text of the message", "required": True}],
            "output": [
                {"name": "queue", "type": "string", "description": "One of: billing, technical, sales, other."},
                {
                    "name": "is_urgent",
                    "type": "boolean",
                    "description": "True if the sender is blocked right now or reports an outage.",
                },
            ],
        }
    )
    talqing.tasks.publish(task["id"])

    run = talqing.task_runs.create(
        task_id=task["id"], vars={"message": "Our card was charged twice this morning."}
    )
    print(run["status"], run["output"])

A completed run returns the declared fields under output:

{
  "status": "completed",
  "output": { "queue": "billing", "is_urgent": false },
  "steps_used": 1,
  "max_steps": 25,
  "attempts": 1,
  "provider_cost": 0.0031
}

In the dashboard, Tasks in the sidebar lists tasks; the editor has Prompt, Model, Inputs and output, Tools, FAQs, Limits, Run and Runs sections, with TaskCoPilot beside them.

Inputs and output

Declare vars and output, and how submit_result collects the result.

Running and runs

Run one, read the trace, attempts and steps_used.

Agent tasks

Enter a task from a live conversation instead.

Get started

Build

Guides

How a task differs from an agent

What the prompt can read

Config reference

Create, publish and run

Next

Inputs and output

Running and runs

Agent tasks

​How a task differs from an agent

​What the prompt can read

​Config reference

​Create, publish and run

​Next

Inputs and output

Running and runs

Agent tasks

How a task differs from an agent

What the prompt can read

Config reference

Create, publish and run

Next