Create tasks from your own system, assign them to an agent, start runs and follow the result.

This is the most common integration: your ERP, CRM or back office creates work in AgentWorks, an agent picks it up, and your system reads the outcome.

Scopes for this guide: tasks:write, agents:read, agents:run, runs:read.

Find the agent

curl "$AGENTWORKS_API_URL/agents/?limit=50" \
  -H "Authorization: Bearer $AGENTWORKS_API_KEY"

Keep the id of the agent that should do the work. A key only sees the agents its owner can see: their own agents and the ones shared with them.

Create a task

curl -X POST "$AGENTWORKS_API_URL/tasks" \
  -H "Authorization: Bearer $AGENTWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Check invoice 2026-0412",
    "description": "Compare the invoice with purchase order PO-881 and report differences.",
    "priority": "high",
    "due_date": "2026-10-12T17:00:00Z"
  }'

Only title is required. priority is one of urgent, high, medium, low, none. The response is the task, including its id and its number on the board.

Assign it to an agent

curl -X PATCH "$AGENTWORKS_API_URL/tasks/$TASK_ID/assignee" \
  -H "Authorization: Bearer $AGENTWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "agent", "id": "'$AGENT_ID'"}'

type is agent or user. Send {"type": null, "id": null} to unassign. The body takes exactly these two fields; anything else is refused with 422.

Start a run directly

You can also start an agent without a task:

curl -X POST "$AGENTWORKS_API_URL/agents/$AGENT_ID/run" \
  -H "Authorization: Bearer $AGENTWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"task": "Summarise the open invoices of customer 1042."}}'

input is a JSON object of text values; put the instruction for this run in task. The response gives you a run_id, the chat_id of the run's conversation and a status.

Follow the run

curl "$AGENTWORKS_API_URL/runs/$RUN_ID" \
  -H "Authorization: Bearer $AGENTWORKS_API_KEY"

The run carries its status, a summary when it has finished, cost_euros, the tokens used and the time it took. For a task, list its runs with GET /tasks/{task_id}/runs, or read last_run_status on the task itself.

Poll at a calm pace (every few seconds is plenty) and stay inside the rate limits.

When a run waits for a person

An agent can pause because it needs an approval or has a question.

Approvals are decided by a person in the app. A key cannot approve or reject. With approvals:read you can list what is waiting and show it in your own system.
Questions can be answered over the API with agents:run: POST /agents/{agent_id}/runs/{run_id}/respond.

Stop or retry

POST /agents/runs/{run_id}/cancel stops a run and POST /agents/runs/{run_id}/retry starts it again. Both need agents:run.

Hand work to agents