Skip to main content
A task defines the input it accepts, the output it produces, and the work the agent performs on the source. You write the schema and task goal, Deck handles everything else. Every task run returns the same structured output regardless of which source it runs against, you only need a single task for every source.

​
How tasks fit in

Tasks belong to an agent. When you run a task, you provide the task input defined by its schema and either a source or a credential. Deck creates a session and a task run that executes the work.

​
Creating tasks

Tasks can be created in the Console with prompting or through the API. Once created, you reference them by ID in your API calls.

​
Writing the prompt

The prompt field tells the agent what to accomplish on the source. Describe the goal, not the steps to get there. A task runs across every source that supports it. The same “fetch my latest bill” task works on any utility provider, so the prompt should be source-agnostic. Don’t reference specific websites, page layouts, or UI elements. Your prompt gets combined with Deck’s agent harness, a built-in set of guidance that tells the agent how to navigate sites, handle authentication, recover from errors, and use its tools. When your prompt includes detailed navigation instructions, they can conflict with the harness or restrict tools the agent would otherwise use to complete the task. Keep your prompt focused on the outcome and let the harness handle execution. 
Log in to the source and fetch my latest bill.

Log in and fetch upcoming reservations.
These prompts describe what the agent should do. The agent handles the how.

​
Read vs. write

Tasks can be read operations (fetching data) or write operations (performing actions).
TypeExamples
ReadFetch account balance, list transactions, download statements
WriteSubmit a form, make a payment, cancel a reservation
The API treats both the same way. The distinction is in what the agent does on the source.

​
Input and output schemas

Every task defines a contract through JSON Schema:
  • Input schema validates what you send when running the task. Deck rejects requests that don’t match before the agent starts.
  • Output schema defines the structure of the data the agent returns. Regardless of how the source renders its data, Deck returns a consistent shape.
This contract means your integration code works the same way across sources. A “fetch reservations” task returns the same structure whether the source is Hilton, Marriott, or Hyatt.

​
Designing the input schema

Only include fields that change between runs. The input should capture what your application needs to parameterize, not how the source works. Keep it source-agnostic so the same task runs against any supporting source. 
{
  "start_date": "2026-04-01",
  "end_date": "2026-04-05"
}
Minimal, generic fields that apply to any source.

​
Accepting file inputs

File inputs are available on Enterprise plans. The extraction purpose additionally requires the extraction and storage add-ons.
File inputs are in preview and not yet generally available.
A task can accept files as input. Define a file field in the input schema as an object whose purpose selects how Deck handles the file, with data carrying the file as base64. Two purposes are supported:
purposeWhat Deck does
attachmentThe agent receives the file at run time and uses it on the source.
extractionDeck extracts structured JSON from the file directly. The agent is skipped.
{
  "name": "Submit application",
  "agent_id": "agt_a1b2c3d4...",
  "input_schema": {
    "type": "object",
    "properties": {
      "applicant_name": { "type": "string" },
      "resume": {
        "type": "object",
        "properties": {
          "purpose": { "const": "attachment" },
          "file_name": { "type": "string" },
          "content_type": { "type": "string" },
          "data": { "type": "string", "contentEncoding": "base64" }
        }
      }
    },
    "required": ["applicant_name", "resume"]
  }
}
See providing files as input for both purposes and the full walkthrough.

​
Designing the output schema

Design the output for what your application needs, not what a specific source displays. The schema should be generic enough to work across all sources that support the task. Fields come back null when a source doesn’t have that data. 
{
  "reservations": [
    {
      "confirmation_number": "HLT-849271",
      "hotel_name": "Hilton Garden Inn",
      "check_in": "2026-04-01",
      "check_out": "2026-04-05",
      "total_cost": 847.50
    }
  ]
}
Flat, generic fields. Any hotel source can populate these.

​
Tokenizing sensitive fields

Available on Enterprise plans.
Some tasks take sensitive input, such as a card number or CVV, that should never sit in plaintext in your task input or appear in logs. Declare those fields in a tokenized array on the input schema when you create the task. Each entry must match a property defined in properties. 
{
  "name": "Add payment method",
  "agent_id": "agt_...",
  "prompt": "Add a new payment method to the user's account.",
  "input_schema": {
    "type": "object",
    "properties": {
      "card_number":     { "type": "string" },
      "expiration":      { "type": "string" },
      "cvv":             { "type": "string" },
      "cardholder_name": { "type": "string" }
    },
    "required": ["card_number", "expiration", "cvv", "cardholder_name"],
    "tokenized": ["card_number", "cvv", "cardholder_name"]
  }
}
Here card_number, cvv, and cardholder_name are tokenized; expiration is sent normally. When you run the task, pass every field as usual. Deck tokenizes the marked values when the run is created, storing them in a secure vault, and restores the originals when the run is dispatched for execution so the agent can use them on the source. The run stores tokens in place of the real values, never the values themselves. In API responses, tokenized fields are removed from the run’s input entirely, and a tokenized array lists which field names were removed. You can’t query the original values back through the API.

​
Task statuses

StatusMeaning
learningThe agent is learning how to perform the task. You can run it, but expect lower success rates.
testThe agent understands the task but is still improving. Higher success rates than learning.
liveProduction-ready. The agent fully understands the task.
A task graduates after 3 successful runs in its current stage: learning → test after 3 successes, then test → live after 3 more. Check status on the task object to see where it currently sits. If you update a task, it may move back to learning or test while the agent adapts to the changes.

​
Resetting a task

Once a task has progressed to test or live, the agent reuses what it has learned on subsequent runs. If the task is struggling to deliver successful results or you want the agent to start over, you can reset the task back to learning. Reset a task from the Console on the task detail page, or call POST /tasks/{task_id}/reset. The task’s status returns to learning, and on the next run the agent learns how to perform the task again. Expect lower success rates until it progresses back to test or live.

​
Deep dives

Storage

Capture files during task execution and extract structured data.

Task runs

What happens when you execute a task.