Get typed answers

By default the agent’s answer is free-form text. Give it a schema and the answer you read from changes becomes a JSON object that conforms to it.

Where you set it	What you pass	What you get back
`answer_format` on the agent, or per run via `overrides`	A JSON Schema	A JSON object
`answer_schema` / `answerSchema` in the SDKs	A Pydantic model or Zod v4 schema	A validated, typed instance

With the SDK schema, the SDK derives the JSON Schema and parses the final answer for you. Rules:

A completed session whose answer is missing or doesn’t match raises AnswerValidationError with the raw payload attached.
The raw wire value always stays on final_changes / finalChanges, next to the parsed answer.
Passing both a schema and an agent.answer_format override is rejected: they set the same field.
Runs that end without reaching completed (an idle session that hasn’t answered, a failed one) skip validation; the answer passes through as-is, None / undefined when absent.

# `hai run` prints the structured answer once it lands
hai run "Top 3 stories on Hacker News right now?" \
  --agent h/web-surfer-flash \
  --override 'agent.answer_format={"type":"object","properties":{"stories":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}},"required":["title","url"]}}},"required":["stories"]}'

# Launch with a schema...
SESSION=$(curl -sX 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": [{"type": "user_message", "message": "Top 3 stories on Hacker News right now?"}],
    "overrides": {
      "agent.answer_format": {
        "type": "object",
        "properties": {
          "stories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {"title": {"type": "string"}, "url": {"type": "string"}},
              "required": ["title", "url"]
            }
          }
        },
        "required": ["stories"]
      }
    }
  }' | jq -r .id)

# ...then read the structured answer once it lands.
curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION/changes" \
  -H "Authorization: Bearer $HAI_API_KEY" | jq .answer

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="Top 3 stories on Hacker News right now?",
    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: "Top 3 stories on Hacker News right now?",
  answerSchema: Stories,
});

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

See it in action

Describe the data you want and the shape you want it in; the agent browses and hands back exactly that.

Chaining agents

With a typed answer, an agent behaves like any other function: call it, get data back, build on it. Here one agent gathers sources and others read them in parallel:

import asyncio
from pydantic import BaseModel
from hai_agents import AsyncClient

class Source(BaseModel):
    title: str
    url: str
    excerpt: str

class Sources(BaseModel):
    sources: list[Source]

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

async def main() -> None:
    client = AsyncClient()

    scout = await client.run_session(
        agent="h/web-surfer-flash",
        messages="Find the 5 highest-value sources on EU AI Act enforcement",
        answer_schema=Sources,
    )

    readers = await asyncio.gather(*(
        client.run_session(
            agent="h/web-surfer-flash",
            messages=f"Read this source and extract the key facts: {source.url}",
            overrides={"agent.environments[kind=web].start_url": source.url},
            answer_schema=Brief,
        )
        for source in scout.answer.sources
    ))

    for reader in readers:
        print(reader.answer.url, reader.answer.key_facts)

asyncio.run(main())

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

const Sources = z.object({
  sources: z.array(z.object({ title: z.string(), url: z.string(), excerpt: z.string() })),
});

const Brief = z.object({
  url: z.string(),
  summary: z.string(),
  keyFacts: z.array(z.string()),
});

const client = new HaiAgentsClient();

const scout = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Find the 5 highest-value sources on EU AI Act enforcement",
  answerSchema: Sources,
});

const readers = await Promise.all(
  (scout.answer?.sources ?? []).map((source) =>
    client.runSession({
      agent: "h/web-surfer-flash",
      messages: `Read this source and extract the key facts: ${source.url}`,
      overrides: { "agent.environments[kind=web].start_url": source.url },
      answerSchema: Brief,
    }),
  ),
);

for (const reader of readers) {
  console.log(reader.answer?.url, reader.answer?.keyFacts);
}

Parallel sessions count against your concurrency quota.

Next steps

Configure an agent

Set answer_format on the agent itself.

Parallelize work with subagents

Fan work out, then merge typed answers.

Get started

Concepts

Browser

Desktop

Integrations

Guides

Operate

See it in action

Chaining agents

Next steps

Configure an agent

Parallelize work with subagents

​See it in action

​Chaining agents

​Next steps

Configure an agent

Parallelize work with subagents

See it in action

Chaining agents

Next steps