AGNT Tasks

Async task creation and AI-powered execution. Tasks are discrete units of work — assigned to assistants, tracked through status changes, and processed by AI agents that can execute multi-step workflows autonomously.

Why AGNT Tasks

AI agents need a work queue. Not a chat-style back-and-forth, but a structured task with a title, description, status, assignees, and an execution history. AGNT Tasks gives agents something to actually do — and gives you visibility into what they did.

Tasks bridge the gap between "AI responded to a message" and "AI completed a workflow." A chat might generate tasks. A task might spawn other tasks. The execution pipeline handles retries, status transitions, and feedback loops without you building any of it.

Quick Start

Create a task, assign it to an assistant, and kick off AI processing:

# Create a task
curl -X POST https://api.agnt.ai/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Schedule Q2 planning meeting",
    "assistant": "asst_abc123",
    "description": "Find a 90-minute slot next week that works for the leadership team.",
    "type": "scheduling"
  }'

# Queue the task for AI processing
curl -X POST https://api.agnt.ai/tasks/task_def456/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Prioritize mornings if possible."
  }'

# Check task status
curl https://api.agnt.ai/tasks/task_def456 \
  -H "Authorization: Bearer $TOKEN"

Core Concepts

Task Lifecycle

Every task moves through a status progression:

Status transitions are managed by the system during processing. You can also force a status change via the update endpoint, but the process and stop endpoints are the standard way to drive the lifecycle.

Assistants and Assignment

Every task requires an assistant — the AI agent responsible for execution. Tasks can also have assignedUsers (human users involved) and followers (users who want visibility but aren't directly responsible).

Assignees are managed by email. The PUT /tasks/:taskId/assignees endpoint takes an array of email addresses. Users are auto-provisioned if they don't exist yet.

Processing

POST /tasks/:taskId/process queues the task for AI execution. You can include a message (additional context or instructions) and files (attachments the agent should reference).

Processing is async. The task moves to in_progress and the agent begins execution. The agent may use skills, access memory, consult calendars, or perform any other action available to it.

Activities and Executions

The task object includes two history arrays:

• activities: A log of everything that happened — status changes, messages, assignments, human feedback. This is the audit trail.
• executions: Records of each AI processing run — what the agent did, what it returned, how long it took. This is the technical trace.

When you GET /tasks/:taskId, both are included in the response. For large task histories, this gives you full observability without hitting separate endpoints.

Feedback Loop

The feedback endpoint lets users signal quality:

• like — the task result was good
• dislike — the task result was bad
• null — clear previous feedback

This isn't cosmetic. Feedback is stored in the activity log and can influence future agent behavior through the memory system.

Stopping Execution

POST /tasks/:taskId/stop halts the current execution and sets the status to on_hold. Use this when an agent is heading in the wrong direction or when you need to provide additional context before it continues.

A stopped task can be resumed by calling process again with updated instructions.

API Reference

Endpoints

Task Object

{
  "id": "task_def456",
  "account": "acc_org789",
  "title": "Schedule Q2 planning meeting",
  "description": "Find a 90-minute slot next week that works for the leadership team.",
  "assistant": "asst_abc123",
  "type": "scheduling",
  "status": "completed",
  "ownerEmail": "jane@example.com",
  "assignedUsers": ["jane@example.com", "bob@example.com"],
  "followers": ["cto@example.com"],
  "skills": ["calendar-management", "email-outreach"],
  "activities": [
    {
      "type": "status_change",
      "from": "pending",
      "to": "in_progress",
      "timestamp": "2026-02-28T14:01:00.000Z"
    },
    {
      "type": "status_change",
      "from": "in_progress",
      "to": "completed",
      "timestamp": "2026-02-28T14:03:00.000Z"
    }
  ],
  "executions": [
    {
      "id": "exec_001",
      "status": "completed",
      "startedAt": "2026-02-28T14:01:00.000Z",
      "completedAt": "2026-02-28T14:03:00.000Z"
    }
  ],
  "createdAt": "2026-02-28T14:00:00.000Z",
  "updatedAt": "2026-02-28T14:03:00.000Z"
}

List Tasks

GET https://api.agnt.ai/tasks

curl "https://api.agnt.ai/tasks?status=in_progress&mine=true&page=1&perPage=10" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "task_def456",
      "title": "Schedule Q2 planning meeting",
      "status": "in_progress",
      "type": "scheduling",
      "assistant": "asst_abc123",
      "ownerEmail": "jane@example.com",
      "assignedUsers": ["jane@example.com"],
      "followers": [],
      "skills": [],
      "createdAt": "2026-02-28T14:00:00.000Z",
      "updatedAt": "2026-02-28T14:01:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 1
  }
}

Create Task

POST https://api.agnt.ai/tasks

curl -X POST https://api.agnt.ai/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Draft Q2 OKRs document",
    "assistant": "asst_abc123",
    "description": "Create a first draft of Q2 OKRs based on the strategy memo and last quarter results.",
    "type": "document-creation",
    "skills": ["document-drafting", "data-analysis"],
    "assignedUsers": ["jane@example.com"],
    "followers": ["cto@example.com", "vp-eng@example.com"]
  }'

