Run agents from n8n

The Agents API works in n8n as a standard HTTP integration. There’s no custom node to install: you authenticate with a header, create a session, and either poll for the result or receive a webhook when it finishes.

Create a credential

In n8n, go to Credentials → Add Credential → Header Auth and set:

Field	Value
Name	`Authorization`
Value	`Bearer hk-...`

Create the key at platform.hcompany.ai/settings/api-keys. It’s shown once, so copy it when you create it. A key is scoped to one organization.

Start a session

Add an HTTP Request node:

Setting	Value
Method	`POST`
URL	`https://agp.eu.hcompany.ai/api/v2/sessions`
Authentication	Header Auth (from step 1)
Body Content Type	JSON

Body:

Request body

{
  "agent": "h/web-surfer-flash",
  "messages": [
    {"type": "user_message", "message": "Find the top 3 trending repositories on GitHub today and report their names and star counts"}
  ]
}

h/web-surfer-flash is a built-in agent that comes with its own browser environment, so you can run a task without setting anything else up. To run your own agent, pass its name instead, or send an inline agent object. See Create a session for the full body.The response returns the session id you’ll use to poll for results:

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": {"status": "pending", "steps": 0},
  "agent_view_url": "https://platform.hcompany.ai/agents/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "latest_answer": null
}

Poll for completion

Add a second HTTP Request node in a loop:

Setting	Value
Method	`GET`
URL	`https://agp.eu.hcompany.ai/api/v2/sessions/{{ $json.id }}/status`
Authentication	Header Auth (from step 1)

Check the status field. The session is done when status is completed, failed, timed_out, or interrupted. Any other value (queued, pending, running, paused, idle, awaiting_tool_results) means it’s still going. Use an If node to branch on the status, and loop the “still running” branch back through a Wait node before hitting the status endpoint again. Two to five seconds is a good interval. Back off to ten to fifteen for tasks that run several minutes.

Status response

{
  "status": "running",
  "error": null,
  "steps": 7
}

Read the answer

The status endpoint tells you when the run is done, but it doesn’t carry the answer. Once the status is completed, add one more HTTP Request node to fetch the session and read latest_answer:

Setting	Value
Method	`GET`
URL	`https://agp.eu.hcompany.ai/api/v2/sessions/{{ $json.id }}`
Authentication	Header Auth (from step 1)

The latest_answer field holds the agent’s final result.

Import the full workflow

Rather than build the four nodes by hand, copy the JSON below and paste it onto an empty n8n canvas (or ⋯ menu → Import from clipboard). It wires the steps as a loop:

Wait pauses a few seconds.
Poll Status checks the state.
If reads the answer once the status is terminal, or loops back to Wait.

After importing, open each HTTP Request node and select your own Header Auth credential from step 1. The credential ID baked into the export won’t match your instance, so n8n shows the nodes as needing a credential until you pick yours.

n8n workflow JSON

