Input, state, and output

How data flows into and out of an agent. The same model applies to every kind — primitives consume their input, pipelines merge per-step outputs into a shared state object, and the agent's final result is shaped by outputSchema (LLM) or output (pipelines).

Input

inputSchema declares the agent's input contract. Properties are listed directly; all are required but nullable.

inputSchema:
  query: string
  language:
    type: string
    default: en
  format:
    type: string
    enum: [json, text, markdown]

Shorthand: name: string is equivalent to name: { type: string }. Supported types are string, number, boolean, object, and array. Use enum to restrict string values; use default to fall back when the caller omits the field.

If inputSchema is omitted, the agent accepts a plain string, accessible in templates as {{userQuery}}.

Model config (LLM kind only)

model:
  provider: openai            # openai | anthropic | google | mistral
  name: gpt-5.4
  temperature: 0.7            # optional
  maxTokens: 4096             # optional
  topP: 1.0                   # optional

Instruction and prompt (LLM kind only)

instruction: |               # required — the system prompt
  You are a math tutor. Explain each step clearly.

prompt: |                    # optional — user-message template
  Solve carefully: {{userQuery}}

• instruction is the system prompt. Templated with {{}} against state.
• prompt is the user message. When absent, the agent's raw input ({{userQuery}} or the input object stringified) is sent verbatim.

Splitting them lets the system prompt remain stable (and cache-friendly with providers that cache by prefix), while the user-message template changes per call.

State

State is the working memory that pipeline steps share. It's a flat object scoped per agent — sub-agents have their own state and cannot see the parent's.

{
  ...input,                                              # input properties at root
  [stateKey ?? normalizeId(subAgent)]: subAgentOutput    # per sub-agent
}

Rules:

• {{varName}} references root input properties.
• {{agentId.property}} references a sub-agent's output property.
• {{stateKey}} references the entire output of a sub-agent (when outputSchema makes it a structured object) or its raw output.
• Unresolved references (skipped steps, first loop iteration) resolve to null — they don't throw.

stateKey lets you rename where a step's output lands. By default it lands under the sub-agent's id; stateKey: writing renames it for ergonomic downstream references.

Output

LLM agents — outputSchema

Constrains the model's response to a JSON object. The runner enforces the schema and returns parsed JSON, not a string.

outputSchema:
  sentiment:
    type: string
    enum: [positive, negative, neutral]
  confidence: number

const { output } = await client.agents.run({
  agentId: "sentiment-analyzer",
  input: { text: "I love this!" },
});
// output = { sentiment: "positive", confidence: 0.95 }

Without outputSchema, the agent returns the model's raw text.

Pipeline agents — output

Pipeline agents use output to map state to the result. Optional — defaults to the last step's output (sequential) or all branch outputs keyed by id (parallel).

output:
  article: "{{writing.writer.draft}}"
  review: "{{writing.editor}}"

Anything in state is fair game — output is just a template substitution map.

Examples (LLM kind)

Few-shot examples improve consistency. They're injected into the prompt before the user message.

examples:
  - input: "I absolutely love this product!"
    output: '{"sentiment": "positive", "confidence": 0.95}'
  - input: "The package arrived on Tuesday."
    output: '{"sentiment": "neutral", "confidence": 0.88}'

When the agent has an outputSchema, examples should produce JSON that matches it.