Skip to Content
onedef

Ask the agent

ctx.elicitAgentInput hands a piece of work to the connected model, and checks its answer against your schema.

Sometimes the question isn't for the user. It's work for the model the user is talking to: write this section, translate these lines, pick the right files. ctx.elicitAgentInput hands that work to the agent driving the run. Your server needs no model of its own, and no API key.

import { createWorkflow } from '@onedef/elicitation-workflow'
import { z } from 'zod'

export const writeGuide = createWorkflow({
  id: 'write-guide',
  description: 'Write a short guide on a topic, section by section.',
  input: z.object({ topic: z.string() }),
})
  .handler(async (ctx) => {
    const plan = await ctx.elicitAgentInput('plan', {
      schema: z.object({ sections: z.array(z.string()).min(2).max(4) }),
      instructions: 'Propose 2 to 4 section titles for the topic.',
      data: { topic: ctx.input.topic },      // shared context: send it once, in the first question
    })

    const sections = []
    for (const title of plan.sections) {
      const { body } = await ctx.elicitAgentInput(`section-${title}`, {
        schema: z.object({ body: z.string().min(40) }),
        instructions: 'Write this section in 2 to 4 sentences.',
        data: { title },
      })
      sections.push({ title, body })
    }

    return ctx.step('publish', () => publish(ctx.input.topic, sections))
  })

How the agent drives it

registerWorkflowTool(server, 'write_guide', { runStore }, writeGuide) registers write_guide and write_guide_next. The agent:

  1. calls write_guide({ topic }) and gets { runId, status: 'waiting', waitingFor: { kind: 'agent', name, instructions, data, schema } };
  2. does what waitingFor asks and calls write_guide_next({ runId, payload });
  3. repeats until status is done, with the result in output.

The tool descriptions explain this, so an agent drives a run without any extra prompt.

Answers are checked inside the run

schema is any Standard Schema with JSON Schema support (zod 4.2+, valibot, arktype). The agent sees it as JSON Schema in waitingFor.schema. An answer that doesn't match is rejected with the reason:

INVALID_INPUT: Answer to "plan" rejected, the run did not move: sections: Too small: expected array to have >=2 items.

The run stays at the same question, so the agent fixes its answer and sends it again.

Context, once

Each call to _next returns only the next question. Put the shared context (the source document, the rules, the full lyrics) in the first question's data. Later questions can assume the agent has it, which keeps every round small.

Both kinds in one run

A workflow can ask the agent and the user in the same run. The agent writes the guide, and the user confirms before it's published:

const answer = await ctx.elicitHumanInput({
  message: `Publish "${ctx.input.topic}"?`,
  requestedSchema: { type: 'object', properties: { publish: { type: 'boolean' } }, required: ['publish'] },
})

On this page