Overview

An agent task takes named inputs, does some work with a model and its tools, and returns a typed value. Same prompt, same model, same tools, same MCP servers as an agent — minus every conversational organ, plus the one thing a conversation cannot have: a structured output you declare up front. Reach for 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. Draft an opening line. Pull one field out of a document. Here is a complete task, exactly as POST /v1/tasks takes it:

{
  "config": {
    "name": "Research a company",
    "prompt": "You research companies from a work email address.\n\nGiven {{vars.email}}, work out the company behind the domain, what it sells and who it sells to. Use the web search tool before you answer, and never guess a fact you did not read.",
    "llm": {
      "provider": "openai",
      "model": "gpt-5.6-luna",
      "reasoning_effort": "medium"
    },
    "vars": [
      { "name": "email", "description": "A work email address, e.g. priya@northwind.com", "required": true }
    ],
    "output": [
      { "name": "company_name", "type": "string", "description": "The company's legal or trading name. Send null if the domain resolves to no company you can identify." },
      { "name": "what_they_sell", "type": "string", "description": "One or two sentences on the product and who buys it, in plain language. Send null if you could not read enough to say." },
      { "name": "employee_count", "type": "integer", "description": "Headcount as a whole number, from the company's own site or a listing page. Send null rather than estimating." },
      { "name": "is_enterprise", "type": "boolean", "description": "True if they sell mainly to companies of 500+ people, false if they sell to smaller businesses or consumers. Send null if the site does not say." }
    ],
    "max_steps": 25,
    "timeout_seconds": 180
  }
}

Only name and output are required. Everything else takes a default.

What a task is not

A task is its own noun with its own operations, not a fourth agent channel. It has no channel field, because there is nobody on the other end.

An agent has	A task has it too	Why not
`prompt`, `llm`, `tools`, `mcps`, `vars`, `timezone`	Yes	—
`stt`, `tts`, `realtime`	No	Nobody to hear, nobody to speak to.
`greeting`	No	Nobody to greet.
`turn_handling`	No	There are no turns to take.
`handoffs`	No	Nothing to hand over.
`avatar`, `channel`, `language`	No	Nothing is rendered or spoken.
`recording`, `analysis`	No	There is no call to record or analyse afterwards.
`kb_ids`	No	A conversation wanders and looks things up mid-sentence; a task fetches what it needs through its tools and MCP servers.
`on_enter`, `on_exit`, `on_user_turn_completed`	No	One turn, so there is nothing for a lifecycle hook to sit between.

The config forbids fields it does not have. Sending greeting or kb_ids on a task is a 422, not a silent drop.

What the prompt can read

A task’s prompt is a template, checked when you save it, exactly as an agent’s is.

Token	Resolves to
`{{vars.name}}`	The value this run was given, or the variable’s declared `default`.
`{{system_vars.now}}` / `.date` / `.time`	The clock, in the task’s `timezone`. Setting `timezone` is required before you can read any of them — a task without one is refused with the reason.

There is no call, so {{system_vars.human_phone_number}}, {{system_vars.agent_phone_number}} and {{system_vars.direction}} never hold anything. Writing one is not an error, but it saves with a warning saying it will always be empty. {{secrets.NAME}}, {{args.*}} and {{tooldata.*}} are refused in a prompt here for the same reasons they are refused in an agent’s — see variables.

No draft, no publish

A task has one config, and saving it is what makes it live. There is no draft, no publish step and no version history.

Strict at save. create_task and update_task run every check that publishing an agent runs — including the ones an agent draft is allowed to defer, like a provider key for the model. An invalid config comes back as a 400 listing every problem at once, and nothing is stored. A task that exists can always run.
An edit takes effect on the next run, with nothing in between.
There is nothing to roll back to. No earlier wording is kept, and a run records the task’s name and nothing else about the definition that produced it. Two runs either side of an edit are indistinguishable in the history.

create_task and update_task return a warnings array beside the saved task. These are real problems that are not fatal — a prompt reading {{vars.emial}} that nothing declares, a task with no prompt at all. There is no publish screen to show them on, so read them where they come back.

