AI Agent block

Configure the AI Agent block: the model, the prompt, structured output and the tools the agent may call, with the output it returns.

The AI Agent block (type: "agent") sends a prompt, and optionally a document, to a model and stores the answer. With an output schema it returns structured fields; with tools it can call Loopfour actions while it works. For the plain-language guide, see Read, extract and classify with AI.

When to use it

Extract fields from an invoice, bill, contract or remittance PDF into a fixed structure.
Classify or summarise text, such as coding a bill to a GL account from its description.
Look things up during a step, for example search a contact in Zoho Inventory before drafting a reply.

For a fixed calculation, use the Code block; the agent's answer can vary between runs.

Configuration

Field (`config` key)	Editor label	Type	Required	Meaning
`provider`	Provider	`anthropic` or `openai`	No	Default `anthropic` in the editor. When omitted, the provider follows the model.
`model`	Model	`claude-opus-5` or `gpt-5.6-sol`	No	Default `claude-opus-5`; `gpt-5.6-sol` when the provider is `openai`. The model must belong to the provider.
`prompt`	Prompt	string	Yes, or `systemPrompt`	The instruction for this step. Template references are resolved first.
`systemPrompt`	System Prompt	string	No	Standing instructions, such as the role and rules the agent follows.
`input`	Input Data (JSON)	object or string	No	Variables for the agent. A string becomes `content`. Attach a document with `documentUrl` or `documentContent` (see below).
`outputSchema`	Output Schema (JSON Schema)	object or JSON string	No	JSON Schema for the answer. When set, the answer is returned in `structured` and checked against the schema.
`temperature`	Temperature	number	No	0 to 2 at run time; the editor slider covers 0 to 1 and defaults to 0.
`maxTokens`	Max Tokens	number	No	1 to 128000.
`tools`	Tools (JSON array)	array	No	Tool definitions the agent may call, at most 20. Each is `{ "name", "description", "parameters", "action" }`, where `parameters` is a JSON Schema and `action` is a Loopfour action id such as `zoho-inventory.searchContacts` or `data_table.find`.
`maxToolIterations`	Max tool iterations	number	No	1 to 30, default 8. Caps the tool-calling rounds in one step.
`connections`	Tool accounts	object	No	Maps a provider to a connection id, so a tool runs against that account. Providers you do not list use the company default.
`timeoutMs`	Not shown	number	No	1000 to 300000, default 60000.

Attach a document

Put these keys inside input:

Key	Meaning
`documentUrl`	A URL the model provider fetches. Preferred for large files, because the bytes stay out of the run. A Workspace Files `getFile` step with `mode: "url"` returns one.
`documentContent`	Base64 file content. It is held in the run for its whole length, so keep it small.
`documentMimetype`	The file type, such as `application/pdf`.
`documentName`	The file name.

When you attach a PDF to a step set to openai, the step may switch to the Anthropic provider to read it.

Output

Field	Type	Meaning
`structured`	object	The answer as fields, when `outputSchema` is set. Read it as `{{steps.<step id>.structured.<field>}}`.
`content`	string	The answer as text.
`usage`	object	Token counts: `promptTokens`, `completionTokens`, `totalTokens`.
`cost`	object	Cost estimate for the call.
`latencyMs`	number	Time the model call took.
`model`	string	The model that answered.
`provider`	string	The provider that answered.
`agentId`	string	An id for this inline agent.

The editor's output list shows result and text; the executor returns structured and content instead.

Example

This workflow reads a vendor bill PDF saved in Files and extracts the fields an AP clerk would key in.

{
  "name": "Extract vendor bill fields",
  "trigger": { "type": "api" },
  "inputSchema": {
    "type": "object",
    "properties": { "fileId": { "type": "string" } },
    "required": ["fileId"]
  },
  "steps": [
    {
      "id": "get_bill",
      "type": "workspace_files",
      "name": "Get bill link",
      "config": { "operation": "getFile", "fileId": "{{input.fileId}}", "mode": "url" }
    },
    {
      "id": "extract_bill",
      "type": "agent",
      "name": "Extract bill fields",
      "config": {
        "provider": "anthropic",
        "model": "claude-opus-5",
        "systemPrompt": "You are an accounts payable clerk. Copy values exactly as printed.",
        "prompt": "Extract the vendor name, bill number, bill date, due date and total from this bill.",
        "input": {
          "documentUrl": "{{steps.get_bill.url}}",
          "documentMimetype": "application/pdf"
        },
        "outputSchema": {
          "type": "object",
          "properties": {
            "vendorName": { "type": "string" },
            "billNumber": { "type": "string" },
            "billDate": { "type": "string" },
            "dueDate": { "type": "string" },
            "total": { "type": "number" }
          },
          "required": ["vendorName", "billNumber", "total"]
        },
        "temperature": 0
      }
    }
  ]
}

A later step reads the total as {{steps.extract_bill.structured.total}}.

Errors and limits

The step needs prompt or systemPrompt. A model that does not belong to the provider is refused when the workflow is saved and when it runs.
With outputSchema set, an answer that does not match the schema fails the step with returned structured output that does not match its output schema.
A tool loop that goes past maxToolIterations fails the step.
The model call is retried up to two times before the step fails.
The answer can differ between runs. For decisions that move money, follow the agent with a Condition or an Approval step.