|
1 | | -# `AgentTask`: keep judgment with the model |
2 | | - |
3 | | -Use `AgentTask` for work that needs interpretation: reviewing a diff, |
4 | | -diagnosing a failure, comparing designs, extracting a policy, or proposing a |
5 | | -fix. |
6 | | - |
7 | | -```ts |
8 | | -type Diagnosis = { cause: string; confidence: number } |
9 | | - |
10 | | -const diagnosis = ctx.agentTask<Diagnosis>( |
11 | | - "diagnose", |
12 | | - "Find the most likely cause of this test failure.", |
13 | | - { stdout: test.stdout, stderr: test.stderr }, |
14 | | - { |
15 | | - type: "object", |
16 | | - required: ["cause", "confidence"], |
17 | | - properties: { |
18 | | - cause: { type: "string" }, |
19 | | - confidence: { type: "number" }, |
| 1 | +# AgentTask |
| 2 | + |
| 3 | +Use the coding agent as a typed judgment step inside your workflow. |
| 4 | + |
| 5 | +The agent interprets. With a JSON Schema, Yield checks the returned shape. Your |
| 6 | +program still owns what happens next. |
| 7 | + |
| 8 | +```text |
| 9 | +workflow code |
| 10 | + ↓ |
| 11 | +AgentTask |
| 12 | + ↓ |
| 13 | +coding-agent judgment |
| 14 | + ↓ |
| 15 | +JSON result, schema-validated when requested |
| 16 | + ↓ |
| 17 | +workflow code continues |
| 18 | +``` |
| 19 | + |
| 20 | +Use `AgentTask` when one step needs interpretation: review what a check may |
| 21 | +have missed, diagnose captured output, compare designs against criteria, or |
| 22 | +extract structured information from repository material. |
| 23 | + |
| 24 | +## One workflow, three roles |
| 25 | + |
| 26 | +| Role | Primitive | Responsibility | |
| 27 | +| ------------------ | -------------------------- | ------------------------------------------------------ | |
| 28 | +| deterministic work | `RunCommand` and `Require` | run commands and enforce requirements | |
| 29 | +| agent judgment | `AgentTask` | interpret a bounded request and return structured data | |
| 30 | +| human authority | `AskUser` | make a decision before a protected effect | |
| 31 | + |
| 32 | +Not every workflow needs all three. Yield lets them work together without |
| 33 | +asking the coding agent to rediscover order, retry limits, or completion rules |
| 34 | +on every run. |
| 35 | + |
| 36 | +## Example: check, review, approve, publish |
| 37 | + |
| 38 | +This tested workflow runs a deterministic check, asks the coding agent to |
| 39 | +review what that check may miss, requires a safe review result, then asks a |
| 40 | +person before publishing. |
| 41 | + |
| 42 | +<!-- release-example:start --> |
| 43 | + |
| 44 | +```typescript |
| 45 | +import { defineSkill } from "@operatorstack/yield" |
| 46 | + |
| 47 | +type Review = { critical: number; summary: string } |
| 48 | + |
| 49 | +defineSkill((ctx) => { |
| 50 | + // Yield runs commands itself and records their output and exit status. |
| 51 | + const tests = ctx.runCommand("test", "echo tests-ok", 300) |
| 52 | + |
| 53 | + // A failed requirement stops the workflow and keeps its evidence. |
| 54 | + ctx.require(tests.exit_code === 0, "the test command succeeds", tests) |
| 55 | + |
| 56 | + // Review gives TypeScript its compile-time type. The JSON schema checks the |
| 57 | + // coding agent's response at runtime before this workflow can continue. |
| 58 | + const review = ctx.agentTask<Review>( |
| 59 | + "review-release", |
| 60 | + "Review this release for correctness problems that the test command may miss. Report critical findings and a short summary.", |
| 61 | + { stdout: tests.stdout, stderr: tests.stderr }, |
| 62 | + { |
| 63 | + type: "object", |
| 64 | + required: ["critical", "summary"], |
| 65 | + properties: { |
| 66 | + critical: { type: "integer", minimum: 0 }, |
| 67 | + summary: { type: "string", minLength: 1 }, |
| 68 | + }, |
20 | 69 | }, |
21 | | - }, |
22 | | -) |
| 70 | + ) |
| 71 | + ctx.require(review.critical === 0, "the review has no critical findings", review) |
| 72 | + |
| 73 | + // Yield emits these fixed choices. A supported host may show native controls; |
| 74 | + // otherwise the coding agent asks through its normal interface. |
| 75 | + const approval = ctx.askUser("approve-publish", "Publish this package?", [ |
| 76 | + { value: "yes", label: "Publish" }, |
| 77 | + { value: "no", label: "Stop" }, |
| 78 | + ]) |
| 79 | + if (approval !== "yes") ctx.refused("the operator declined publication") |
| 80 | + |
| 81 | + // Publishing cannot start before approval. Verification is a separate step, |
| 82 | + // so completion requires evidence that the registry contains the release. |
| 83 | + const publish = ctx.runCommand("publish", "echo publish-ok", 600) |
| 84 | + ctx.require(publish.exit_code === 0, "the publish command succeeds", publish) |
| 85 | + |
| 86 | + const registry = ctx.runCommand("verify-registry", "echo registry-ok", 300) |
| 87 | + ctx.require(registry.exit_code === 0, "the registry contains the release", registry) |
| 88 | + |
| 89 | + return { published: true, summary: review.summary } |
| 90 | +}) |
23 | 91 | ``` |
24 | 92 |
|
25 | | -The arguments are: |
| 93 | +<!-- release-example:end --> |
| 94 | + |
| 95 | +## Give the task the evidence it needs |
| 96 | + |
| 97 | +The third argument is explicit workflow context. Pass the result that the |
| 98 | +judgment depends on, such as command output, a diff summary, or a previous |
| 99 | +structured result. Explicit context is easier to understand, test, and replay. |
| 100 | + |
| 101 | +Yield sends the instruction and explicit context in the request. It does not |
| 102 | +promise access to a complete conversation, the repository, or any hidden host |
| 103 | +context. A coding agent may have additional working capabilities in its host, |
| 104 | +but those capabilities are host-dependent. |
| 105 | + |
| 106 | +Cursor, Codex, and Claude Code are verified integrations. The host still owns |
| 107 | +the UI and working capabilities available to the agent. |
| 108 | + |
| 109 | +## What schema validation proves |
| 110 | + |
| 111 | +When you provide a JSON Schema, Yield validates the returned JSON before the |
| 112 | +workflow continues. It proves that required fields and declared structural |
| 113 | +constraints are present. It does not prove that the analysis is correct, files |
| 114 | +were inspected, or the requested work happened. |
| 115 | + |
| 116 | +Use `RunCommand` for machine-observed output, `Require` to control |
| 117 | +continuation, and `AskUser` for human authority. Another `AgentTask` can offer |
| 118 | +another judgment, but it is still model judgment. |
| 119 | + |
| 120 | +## Test the surrounding workflow |
26 | 121 |
|
27 | | -1. a stable operation ID; |
28 | | -2. the instruction; |
29 | | -3. optional structured context; |
30 | | -4. an optional JSON Schema for the response. |
| 122 | +In production, `AgentTask` waits for the coding agent. In a test, |
| 123 | +`yskill test` reads a deterministic fixture response instead. The same |
| 124 | +surrounding workflow logic still runs, including commands and requirements. |
31 | 125 |
|
32 | | -The Yield CLI validates the response schema before accepting it. Schema-valid |
33 | | -does not mean true; use `RunCommand`, human approval, or another explicit check |
34 | | -when the workflow needs stronger evidence. |
| 126 | +See [testing fixtures](../testing-fixtures.md) for |
| 127 | +`fixtures/responses.json` and test-only effects. |
35 | 128 |
|
36 | 129 | ## Common mistake |
37 | 130 |
|
|
0 commit comments