Primitive 02 / Agent

AgentTask

Ask the coding agent for judgment. Accept a schema-checked result, then keep the gate and next action in normal code.

01 / When

Use it where a check ends and judgment begins.

Run commands for observed facts. Give the relevant output to the coding agent for interpretation. Then use the returned fields in ordinary code.

Useful for

Review a code changeFind risks a deterministic check cannot express.
Diagnose a failureExplain a likely cause from supplied logs.
Compare two designsReturn a choice and its trade-offs.
Extract policy rulesTurn a document into stable fields.
Triage a signalClassify the next useful action.
Propose a focused fixDescribe a safe, bounded change.

Keep the boundary clear.AgentTask owns judgment. The surrounding program owns commands, retries, approvals, and completion.

02 / Code

Ask for a result your code can inspect.

Use a type for the fields your program reads and a JSON Schema to check the returned shape before the run continues.

AgentTask · TypeScript

import { defineSkill } from "@operatorstack/yield"

type Review = { critical: number; summary: string }

defineSkill((ctx) => {
  const check = ctx.runCommand("typecheck", "npm run typecheck", 300)
  ctx.require(check.exit_code === 0, "typecheck passes", check)

  const review = ctx.agentTask<Review>(
    "review",
    "Review this change for correctness problems the check may miss.",
    { stdout: check.stdout, stderr: check.stderr },
    {
      type: "object",
      required: ["critical", "summary"],
      properties: {
        critical: { type: "integer", minimum: 0 },
        summary: { type: "string", minLength: 1 },
      },
    },
  )
  ctx.require(review.critical === 0, "no critical findings", review)
  return { summary: review.summary }
})

Other language versions

Python

from yieldskill import define_skill

def program(ctx):
    result = ctx.agent_task(
        "diagnose", "Find the likely cause.",
        None, {"type": "object", "required": ["cause"]},
    )
    return result

define_skill(program)

Go

package main

import "github.com/operatorstack/yield/sdk/yield"

func main() {
  yield.Main(func(ctx *yield.Context) (yield.Outcome, error) {
    result := ctx.AgentTask("diagnose", "Find the likely cause.", nil, schema)
    return ctx.Complete(result)
  })
}

Rust

use yieldskill::{define_skill, Context, SkillResult};

fn program(ctx: &mut Context) -> SkillResult {
  let result = ctx.agent_task(
    "diagnose", "Find the likely cause.", None, Some(schema()),
  );
  Ok(result)
}

fn main() { define_skill(program); }

03 / Run

See judgment become a typed result.

CursorYield run · agent task

› /review

Reviewing the supplied command output for risks the typecheck cannot decide.

AgentTask · review

Review response readyschema valid

No critical correctness problems found. The change is ready for its next workflow step.

Saved response

{
  "critical": 0,
  "summary": "No critical findings"
}

04 / Shape

Define what crosses the boundary.

Operation ID: A stable name that binds this judgment during replay.
Instruction: The decision the coding agent should make, not the control policy.
Context: Optional inputs or command output to supply deliberately.
Schema: An optional JSON Schema for the fields your code will use.

05 / Saved

Resume with an accepted result.

The coding agent returns a response. Yield checks the optional schema before accepting it, then records the accepted result for resume and replay.

Common mistake

Schema-valid means the response has the expected shape, not that it is true. Use RunCommand for observed facts, ask a person for approval, or add another explicit check when the workflow needs stronger evidence.