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.
- Test and save
An integrator tests the input in Try agent and presses Save as task, or creates the task with the JavaScript SDK.
- Connect once
Call agent.run with the task name and input. Connect includes an example for the saved task.
- 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.
- Inspect History
Each operation keeps the task name, revision and settings used for that run.
Send the input, keep settings on the agent
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 operationThe 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
| Operation | Saved settings | Input for each run |
|---|---|---|
| extract | schema | Text or JSON to read |
| summarize | maxLength (default 200), optional focus | Content to summarize |
| validate | criteria | Subject, with an optional reference for this run |
| decide | actions with optional descriptions and parameter schemas | Situation 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.
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
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
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 path | Purpose |
|---|---|
| GET /v1/agents/{agentId}/tasks | List 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}/run | Run 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.
{
"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.