Skip to content

Build

Saved tasks

Save output fields, rules or actions on the agent. Your application names the task and sends only its input.

Save a request your application can reuse

A saved task keeps one operation and its extraction schema, validation criteria, summary settings or offered actions. Test a request in Try agent, choose Save as task and give it a name. Your application then calls that name instead of sending the settings on every request.

  1. Test and save

    An integrator tests the input in Try agent and presses Save as task, or creates the task with the JavaScript SDK.

  2. Connect once

    Call agent.run with the task name and input. Connect includes an example for the saved task.

  3. Edit in the cabinet

    An Owner or Editor opens Tasks, edits the fields, rules or actions, runs the draft and saves. The next new request uses the saved revision.

  4. Inspect History

    Each operation keeps the task name, revision and settings used for that run.

Send the input, keep settings on the agent

JavaScript
import { NullProtocol } from 'nullprotocol';

const agent = await NullProtocol.load({
  key: process.env.NULLPROTOCOL_KEY,
  agentId: 'order-reader'
});

await agent.tasks.set('read-request', {
  operation: 'extract',
  schema: { orderId: 'number', problem: 'string' },
  ifRevision: null
});

const result = await agent.run(
  'read-request',
  'Order 1042 arrived with a broken mug.'
);
if (!result.success) throw new Error(result.error);
console.log(result.data);
console.log(result.task); // name, revision and operation

The result has the fields of the task’s operation plus task metadata. A missing task is task_not_found. JavaScript operation failures are returned as unsuccessful results; Python raises APIError for HTTP errors such as a missing task.

What stays with the task

OperationSaved settingsInput for each run
extractschemaText or JSON to read
summarizemaxLength (default 200), optional focusContent to summarize
validatecriteriaSubject, with an optional reference for this run
decideactions with optional descriptions and parameter schemasSituation to decide about

All tasks can save selected contextKeys and a boolean knowledge setting. The source documents remain connected to the agent; retrieval uses each run’s input. A run can supply images, a data scope and a Knowledge override. reference belongs only to validate tasks. HTTP task runs do not accept an operation, schema, criteria, actions or contextKeys in their body.

Execute a saved decision task

For a saved decide task named route-request that offers request_photo with a text parameter, register the handler locally. The caller does not need to repeat the offered action list.

JavaScript
import { NullProtocol } from 'nullprotocol';

const agent = await NullProtocol.load({
  key: process.env.NULLPROTOCOL_KEY,
  agentId: 'order-reader'
});

agent.registerAction('request_photo', ({ text }) => {
  // Save a request or call your authorized delivery service here.
  return { preparedText: text };
}, { input: {
  type: 'object', properties: { text: { type: 'string', minLength: 1 } },
  required: ['text'], additionalProperties: false
} });
const decision = await agent.run('route-request', 'The mug arrived broken.');
if (!decision.success) throw new Error(decision.error);
const execution = await agent.execute(decision);
if (!execution.success) throw new Error(execution.error);

HTTP returns a decision payload without executing application handlers. SDK execution requires the original decision object, not a serialized copy. See actions for guards and failure outcomes.

Save a new revision without losing another edit

JavaScript
const current = await agent.tasks.get('read-request');
await agent.tasks.set('read-request', {
  operation: 'extract',
  schema: { orderId: 'number', problem: 'string', priority: 'string' },
  ifRevision: current.revision
});
const tasks = await agent.tasks.list();
// Delete only when no caller still needs the name:
// await agent.tasks.delete('read-request');

set or PUT replaces the complete task and increments its revision. ifRevision: null creates only; a positive revision replaces only that revision. A competing edit returns 409 task_revision_conflict. Omitting ifRevision overwrites deliberately. Task names start with a lowercase letter and contain up to 64 lowercase letters, digits, dots, underscores or hyphens. Each agent can hold 32 tasks.

Run and manage tasks over HTTP

Terminal
curl --fail-with-body --request POST \
  'https://api.nullprotocol.ai/v1/agents/order-reader/tasks/read-request/run' \
  --header "Authorization: Bearer $NULLPROTOCOL_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ticket-1042-read-v1' \
  --data-raw '{ "input": "Order 1042 arrived with a broken mug." }'
Method and pathPurpose
GET /v1/agents/{agentId}/tasksList tasks
GET /v1/agents/{agentId}/tasks/{name}Read one task and revision
PUT /v1/agents/{agentId}/tasks/{name}Replace its operation and settings; optional ifRevision
DELETE /v1/agents/{agentId}/tasks/{name}Remove a task; callers using the name will fail
POST /v1/agents/{agentId}/tasks/{name}/runRun using input and optional reference, images, conversation or knowledge

These public routes use a Space SDK key. The cabinet uses corresponding member-authenticated routes under /v1/spaces/{slug}/agents/{agentId}/tasks: Viewers read, Owners and Editors write. Keep SDK keys on your server.

HTTP success shape
{
  "result": { "success": true, "data": { "orderId": 1042, "problem": "broken mug" } },
  "operationId": "the-history-operation-uuid",
  "task": { "name": "read-request", "revision": 1, "operation": "extract" }
}

The OpenAPI contract includes all public task routes. Run calls require Idempotency-Key and follow the HTTP retry rules. The task name is part of the fingerprint: using the same ID for another task on the same agent is an idempotency_mismatch. Replaying a completed request after editing its task returns the original response and revision; use a new ID for a new request that should use the changed settings.