A structured result is the output of a task arranged in fields, artifacts, and named states that software can inspect without guessing what the person meant.
For an AI agent, “done” is not a useful result. The agent needs to know what was done, what evidence came back, whether the acceptance test passed, and what differed from the brief. A structured result makes those facts explicit.
A result is more than the artifact
Suppose an agent asks a person to photograph six storefront signs.
The photographs are artifacts. They are important, but they do not answer every question the workflow has:
- Which image belongs to which address?
- When was each image captured?
- Was the sign visible?
- Did the participant visit all six locations?
- Were any locations closed or inaccessible?
- Does the submission meet the acceptance test?
A structured result packages the images with the fields needed to interpret them. It might include one row per address, a timestamp, a visibility status, a short note, and a link to the corresponding image.
The artifact shows what the participant observed. The structure tells the workflow how to use it.
The result contract starts before the work
A reliable result cannot be designed after a participant submits the work. Its shape should be part of the task brief.
Before execution, the requester should state:
- 1.the action to perform;
- 2.the expected artifacts;
- 3.the structured fields to return;
- 4.the acceptance test;
- 5.the fallback for predictable problems;
- 6.and how to report an exception.
Taskin's public API reflects this sequence. Its preflight endpoint requires an expected result and an acceptance test before a bounded task can be submitted. That forces the requester to define what the workflow needs back while the task can still be corrected.
A weak brief asks for “a report.” A usable brief asks for a PDF with three named sections, a JSON object containing five required fields, and a list of source links for every factual claim.
What belongs in a structured result?
The right schema depends on the task. Most results need some combination of the following.
Task identity
The result should point to the task, accepted brief version, requesting principal, and participant. This prevents a valid artifact from being attached to the wrong request.
Completion state
Use a named state such as submitted, partially completed, blocked, or declined. Do not force every outcome into complete or failed. Human work often encounters conditions the requester could not see in advance.
Structured fields
These are the facts the next system needs to read. A location check might return:
- access status;
- address confirmed;
- opening hours displayed;
- sign visible;
- and observation time.
A review task might return a decision, the reasons for it, the evidence examined, and any unresolved question.
Artifacts
Photographs, documents, audio, video, forms, or written assessments may carry the primary evidence. Each artifact should have a stable label or identifier so the agent can connect it to the relevant field.
Capture conditions
Time, location, device data, method, or other conditions can change how much confidence a result deserves. These fields should be requested only when relevant and lawful.
Deviations and exceptions
Reality does not always match the brief. The location may be closed. A document may no longer exist. A sign may be hidden by scaffolding.
The participant should report the deviation and follow the stated fallback. A well-formed exception is often a valid result. Hiding the exception creates a more dangerous failure because the output looks complete when it is not.
Participant declaration
For sensitive tasks, the result may include a statement confirming what the participant personally did or observed. This is not proof of every underlying fact, but it makes the source of the claim clear.
Structured does not mean trustworthy by default
JSON can be wrong. A complete form can contain a mistaken observation. A timestamp can be inaccurate. Structure improves legibility; it does not prove truth.
Trust comes from the full result design:
- a bounded brief;
- a suitable and willing participant;
- relevant evidence;
- a defined collection method;
- an acceptance test;
- and a record of changes and decisions.
The agent should inspect both the data and its provenance. If the task requires a licensed professional, verified identity, or a specific collection method, those requirements belong in the brief and must be confirmed. They should not be inferred from a tidy response object.
Preserve uncertainty instead of cleaning it away
One of the worst result designs requires an answer when the participant does not know.
Consider a field named business_open that accepts only true or false. A participant arrives during the stated hours but finds the door locked and no notice posted. Choosing either value would overstate the observation.
A safer schema could allow:
{
"business_status": "uncertain",
"observation": "Door locked at 14:10; no closure notice visible",
"evidence": ["img_01", "img_02"],
"follow_up_recommended": true
}The agent can now route the uncertainty instead of treating an invented binary answer as fact.
Useful schemas make room for unknown, not observed, not applicable, blocked, and requires clarification. Those values are part of the result, not defects to remove.
Design the acceptance test around the task
An acceptance test should be objective enough for a person and a machine to apply consistently.
For the storefront example, the test could require:
- one record for each requested address;
- at least one legible exterior image per address;
- timestamps inside the requested window;
- a visibility status for every sign;
- and a deviation note when an image could not be captured.
This checks whether the participant completed the requested process. It does not demand that every store be open or every sign be visible.
That distinction protects both sides. The requester receives usable evidence. The participant is not penalized for reporting the world as it is.
The result has three layers
Teams often use “result,” “evidence,” and “verification” as if they mean the same thing. They do not.
The result is the complete response returned to the workflow. It includes status, fields, artifacts, exceptions, and provenance.
The evidence is the material supporting the response: photographs, documents, recordings, measurements, source links, or a participant's written observation.
Verification is the process used to decide how much confidence to place in the result. It may involve checking metadata, comparing fields with the brief, confirming a credential, asking a second person, or sending a sensitive case to an accountable reviewer.
Keeping the layers separate prevents a common mistake: treating the presence of evidence as proof that every claim is correct. A photograph can be genuine but attached to the wrong location. A professional licence can be valid but irrelevant to the requested jurisdiction. A complete form can still contain a mistaken judgment.
The task should therefore define both what must return and how consequential claims will be checked.
A schema should match the decision downstream
The best result schema is not the most detailed one. It is the smallest schema that supports the next legitimate decision.
Start with the consuming workflow:
- 1.What decision will be made from this result?
- 2.Which facts are required to make that decision?
- 3.Which facts need evidence?
- 4.Which values are allowed?
- 5.Which conditions require human review?
- 6.What must never be inferred automatically?
If the next step only needs to know whether a public notice is displayed, asking for a broad narrative report creates unnecessary work and ambiguous output. If the result will determine a regulated or high-impact action, a binary field may be dangerously thin.
Fields should have clear types and units. Dates need a timezone. Money needs a currency. Measurements need units. Categories need defined values. Free text should be reserved for observations that cannot be captured safely in a fixed field.
Result schemas need version control
A result schema can change as a workflow learns. That creates a compatibility problem.
If version one returns status: complete and version two replaces it with outcome: observed | blocked | partial, downstream systems must know which version they received. Without a schema version, the same field name can acquire a different meaning without warning.
A durable result should identify:
- the task and accepted brief version;
- the result-schema version;
- when the result was created;
- which participant or system supplied each field;
- and whether any field was transformed after submission.
Schema changes should be additive where possible. Removing or redefining a field can break a live workflow even when the human work itself was correct.
Common result-design failures
A completion flag without evidence
A single completed: true value says nothing about what happened. It is useful only when the system can connect it to the agreed artifacts and acceptance test.
Free text for facts the workflow must route
If an agent needs to distinguish closed, inaccessible, unsafe, and not found, those should be named values. Burying them in a paragraph forces a model to reinterpret the result every time.
Required certainty
Schemas that accept only yes or no encourage false confidence. Add values for unknown, not observed, blocked, and not applicable when those outcomes can occur.
Evidence without a field relationship
Ten uploaded photographs are difficult to use when the workflow cannot tell which address, item, or claim each photograph supports.
Silent normalization
A system may clean spelling, reformat dates, or map a participant's words into a category. The original submission and the transformation should remain visible when the distinction matters.
Unbounded personal data
A result should not collect identity, location, images, or other personal information merely because it may be useful later. Request the minimum required for the stated decision and retention policy.
How an agent uses the result
A structured result lets an agent take a defined next action. It can:
- validate required fields;
- compare the submission with the acceptance test;
- ask for a missing item;
- route an exception to a human reviewer;
- update another system;
- continue the workflow;
- or close the task and record the decision.
The workflow should not rely on a language model to infer every status from unstructured prose. Models can help summarize or classify a submission, but required facts should still have named fields and allowed values.
An example result
A hybrid document-collection task might return:
{
"task_reference": "tsk_123",
"state": "submitted",
"brief_version": 2,
"outcome": "partially_completed",
"fields": {
"office_visited": true,
"form_obtained": true,
"fee_schedule_obtained": false
},
"artifacts": [
{"id": "doc_01", "type": "pdf", "label": "permit_application"},
{"id": "img_01", "type": "image", "label": "posted_requirements"}
],
"deviations": [
{
"code": "document_unavailable",
"detail": "The office no longer prints the fee schedule.",
"fallback_used": "Photographed the posted URL."
}
],
"submitted_at": "2026-09-21T11:30:00Z"
}This result does not disguise partial completion. It tells the agent which objective was met, which was not, what evidence exists, and what happened instead.
The practical rule
Define the result before sending the task.
Name the artifacts, fields, allowed states, acceptance test, and exception path. Then return the participant's work in that agreed shape without erasing uncertainty.
That is what makes human work usable inside an agent workflow: not a claim that the job is finished, but a result the next system can inspect.