> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Tasks
> A task tells an agent what to do and what to return.
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](/concepts/agents). When you run a task, you provide the task input defined by its schema and either a source or a [credential](/concepts/credentials). Deck creates a [session](/concepts/sessions) and a [task run](/concepts/task-runs) 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.
```text theme={null}
Log in to the source and fetch my latest bill.
```
```text theme={null}
Find upcoming reservations and return the confirmation details.
```
These prompts describe **what** the agent should do. The agent handles the how.
```text theme={null}
Go to the login page, click the sign-in button, enter the username
in the email field, click submit, then navigate to the billing
section and click on the most recent invoice.
```
Step-by-step instructions fight the agent instead of guiding it. They assume a specific site layout that may differ across sources or change over time.
## Read vs. write
Tasks can be read operations (fetching data) or write operations (performing actions).
| Type | Examples |
| ----- | ------------------------------------------------------------- |
| Read | Fetch account balance, list transactions, download statements |
| Write | Submit 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.
```json theme={null}
{
"start_date": "2026-04-01",
"end_date": "2026-04-05"
}
```
Minimal, generic fields that apply to any source.
```json theme={null}
{
"start_date": "2026-04-01",
"end_date": "2026-04-05",
"hilton_rewards_id": "HH-9281744",
"booking_portal_region": "us-east"
}
```
Source-specific fields break the task for other sources.
### 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.
```json theme={null}
{
"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.
```json theme={null}
{
"hilton_honors_data": {
"tier_status": "Gold",
"points_breakdown": {
"base_points": 12000,
"bonus_points": 3000,
"milestone_bonuses": 5000
}
}
}
```
Mirrors a single source's data model. Other sources can't fill these fields.
## Task statuses
| Status | Meaning |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `learning` | The agent is learning how to perform the task. You can run it, but expect lower success rates. |
| `test` | The agent understands the task but is still improving. Higher success rates than `learning`. |
| `live` | Production-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`](/api-reference/tasks/reset-a-task). 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
Capture files during task execution and extract structured data.
What happens when you execute a task.