Tasks & Output

Tasks and Output

A task is the core unit of work in AgentContainer. You dispatch a task to an agent, the agent runs autonomously inside a sandboxed container, and you retrieve the output when it finishes. This guide covers every step of that lifecycle — from dispatching and uploading input files, through the container execution, to retrieving results.

Before continuing, make sure you have an API key ready. See the Authentication docs if you need to generate one.

Dispatching a Task

To create a task, send a POST request to the agent's tasks endpoint:

POST https://api.agentcontainer.com/api/v1/agents/{agentId}/tasks

The request body accepts the following fields:

• description (required) — A natural-language description of what the agent should do. This becomes the task prompt.
• versionId — Pin the task to a specific agent version. If omitted, the agent's current active version is used.
• inputFileIds — An array of file IDs to make available inside the container. See Uploading Input Files below.
• metadata — An arbitrary JSON object stored alongside the task. Useful for tracking external references or tags.
• overrides — Per-task overrides for the agent's default configuration. See Per-Task Overrides.

Here is a minimal example that dispatches a task:

curl -X POST https://api.agentcontainer.com/api/v1/agents/agt_abc123/tasks \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Analyze the CSV file and produce a summary report in Markdown."
  }'

A successful response returns the new task object:

{
  "id": "tsk_xyz789",
  "agentId": "agt_abc123",
  "status": "pending",
  "description": "Analyze the CSV file and produce a summary report in Markdown.",
  "createdAt": "2026-03-26T14:00:00.000Z"
}

Balance requirement: AgentContainer reserves $0.50 from your balance when a task starts. If your balance is below $0.50, the task will not start and the request will return an error. Visit the Billing docs for details on how credits and usage charges work.

Uploading Input Files

If your task needs input files (datasets, images, configuration files, etc.), you upload them through a two-step process before dispatching the task.

Step 1: Prepare the upload

Call the prepare endpoint with the file name and MIME type. This returns an uploadId and a pre-signed uploadUrl.

curl -X POST https://api.agentcontainer.com/api/v1/uploads/prepare \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "sales_data.csv",
    "mimeType": "text/csv"
  }'

Response:

{
  "uploadId": "upl_abc123",
  "uploadUrl": "https://storage.convex.cloud/upload/..."
}

Step 2: Upload the file bytes

Send the raw file contents to the uploadUrl returned in the previous step.

curl -X POST "https://storage.convex.cloud/upload/..." \
  -H "Content-Type: text/csv" \
  --data-binary @sales_data.csv

The storage service returns a storageId in the response body.

Step 3: Complete the upload

Finalize the upload by sending the uploadId and storageId back to AgentContainer. This registers the file and returns a file ID you can reference in tasks.

curl -X POST https://api.agentcontainer.com/api/v1/uploads/complete \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "upl_abc123",
    "storageId": "stor_def456"
  }'

The response includes a fileId. Pass this ID (or multiple IDs) in the inputFileIds array when you dispatch the task:

curl -X POST https://api.agentcontainer.com/api/v1/agents/agt_abc123/tasks \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Analyze the CSV and produce a summary report.",
    "inputFileIds": ["file_ghi789"]
  }'

Task Lifecycle

Every task moves through a well-defined set of statuses:

pending  -->  running  -->  finished
                       |-->  failed
                       |-->  cancelled

• pending — The task has been created and is waiting for a container to become available.
• running — The container is active and the agent is executing the task.
• finished — The agent completed the task successfully (called finish).
• failed — The task encountered an unrecoverable error (crash, timeout, or infrastructure failure).
• cancelled — The task was cancelled by the user before completion.

Polling for status

Use the task detail endpoint to check on a running task. Poll until the status is one of the terminal states (finished, failed, or cancelled).

curl https://api.agentcontainer.com/api/v1/tasks/tsk_xyz789 \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx"

Cancelling a task

If you need to stop a running task, send a cancel request. The container will be shut down and the task status will move to cancelled.

curl -X POST https://api.agentcontainer.com/api/v1/tasks/tsk_xyz789/cancel \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx"

See the API Reference for the full response schema of both endpoints.

What Happens Inside the Container

When a task moves to running, AgentContainer provisions a sandboxed Linux container and sets up the workspace. Here is what the agent sees:

• ~/TASK.md — The task description you provided is written to this file. This is the primary instruction the agent reads.
• ~/task_files/ — Any input files you attached via inputFileIds are placed in this directory, using their original file names.
• ~/reference_files/ — Reference files configured on the agent (documentation, templates, style guides, etc.) are placed here. These persist across tasks and help the agent understand your project context.