{
  "id": "task_new001",
  "account": "acc_org789",
  "title": "Draft Q2 OKRs document",
  "description": "Create a first draft of Q2 OKRs based on the strategy memo and last quarter results.",
  "assistant": "asst_abc123",
  "type": "document-creation",
  "status": "pending",
  "ownerEmail": "jane@example.com",
  "assignedUsers": ["jane@example.com"],
  "followers": ["cto@example.com", "vp-eng@example.com"],
  "skills": ["document-drafting", "data-analysis"],
  "activities": [],
  "executions": [],
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-01T10:00:00.000Z"
}

Get Task

GET https://api.agnt.ai/tasks/:taskId

Returns the full task object including activities and executions.

curl https://api.agnt.ai/tasks/task_def456 \
  -H "Authorization: Bearer $TOKEN"

Update Task

PUT https://api.agnt.ai/tasks/:taskId

Update any mutable field on the task. You can change title, description, type, status, skills, or followers.

curl -X PUT https://api.agnt.ai/tasks/task_def456 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Schedule Q2 planning meeting (updated)",
    "description": "Find a 90-minute slot. Leadership team plus new VP of Product."
  }'

{
  "id": "task_def456",
  "title": "Schedule Q2 planning meeting (updated)",
  "description": "Find a 90-minute slot. Leadership team plus new VP of Product.",
  "status": "pending",
  "updatedAt": "2026-03-01T10:15:00.000Z"
}

Delete Task

DELETE https://api.agnt.ai/tasks/:taskId

Permanently deletes the task, its activities, and its execution history. Irreversible.

curl -X DELETE https://api.agnt.ai/tasks/task_def456 \
  -H "Authorization: Bearer $TOKEN"

Update Assignees

PUT https://api.agnt.ai/tasks/:taskId/assignees

Replaces the full assignee list. This is a set operation, not an append.

curl -X PUT https://api.agnt.ai/tasks/task_def456/assignees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["jane@example.com", "bob@example.com", "new-hire@example.com"]
  }'

{
  "id": "task_def456",
  "assignedUsers": ["jane@example.com", "bob@example.com", "new-hire@example.com"],
  "updatedAt": "2026-03-01T10:20:00.000Z"
}

Send Feedback

POST https://api.agnt.ai/tasks/:taskId/feedback

curl -X POST https://api.agnt.ai/tasks/task_def456/feedback \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "like"
  }'

{
  "id": "task_def456",
  "feedback": "like",
  "updatedAt": "2026-03-01T10:25:00.000Z"
}

Stop Execution

POST https://api.agnt.ai/tasks/:taskId/stop

Halts the current AI execution and sets the task status to on_hold. No request body needed.

curl -X POST https://api.agnt.ai/tasks/task_def456/stop \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "task_def456",
  "status": "on_hold",
  "updatedAt": "2026-03-01T10:30:00.000Z"
}

Process Task

POST https://api.agnt.ai/tasks/:taskId/process

Queues the task for AI execution. The task moves to in_progress and the agent begins working.

curl -X POST https://api.agnt.ai/tasks/task_def456/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "The VP of Product prefers afternoon meetings. Also check if the large conference room is available.",
    "files": []
  }'

{
  "id": "task_def456",
  "status": "in_progress",
  "updatedAt": "2026-03-01T10:35:00.000Z"
}

For Coding Agents

If you're an AI coding agent integrating with AGNT Tasks, here's what matters:

1. Create, then process. Task creation and processing are separate steps. Create the task first to get an ID, then call process to start execution. This lets you attach metadata, set assignees, and configure the task before the agent starts working.

2. Use needs_clarification as a handoff signal. When a task enters this status, the agent is blocked and waiting for input. Call process again with a message containing the clarification to resume.

3. Poll or webhook for completion. Processing is async. After calling process, the task is in in_progress. Poll GET /tasks/:taskId to check status, or configure webhooks (if available) to get notified on status changes.

4. Use type for routing. The type field is freeform — use it to categorize tasks for your own filtering and dashboards. Common patterns: scheduling, research, document-creation, data-analysis, outreach.

5. Use skills to scope agent capabilities. The skills array tells the agent which tools it can use during execution. Omit skills to let the agent use its full toolkit, or restrict it for focused execution.

6. Check activities for the full story. The activities array is the source of truth for what happened. Every status change, every message, every assignment update is logged there.

7. Stop before redirecting. If a task is going in the wrong direction, call stop first, then process with corrected instructions. Don't just call process on an in-progress task — stop it cleanly first.

For Product Teams

AGNT Tasks turns AI assistants into workers that complete things, not just responders that answer things. Here's how to think about it:

Tasks are the execution primitive. Chats are conversations. Tasks are work items. A single chat message like "schedule a meeting" can create a task that the agent works on autonomously — checking calendars, sending invites, handling conflicts — without further user interaction.

Status visibility without a dashboard. Every task has a clear status, an activity log, and execution records. You get full observability into what the agent is doing without building monitoring infrastructure. Filter by status, search by title, scope to a user with mine=true.

Human-in-the-loop built in. The needs_clarification status creates a natural handoff point. The agent works until it's blocked, signals that it needs input, and waits. The user provides clarification, and the agent resumes. No custom state machine required.

Feedback closes the loop. The like/dislike feedback mechanism is simple by design. It creates a signal that flows back to the agent through the memory system over time, improving future task execution without explicit retraining.

Assignees and followers model real teams. Tasks aren't just agent work — they involve people. Assign users to tasks, add followers for visibility, and manage the human side of AI-powered workflows through familiar email-based identity.