Get typed answers - H Platform Docs

By default the agent answers in free-form text. Give it a schema and the answer becomes JSON that conforms to it.

With the SDKs

Pass a Pydantic model as answer_schema or a Zod v4 schema as answerSchema. The SDK derives the JSON Schema, sends it, and parses the final answer into a typed instance.

from pydantic import BaseModel
from hai_agents import Client

class Story(BaseModel):
    title: str
    url: str

class Stories(BaseModel):
    stories: list[Story]

client = Client()
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Open Hacker News and list the top 3 stories with their URLs.",
    answer_schema=Stories,
)

for story in result.answer.stories:  # result.answer is a Stories instance
    print(story.title, story.url)

import { HaiAgentsClient } from "hai-agents";
import { z } from "zod";

const Stories = z.object({
  stories: z.array(z.object({ title: z.string(), url: z.string() })),
});

const client = new HaiAgentsClient();
const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Open Hacker News and list the top 3 stories with their URLs.",
  answerSchema: Stories,
});

for (const story of result.answer?.stories ?? []) {
  console.log(story.title, story.url); // typed via z.infer
}

Case	Behavior
`completed`, answer missing or not matching	Raises `AnswerValidationError` with the raw payload attached.
Not `completed` (failed, or `idle` without an answer)	No validation. The answer passes through as-is, `None` / `undefined` when absent.
Raw wire value	Always on `final_changes` / `finalChanges`, next to the parsed answer.
Schema plus an `agent.answer_format` override	Rejected: both set the same field.

With a JSON Schema

Without an SDK, set a JSON Schema as answer_format on the agent, or per run with the agent.answer_format override. The settled answer (latest_answer on the session, answer on changes) is a JSON object matching it.

hai run "Open Hacker News and list the top 3 story titles." --agent h/web-surfer-flash \
  --override 'agent.answer_format={"type":"object","properties":{"titles":{"type":"array","items":{"type":"string"}}},"required":["titles"]}'

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent": "h/web-surfer-flash",
    "messages": "Open Hacker News and list the top 3 story titles.",
    "overrides": {
      "agent.answer_format": {
        "type": "object",
        "properties": {"titles": {"type": "array", "items": {"type": "string"}}},
        "required": ["titles"]
      }
    }
  }'

If every attempt fails to match the schema, the session fails with error_code: answer_validation.

Chaining agents

A typed answer makes an agent callable like a function: one agent’s output feeds the next. Here a scout finds sources, then readers run in parallel (each counts against your concurrency limit):

import asyncio
from pydantic import BaseModel
from hai_agents import AsyncClient

class Sources(BaseModel):
    urls: list[str]

class Brief(BaseModel):
    key_facts: list[str]

async def main() -> None:
    client = AsyncClient()
    scout = await client.run_session(
        agent="h/web-surfer-flash",
        messages="Find the 5 best sources on EU AI Act enforcement",
        answer_schema=Sources,
    )
    briefs = await asyncio.gather(*(
        client.run_session(agent="h/web-surfer-flash", messages=f"Extract the key facts from {url}", answer_schema=Brief)
        for url in scout.answer.urls
    ))

asyncio.run(main())

const Sources = z.object({ urls: z.array(z.string()) });
const Brief = z.object({ keyFacts: z.array(z.string()) });

const scout = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Find the 5 best sources on EU AI Act enforcement",
  answerSchema: Sources,
});
const briefs = await Promise.all(
  (scout.answer?.urls ?? []).map((url) =>
    client.runSession({ agent: "h/web-surfer-flash", messages: `Extract the key facts from ${url}`, answerSchema: Brief }),
  ),
);

Related: Configure an agent, Parallelize work with subagents