Reference

Field	Type	Default	Bound	Meaning
`name`	string	—	required, unique in the workspace	For people, not the model. A duplicate is a `400`.
`prompt`	string	`""`	—	The system prompt, and the whole of the task’s behaviour. An empty one saves with a warning.
`llm`	object	`openai/gpt-5.6-luna`	one model	Same shape as an agent’s: `provider`, `model`, plus `fallback`, `reasoning_effort`, `priority` and `builtin_tools`. See models and thinking and provider tools.
`tools`	array	`[]`	published tools only	Tools the model may call. See tools and MCP servers.
`mcps`	array	`[]`	active integrations only	MCP servers whose tools it may call.
`vars`	array	`[]`	at most 25	The inputs. See inputs and output.
`output`	array	—	required, 1 to 25 fields	The typed result.
`max_steps`	integer	`25`	1 to 50	Model → tools → model rounds per attempt.
`timeout_seconds`	integer	`120`	10 to 600	The real time budget for the whole run.
`timezone`	string \| null	`null`	IANA name	The task’s clock, e.g. `"Asia/Kolkata"`. Only needed if the prompt or a tool reads it.

Nothing here is billed by Talqing. The platform fee is per minute on voice and video calls, and a task run is neither — what a run costs is your own provider spend on your own key, reported back as provider_cost. See pricing and credits.

In the dashboard

Tasks in the sidebar lists every task in the workspace, each row showing its signature — email → company_name, what_they_sell — and how its last run went. Opening one gives a single editor with Prompt, Model, Inputs and output, Tools, Limits and Run sections, a TaskCoPilot rail beside them, and one Save button with no publish next to it.

End to end

Create a task and run it. Tasks are regional: a task created against https://api.in.talqing.com does not exist in https://api.us.talqing.com, though the same token reaches both.

TASK_ID=$(curl -sS -X POST https://api.in.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.",
      "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. Send null only if the message is empty." },
        { "name": "is_urgent", "type": "boolean", "description": "True if the sender is blocked right now or reports an outage. Send null if the message gives no signal either way." }
      ]
    }
  }' | python3 -c 'import json,sys; print(json.load(sys.stdin)["task"]["id"])')

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

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

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

const { task, warnings } = 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.",
      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. Send null only if the message is empty.",
        },
        {
          name: "is_urgent",
          type: "boolean",
          description:
            "True if the sender is blocked right now or reports an outage. Send null if the message gives no signal either way.",
        },
      ],
    },
  },
});
warnings.forEach((w) => console.warn(w));

const run = await talqing.tasks.runs.create({
  task_id: task.id,
  runTaskRequest: { 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 the task finishes, so the client timeout must clear
# `timeout_seconds`. The default is 30 seconds.
with Talqing(
    token=os.environ["TALQING_API_KEY"],
    base_url="https://api.in.talqing.com",
    timeout=180.0,
) as talqing:
    written = 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."
            ),
            "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. Send null only if the message is empty.",
                },
                {
                    "name": "is_urgent",
                    "type": "boolean",
                    "description": "True if the sender is blocked right now or reports an outage. Send null if the message gives no signal either way.",
                },
            ],
        }
    )
    for warning in written["warnings"]:
        print("warning:", warning)

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

A completed run answers with the fields you declared:

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

Inputs and output

Declare what a task takes in and the typed result it must hand back.

Running and runs

Run one, read the trace, and understand attempts and steps_used.

Tools and MCP servers

Give a task something to do while it works.

Get started

Agents

Tools

Knowledge

Agent teams

Agent tasks

Telephony

Web & chat

Integrations

Email outbound

Observability

Guides

Platform

What a task is not

What the prompt can read

No draft, no publish

Reference

In the dashboard

End to end

Next

Inputs and output

Running and runs

Tools and MCP servers

​What a task is not

​What the prompt can read

​No draft, no publish

​Reference

​In the dashboard

​End to end

​Next

Inputs and output

Running and runs

Tools and MCP servers

What a task is not

What the prompt can read

No draft, no publish

Reference

In the dashboard

End to end

Next