ATS Backend Skill

Connect to and interact with the Agent Task Service (ATS) backend for task orchestration between AI agents and humans.

Overview

The Agent Task Service is a PostgreSQL-backed task orchestration platform that enables intelligent handoffs between agents and humans. Use this skill when you need to:

• Create, list, claim, or complete tasks
• Subscribe to real-time task events
• Send messages on task threads
• Coordinate work between agents and humans

Prerequisites

FIRST: Verify ATS CLI Installation

ats --version  # Requires v1.x+

If not installed:

npm install -g @difflabai/ats-cli

Default Server: https://ats.difflab.ai

Environment Variables:

• ATS_URL – Override server URL
• ATS_ACTOR_TYPE – Default actor type (human, agent, system)
• ATS_ACTOR_ID – Default actor ID
• ATS_ACTOR_NAME – Default actor display name

Configuration

ATS CLI stores defaults in ~/.ats/config:

{
  "url": "https://ats.difflab.ai",
  "actor": {
    "type": "agent",
    "id": "claude-code",
    "name": "Claude Code"
  }
}

Priority: CLI flags > environment variables > config file > defaults

Task Operations

List Tasks

# List pending tasks (default - what needs attention)
ats list

# List all tasks
ats list --all

# Filter by status, channel, type
ats list --status in_progress
ats list --channel reviews
ats list --type approval

# Combine filters
ats list --status pending --channel support --limit 10

# JSON output for scripting
ats list -f json | jq '.[] | .title'

Create a Task

# Simple task
ats create "Review the pull request"

# With options
ats create "Deploy to production" \
  --type deployment \
  --channel ops \
  --priority 8 \
  --description "Deploy v2.1.0 to production cluster"

# With JSON payload
ats create "Process data import" \
  --payload '{"source": "s3://bucket/data.csv", "rows": 50000}'

Priority levels: 1-10, higher is more urgent (default: 5)

Get Task Details

# Human-readable output
ats get 123

# JSON for scripting
ats get 123 -f json | jq '.status'

Update a Task

ats update 123 --priority 9
ats update 123 --title "Updated title" --description "New description"

Claim a Task (Start Working)

Claiming moves the task to in_progress and starts a lease timer:

ats claim 123

# Custom lease duration (ms)
ats claim 123 --lease 120000

Important: The lease expires after 60 seconds by default. If the worker crashes, the task returns to pending automatically.

Complete a Task

# Simple completion
ats complete 123

# With output data
ats complete 123 --outputs '{"result": "Approved", "notes": "LGTM"}'

Cancel a Task

ats cancel 123

Fail a Task

ats fail 123 --reason "Unable to connect to external service"

Reject a Task

ats reject 123 --reason "This task is outside my capabilities"

Reopen a Task

Reopen a task from a terminal state (completed, cancelled, failed, rejected) back to pending:

ats reopen 123

# With reason
ats reopen 123 --reason "Need to revisit this task"

Delete a Task

ats delete 123

Message Operations

Add a Message to a Task

# Simple text message
ats message add 123 "I've started working on this"

# With content type
ats message add 123 '{"status": "analyzing", "progress": 50}' --type data

List Messages for a Task

ats message list 123

# JSON output
ats message list 123 -f json

Real-Time Events

Watch for Events

# Watch all events
ats watch

# Filter by channel
ats watch --channel support

# Filter by task type
ats watch --type approval

# Filter by specific events
ats watch --events task.created,task.completed

Event Types:

• task.created – New task created
• task.claimed – Task claimed by worker
• task.updated – Task fields modified
• task.completed – Task finished successfully
• task.cancelled – Task cancelled
• task.failed – Task failed with error
• task.rejected – Task rejected by worker
• task.reopened – Task reopened from terminal state
• task.message – New message added
• task.lease_expired – Worker lease expired, task returned to pending

Task Status Flow

pending ──claim──→ in_progress ──complete──→ completed ──┐
   ↑                    │                                │
   │                    ├──cancel───→ cancelled ─────────┤
   │                    │                                │
   │                    ├──fail─────→ failed ────────────┼──reopen──→ pending
   │                    │                                │
   │                    └─(lease expires)─→ pending      │
   │                                                     │
   └──reject──→ rejected ────────────────────────────────┘

Terminal states: completed, cancelled, failed, rejected (all can be reopened)

Common Patterns

Pattern 1: Create Task and Wait for Human Response

# Create task for human review
TASK_ID=$(ats create "Approve deployment" --type approval --channel ops -f json | jq -r '.id')
echo "Created task: $TASK_ID"

# Poll for completion
while true; do
  STATUS=$(ats get $TASK_ID -f json | jq -r '.status')
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "rejected" ]; then
    echo "Task finished with status: $STATUS"
    break
  fi
  sleep 5
done

Pattern 2: Claim and Process Tasks

# Get first pending task of a specific type
TASK_ID=$(ats list --type code-review -f json | jq -r '.[0].id')

# Claim it
ats claim $TASK_ID

# Do the work...

# Complete with results
ats complete $TASK_ID --outputs '{"review": "LGTM, approved"}'

Pattern 3: Escalate to Human

When Claude Code encounters something requiring human decision:

ats create "Human decision required: Delete production database?" \
  --type escalation \
  --channel urgent \
  --priority 10 \
  --description "The user requested to delete the production database. This requires human approval." \
  --payload '{
    "context": "User command: DROP DATABASE production",
    "risk_level": "critical",
    "suggested_action": "confirm_with_user"
  }'

Pattern 4: Pipeline with jq

# Get high-priority pending tasks
ats list -f json | jq '.[] | select(.priority >= 8)'

# Count tasks by status
ats list --all -f json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Get task IDs for a channel
ats list --channel support -f json | jq -r '.[].id'

Actor Identity

Configure how you appear in ATS:

# As an agent (default for Claude Code)
ats list --actor-type agent --actor-id claude-code --actor-name "Claude Code Agent"

# As a human
ats list --actor-type human --actor-id user-123 --actor-name "John Doe"

# Or set via environment
export ATS_ACTOR_TYPE=agent
export ATS_ACTOR_ID=claude-code
export ATS_ACTOR_NAME="Claude Code Agent"

Health Check

ats health

Global Options

Quick Reference