{
  "nodes": [
    {
      "parameters": {},
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [0, 0],
      "id": "cddf1db5-ac4a-4020-907c-20039726f972",
      "name": "When clicking 'Execute workflow'"
    },
    {
      "parameters": {
        "method": "POST",
        "url": "https://agp.eu.hcompany.ai/api/v2/sessions",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "{\n  \"agent\": \"h/web-surfer-flash\",\n  \"messages\": [\n    {\"type\": \"user_message\", \"message\": \"Find the top 3 trending repositories on GitHub today and report their names and star counts\"}\n  ]\n}",
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.4,
      "position": [208, 0],
      "id": "afb14ac5-9686-44af-b0ff-7c6268defbb8",
      "name": "Start Session",
      "credentials": {
        "httpHeaderAuth": {
          "id": "REPLACE_WITH_YOUR_CREDENTIAL_ID",
          "name": "Header Auth account"
        }
      }
    },
    {
      "parameters": {
        "amount": 3,
        "unit": "seconds"
      },
      "type": "n8n-nodes-base.wait",
      "typeVersion": 1.1,
      "position": [416, 0],
      "id": "a1111111-1111-4111-8111-111111111111",
      "name": "Wait",
      "webhookId": "b2222222-2222-4222-8222-222222222222"
    },
    {
      "parameters": {
        "url": "=https://agp.eu.hcompany.ai/api/v2/sessions/{{ $('Start Session').item.json.id }}/status",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.4,
      "position": [624, 0],
      "id": "cdff9632-065d-41a0-b71f-563d70c2eddf",
      "name": "Poll Status",
      "credentials": {
        "httpHeaderAuth": {
          "id": "REPLACE_WITH_YOUR_CREDENTIAL_ID",
          "name": "Header Auth account"
        }
      }
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict",
            "version": 2
          },
          "conditions": [
            {
              "id": "c3333333-3333-4333-8333-333333333333",
              "leftValue": "={{ ['completed','failed','timed_out','interrupted'].includes($json.status) }}",
              "rightValue": "",
              "operator": {
                "type": "boolean",
                "operation": "true",
                "singleValue": true
              }
            }
          ],
          "combinator": "and"
        },
        "options": {}
      },
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [832, 0],
      "id": "d4444444-4444-4444-8444-444444444444",
      "name": "Session finished?"
    },
    {
      "parameters": {
        "url": "=https://agp.eu.hcompany.ai/api/v2/sessions/{{ $('Start Session').item.json.id }}",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.4,
      "position": [1040, -96],
      "id": "72eccd6a-4d0e-4f55-9809-ba7708d8760b",
      "name": "Read Answer",
      "credentials": {
        "httpHeaderAuth": {
          "id": "REPLACE_WITH_YOUR_CREDENTIAL_ID",
          "name": "Header Auth account"
        }
      }
    }
  ],
  "connections": {
    "When clicking 'Execute workflow'": {
      "main": [[{ "node": "Start Session", "type": "main", "index": 0 }]]
    },
    "Start Session": {
      "main": [[{ "node": "Wait", "type": "main", "index": 0 }]]
    },
    "Wait": {
      "main": [[{ "node": "Poll Status", "type": "main", "index": 0 }]]
    },
    "Poll Status": {
      "main": [[{ "node": "Session finished?", "type": "main", "index": 0 }]]
    },
    "Session finished?": {
      "main": [
        [{ "node": "Read Answer", "type": "main", "index": 0 }],
        [{ "node": "Wait", "type": "main", "index": 0 }]
      ]
    }
  },
  "pinData": {},
  "meta": {}
}

The loop runs until the session reaches a terminal state. Add a counter if you want a hard cap on the number of polls.

Event-driven alternative

Instead of polling, use Webhooks to get a callback when a session changes status.

Add a Webhook trigger node in n8n

Copy its Production URL.

Call the Create webhook API with that URL for your organization. Subscribe to session.completed and session.failed, or to session.status_updated for every transition (see the event catalog).

Handle the delivery

n8n receives a POST whenever a matching event fires, with session_id, status, and previous_status in the payload. Deliveries are signed and retried with backoff, so the same event can arrive more than once: verify the signature (see Verifying deliveries), skip event ids you’ve already processed, and fetch the session for the authoritative state.

The same pattern works with any tool that can make HTTP requests, such as Make, Zapier, Pipedream, or your own orchestrator.

Next steps

Create a session

The full session request body and options.

Session status

States, step count, and the polling pattern.

Webhooks

Signed callbacks on status changes, and how to verify them.

SDKs

The typed Python and TypeScript clients and the hai CLI.

Get started

Concepts

Browser

Desktop

Integrations

Guides

Operate

Create a credential

Start a session

Poll for completion

Read the answer

Import the full workflow

Event-driven alternative

Next steps

Create a session

Session status

Webhooks

SDKs

Create a credential

Start a session

Poll for completion

Read the answer

​Import the full workflow

​Event-driven alternative

​Next steps

Create a session

Session status

Webhooks

SDKs

Import the full workflow

Event-driven alternative

Next steps