agent-survey

• 中文文档
• A TypeScript-first survey engine.
• Survey definitions can be TypeScript, JavaScript, or JSON.
• The core package has no model, provider, CLI, console, or filesystem assumptions.

Install

pnpm add agent-survey

Node.js 22.19 or later can also run the repository's TypeScript source directly.

Core API

Survey describes only the questionnaire. The caller supplies an Answerer and runtime policy to runSurvey:

import { runSurvey, type Survey } from 'agent-survey';

const survey: Survey = {
  name: 'Example',
  instructions: 'Answer concisely.',
  initialStep: 'question',
  steps: [{
    id: 'question',
    prompt: 'What should we improve?',
    validateFn: answer => answer.length >= 2,
    saveAs: 'suggestion',
  }],
};

const result = await runSurvey(survey, {
  answerer: {
    name: 'my-answerer',
    answer: async request => getAnswer(request.prompt),
  },
  maxSteps: 50,
  maxRetries: 3,
  rememberHistory: true,
});

rememberHistory defaults to true. Set it to false to expose only the current prompt and an empty context view to the Answerer. The runner still keeps its private context for validation, routing, and final results.

Model selection, provider credentials, timeouts, maximum steps, retry counts, logging, and process behavior are not Survey fields.

Optional Adapters

The pi-ai adapter is an explicit subpath import:

import { createPiAnswerer } from 'agent-survey/pi';

const answerer = createPiAnswerer({
  provider: 'anthropic',
  model: 'deepseek-v4-flash',
  baseUrl: 'https://example.test',
  thinking: true,
});

Node transcript helpers are separate from the core:

import { createTranscriptWriter } from 'agent-survey/node';

const transcript = createTranscriptWriter('./survey.ts');
await runSurvey(survey, {
  answerer,
  onAnswerStream(event) {
    if (event.type === 'thinkingDelta') process.stdout.write(event.delta);
    if (event.type === 'textDelta') process.stdout.write(event.delta);
  },
  onEvent: event => transcript.write(event),
});

Survey Sources

loadSurvey(path) returns one complete Survey. Directory discovery order:

1. survey.ts
2. survey.js
3. survey.mjs
4. survey.mts
5. flow.json

TypeScript and JavaScript can put real functions directly in jumpFn and validateFn. JSON uses jumpFnName and validateFnName; an optional sibling functions.ts or functions.js supplies Survey.functionDict.

Steps can require typed JSON5 answers with answerFormat, and can declare options with configurable labels and optional shuffling. Display labels are mapped back to stable option values in context.optionMappings.

See Survey format for the complete contract.

CLI

The CLI is a convenience wrapper that combines the core, the pi-ai adapter, environment configuration, terminal output, and transcript files:

pnpm start flows/survey
pnpm start flows/adaptive-planner --model deepseek-v4-flash
pnpm start flows/configurable-survey --var topic=dog
pnpm start flows/configurable-survey --config flows/configurable-survey/inputs.shopping.json
pnpm start flows/poem-memory --no-history
pnpm start flows/proposition-judgment --var 'proposition=所有质数都是奇数。'
pnpm start flows/proposition-judgment --var 'proposition=所有质数都是奇数。' --no-thinking
pnpm start flows/fantasy-character --var 'characterDescription=an elven spellblade who guards an ancient forest'

flows/fantasy-character first creates a character using the schema included in the prompt, then checks flows/fantasy-character/catalog.jsonl. It asks for race or class data only when the referenced entity is missing. The consistent result is stored in context.variables.bundle, and new catalog entities are appended only after every required answer passes validation.

The CLI streams thinking and answer text to the terminal. Thinking is enabled by default; use --no-thinking to disable it and --thinking to enable it explicitly. These switches configure the pi-ai Answerer and are not Survey fields.

The CLI reads ANTHROPIC_API_KEY and the selected provider's baseUrl from ~/.pi/agent/models.json. These settings belong to the CLI/Answerer, not the Survey.

Markdown transcripts include model thinking when the Answerer returns it in the opaque SurveyAnswer.raw response. Streaming deltas are not duplicated in the transcript; it records the final response once.

Repository Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm check

The package publishes ESM JavaScript and declarations from dist/, with root, ./pi, and ./node exports plus the agent-survey CLI binary.