Once the workspace is ready, Claude Code starts running autonomously. It reads the agent's base prompt (configured when you created the agent), then reads ~/TASK.md and any reference materials. The agent works through the task — writing code, running commands, reading files — until it determines the work is complete.

When the agent is done, it calls the finish helper to signal completion and declare output files. This is the only way a task reaches the finished status. See the next section for details on the finish convention.

For more on how agents and containers are structured, see the Concepts page.

The finish Convention

The finish command is a helper available inside every AgentContainer container. It is the mechanism the agent uses to signal that work is done and to declare output files. The daemon process running alongside the agent validates the finish request against the task's output policy before accepting it.

Successful completion

When the agent completes the task successfully, it calls finish with the --complete-task flag, a message, and any output files:

finish --complete-task --message "Analysis complete. Report generated." report.md charts.png

Incomplete completion

Sometimes the agent cannot fully satisfy the task — perhaps the input data was malformed, or a required external service was unreachable. In these cases, the agent calls finish with --incomplete-task:

finish --incomplete-task --message "CSV had missing columns; partial analysis attached." partial_report.md

An incomplete finish is still a controlled completion, not a failure. The task status will be finished in both cases. The difference is recorded in the task metadata so you can distinguish between fully complete and partially complete work. A failed status, by contrast, indicates an uncontrolled exit — a crash, timeout, or infrastructure error.

Output Policies

An output policy defines the rules for what files a task must (or must not) produce. The policy is set on the agent and can be overridden per task. When the agent calls finish, the daemon validates the declared output files against the policy. If the validation fails, the finish request is rejected and the agent must try again.

There are four output policies:

• any — Zero or more files, no constraints. This is the default policy. The agent can finish with or without output files.
• none — The task produces no output files. The agent must call finish without listing any files. This is useful for tasks that perform side effects (sending emails, updating databases) rather than producing artifacts.
• at_least_one — The agent must declare at least one output file when calling finish. Use this when you always expect a deliverable from the task.
• named — The agent must produce specific named outputs. With this policy, the agent uses the --output name=path syntax to map logical output names to file paths:

finish --complete-task --message "Done" \
  --output report=analysis_report.md \
  --output dataset=cleaned_data.csv

The named policy is especially useful when you are building automations that depend on specific output artifacts — your code can retrieve files by their logical name rather than guessing file paths.

Retrieving Output Files

Once a task reaches the finished status, you can list and download its output files.

List output files

Retrieve the list of files the agent declared when it called finish:

curl https://api.agentcontainer.com/api/v1/tasks/tsk_xyz789/files \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx"

Response:

{
  "files": [
    {
      "id": "file_out001",
      "name": "report.md",
      "mimeType": "text/markdown",
      "sizeBytes": 4096
    },
    {
      "id": "file_out002",
      "name": "charts.png",
      "mimeType": "image/png",
      "sizeBytes": 102400
    }
  ]
}

Download a file

Use the file ID to download a specific output file. The response body is the raw file content.

curl https://api.agentcontainer.com/api/v1/tasks/tsk_xyz789/files/file_out001 \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -o report.md

For the complete file endpoints, including error codes and optional query parameters, see the API Reference.

Per-Task Overrides

Every agent has default settings for model, internet access, max runtime, and output policy. You can override any of these on a per-task basis by including an overrides object in the task creation request. This is useful when a specific task needs a different model, longer runtime, or a stricter output policy than the agent's defaults.

{
  "description": "Generate a detailed financial model from the uploaded spreadsheet.",
  "inputFileIds": ["file_ghi789"],
  "overrides": {
    "model": "claude-sonnet-4.6",
    "internetAccess": false,
    "maxRuntimeSeconds": 1800,
    "outputPolicy": "at_least_one"
  }
}

The available override fields are:

• model — The Claude model to use for this task. Overrides the agent's default model.
• internetAccess — Whether the container has outbound internet access. Set to false for tasks that should run in a fully isolated environment.
• maxRuntimeSeconds — Maximum wall-clock time the task is allowed to run before being terminated. If the task exceeds this limit, it will be marked as failed.
• outputPolicy — The output policy for this specific task. Accepts any, none, at_least_one, or named. See Output Policies above.

Overrides only apply to the individual task — they do not change the agent's default configuration.