> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules).
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.
# Structured outputs
> The Holo3 and Holo3.1 agent loop with one constrained JSON object per step, and the mistakes specific to this format.
export const ChatStrip = ({rows, repeatFrom = 1}) => {
const Body = ({text}) => text.split(/(`[^`]+`)/).map((part, i) => part.startsWith("`") ? {part.slice(1, -1)} : {part});
const Row = ({role, body}) =>
;
};
This is the agent-loop format for `holo3-122b-a10b` (its only option) and `holo3-1-35b-a3b`. Holo4 agents use [function calling](/models-api/build-an-agent/function-calling). Single-shot JSON, like [element localization](/models-api/element-localization), works on every model.
Each step, the decoder is constrained to emit one JSON object matching your schema, with the tool call as a field inside it, so output is always valid JSON. Read [Core concepts](/models-api/build-an-agent/core-concepts) first.
## Output JSON
```json theme={"system"}
{
"note": "Submit succeeded; receipt URL is /orders/8421.",
"thought": "Recording the receipt URL before navigating away.",
"tool_call": {"tool_name": "click", "element": "Continue button at the bottom right", "x": 932, "y": 880}
}
```
The model's durable memory: facts from the current screen that later steps need (URLs, IDs, partial answers). `null` when nothing is new.
A one-line plan for the next action.
One variant of your tool union. Flat: `tool_name` sits next to the arguments, not in a nested `args` object.
## Constrain output to a tool union
Define each tool as a Pydantic model with a `Literal` `tool_name`, and use their union as the schema. The decoder emits exactly one variant, and you dispatch on `tool_name`.
```python Python theme={"system"}
from typing import Literal
from pydantic import BaseModel, Field
class ClickArgs(BaseModel):
"""Click at (x, y) coordinates"""
tool_name: Literal["click"]
element: str = Field(description="Detailed description of the target UI element to click on")
x: int = Field(description="X coordinate as integer in [0, 1000]")
y: int = Field(description="Y coordinate as integer in [0, 1000]")
class WriteArgs(BaseModel):
"""Type text into the currently focused element without clicking first"""
tool_name: Literal["write"]
content: str = Field(description="Content to write")
press_enter: bool = Field(default=False, description="Whether to press Enter after typing")
class AnswerArgs(BaseModel):
"""Provide a final answer"""
tool_name: Literal["answer"]
content: str = Field(description="The answer content")
class Step(BaseModel):
note: str | None = Field(default=None, description="Task-relevant information from the previous observation. Empty if nothing new.")
thought: str = Field(description="Reasoning about next steps")
tool_call: ClickArgs | WriteArgs | AnswerArgs
```
In TypeScript, write the same JSON Schema by hand: a `oneOf` of tool objects, each with `tool_name: { const: "..." }`.
Pass it in `extra_body={"structured_outputs": {"json": schema}}` and also append it to the system prompt in an `` block. The model was trained with both, so dropping either hurts reliability. Do not use `tools` or `tool_choice`: the action arrives in `content`, not in `tool_calls`.
## Chat layout
Tool results go back as `user` messages wrapped in ``, not as `tool` messages:
` schema block" },
{ role: "user", body: "`` screenshot and/or text ``" },
{ role: "assistant", body: "`{ note, thought, tool_call }`" },
{ role: "user", body: "`` result ``" },
]}
/>
## A complete loop
Plug in your own `observation()` (the `` message from [Core concepts](/models-api/build-an-agent/core-concepts#observations)) and `execute(tool_call)`.
````python Python theme={"system"}
import json
schema = Step.model_json_schema()
system = SYSTEM_PROMPT + f"\n\n\n```json\n{json.dumps(schema)}\n```\n"
messages = [{"role": "system", "content": system}, {"role": "user", "content": task}]
for _ in range(MAX_STEPS):
messages.append(observation())
trim_to_last_n_images(messages, n=3)
resp = client.chat.completions.create(
model="holo3-1-35b-a3b",
messages=messages,
temperature=0.8,
extra_body={"structured_outputs": {"json": schema}},
)
step = Step.model_validate_json(resp.choices[0].message.content)
messages.append({"role": "assistant", "content": step.model_dump_json()})
if step.tool_call.tool_name == "answer":
return step.tool_call.content
result = execute(step.tool_call)
messages.append({"role": "user", "content": f'\n{result}\n'})
````
## Format-specific pitfalls
| Symptom | Likely cause |
| :- | :- |
| Model returns free-form text | `structured_outputs.json` missing, or the schema lacks a `Literal` `tool_name` |
| Tool result has no effect | Sent as a `tool` message instead of a `user` message with a `` wrapper |
| Model forgets earlier facts | `note` left empty: it is the only memory carried between turns |
| Reliability drops | Schema in `structured_outputs` but missing from the `` block, or the reverse |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.