Instructions

defineInstruction(options)

defineInstruction(options: InstructionOptions): AgentInstruction

import { defineInstruction } from 'agentfootprint/instructions';

const instruction = defineInstruction({
  id: 'refund-handling',
  activeWhen: (decision) => decision.orderStatus === 'cancelled',
  prompt: 'Handle with empathy. Offer refund.',
  tools: [processRefundTool],
  safety: false,
  onToolResult: [{
    id: 'empathy',
    text: 'Do NOT promise reversal.',
    decide: (decision, ctx) => {
      decision.refundRequested = true;
    },
  }],
});

InstructionOptions

Field	Type	Description
id	string	Unique instruction identifier
activeWhen	(decision) => boolean	Predicate — when to activate
prompt	string	Injected into system prompt
tools	ToolDefinition[]	Added to available tools
safety	boolean	Fail-closed, unsuppressable
onToolResult	ToolResultInstruction[]	Injected after tool results

ToolResultInstruction

Field	Type	Description
id	string	Matches tool ID
text	string	Injected text
decide	(decision, ctx) => void	Mutate Decision Scope

AgentPattern

import { AgentPattern } from 'agentfootprint/instructions';

AgentPattern.Regular  // default — slots evaluated once
AgentPattern.Dynamic  // re-evaluate all slots each iteration

Builder methods

agent
  .instruction(inst)              // add one instruction
  .instructions([inst1, inst2])   // add multiple
  .decision({ key: null })        // initial Decision Scope
  .pattern(AgentPattern.Dynamic)  // enable re-evaluation