Agent Block

The Agent block connects your workflow to Large Language Models (LLMs). Use it to extract data from documents, classify inputs, generate text, or make decisions based on unstructured data. The block supports structured output via JSON Schema, ensuring consistent, machine-readable responses.

Configuration

Provider

Select the AI provider for the agent. Available providers:

System Prompt

The system prompt defines the agent's role, behavior, and constraints. It is sent with every request and shapes how the agent processes input.

You are an expert invoice data extractor. Given a document, extract:
- Invoice number
- Vendor name
- Total amount
- Due date
- Line items with descriptions and amounts

Always return valid JSON matching the output schema.

User Prompt

The primary input for the agent. This is the text or data the agent will process. Sources include:

• Static text configured directly in the block
• Dynamic data from upstream blocks via template variables (e.g., {{steps.download.content}})
• Trigger payload data from the workflow input

Input Data

Optional JSON object passed as additional context to the agent. Use this to pass structured data from upstream blocks:

{
  "documentContent": "{{steps.download.content}}",
  "documentMimetype": "application/pdf",
  "customerName": "{{steps.lookup.output.name}}"
}

Output Schema

Define a JSON Schema to enforce structured output. When set, the agent's response is constrained to match the schema exactly, preventing free-form text and ensuring downstream blocks receive consistent data.

{
  "type": "object",
  "properties": {
    "invoiceNumber": { "type": "string" },
    "vendorName": { "type": "string" },
    "totalAmount": { "type": "number" },
    "dueDate": { "type": "string" },
    "lineItems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": { "type": "string" },
          "amount": { "type": "number" }
        }
      }
    }
  },
  "required": ["invoiceNumber", "vendorName", "totalAmount"]
}

Temperature

Controls response randomness:

Default: 0 (deterministic). For billing workflows, keep temperature at 0 to ensure consistent, repeatable results.

Max Tokens

Maximum length of the agent's response. Defaults to the model's maximum. Override with a specific value to control costs or response length.

Outputs

Example Use Cases

Invoice Data Extraction

Stagehand (download PDF) -> Agent (extract invoice fields) -> QuickBooks (create invoice)

System prompt: "Extract invoice number, vendor, total, due date, and line items from the document." Output schema: Structured JSON matching QuickBooks invoice format.

Payment Classification

Stripe (payment received) -> Agent (classify payment type) -> Condition (recurring vs one-time)

System prompt: "Classify this payment as recurring, one-time, or refund based on the metadata." Output schema: { "type": "recurring" | "one-time" | "refund", "confidence": number }

Contract Term Extraction

DocuSign (signed contract) -> Agent (extract billing terms) -> Transform -> Stripe (create subscription)

System prompt: "Extract billing frequency, amount, start date, and payment terms from this contract."

Email Triage

Gmail (new email) -> Agent (classify and extract) -> Condition (route by type)
    -> Invoice inquiry: Slack (notify finance)
    -> Payment issue: Stripe (lookup) -> Slack (notify support)

Best Practices

• Use temperature 0 for extraction tasks. Billing data must be accurate and consistent. Creative variation is undesirable for financial data.

• Always define an output schema for structured data. This prevents the agent from returning unexpected formats and ensures downstream blocks receive the data they expect.

• Be specific in system prompts. Instead of "extract data from this document," write "extract the invoice number (alphanumeric, usually in format INV-XXXX), vendor name, total amount in USD, and due date in ISO 8601 format."

• Use the right model for the task. Claude Sonnet 4.6 is the best balance of quality and speed for most extraction tasks. Use GPT-4o Mini or Claude Haiku for simple classification. Reserve Claude Opus 4.6 for complex multi-step reasoning.

• Handle PDF documents with care. When passing PDF content, include the MIME type in the input data so the agent can handle it correctly. The execution engine auto-detects PDFs and switches to a vision-capable model when needed.