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
Create the task once in the cabinet, JavaScript SDK or HTTP API. Python 0.5.0 runs saved tasks; it does not provide task-management methods.
from nullprotocol import NullProtocol
with NullProtocol() as client:
agent = client.load("order-reader")
result = agent.run(
"read-request",
"Order 1042 arrived with a broken mug.",
idempotency_key="ticket-1042-read-v1",
)
if not result.success:
raise RuntimeError(result.error)
print(result.data)
print(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.
from nullprotocol import NullProtocol
with NullProtocol() as client:
agent = client.load("order-reader")
agent.register_action(
"request_photo",
lambda parameters, context: {"preparedText": parameters["text"]},
input_schema={
"type": "object",
"properties": {"text": {"type": "string", "minLength": 1}},
"required": ["text"],
"additionalProperties": False,
},
)
decision = agent.run("route-request", "The mug arrived broken.")
if not decision.success:
raise RuntimeError(decision.error)
execution = agent.execute(decision)
if not execution.success:
raise RuntimeError(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
Manage tasks in the cabinet or through the HTTP routes below. Python task management is not part of version 0.5.0.
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.