Run agents from n8n

The Agents API works in n8n as a plain HTTP integration and needs no custom node. Every call below is an HTTP Request node with Authentication set to the Header Auth credential from step 1.

Node	Method	URL
Start Session	`POST`	`https://agp.eu.hcompany.ai/api/v2/sessions`
Poll Status	`GET`	`https://agp.eu.hcompany.ai/api/v2/sessions/{{ $('Start Session').item.json.id }}/status`
Read Answer	`GET`	`https://agp.eu.hcompany.ai/api/v2/sessions/{{ $('Start Session').item.json.id }}`

Create a credential

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

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

Create the key at platform.hcompany.ai/settings/api-keys. It’s shown once, and scoped to one organization.

Start a session

Add the Start Session node with Body Content Type set to JSON:

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 pre-built agent with its own browser, so you have nothing else to set up. To run your own agent, pass its name or an inline agent object (see Create a session). The response carries the session id:

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 Wait node (2 to 5 seconds, or 10 to 15 for tasks that run several minutes), then the Poll Status node, then an If node on status:

`status`	Meaning	Branch
`completed`	Done	Go to step 4
`failed`, `timed_out`, `interrupted`	Ended without an answer to use	Stop, read `error`
`queued`, `pending`, `running`, `paused`, `idle`, `awaiting_tool_results`	Still going	Loop back to Wait

Status response

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

Read the answer

The status endpoint doesn’t carry the answer. Once status is completed, the Read Answer node fetches the session: its latest_answer holds the agent’s final result.

Import the full workflow

Paste this JSON onto an empty n8n canvas (or ⋯ menu → Import from clipboard) to get the nodes above, wired as a Wait, Poll Status, If loop. Then open each HTTP Request node and pick your own Header Auth credential: the placeholder credential ID won’t match your instance. Add a counter if you want a hard cap on polls.

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": {}
}

Event-driven alternative

Instead of polling, get a webhook when a session changes status. The same pattern works with Make, Zapier, Pipedream, or any tool that can make HTTP requests.

Add a Webhook trigger node in n8n

Copy its Production URL.

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

Handle the delivery

Each delivery is a signed POST with session_id, status, and previous_status. The same event can arrive more than once: verify the signature, skip event ids you’ve already processed, and fetch the session for the authoritative state.

Get started

Concepts

Browser and desktop

Integrations

Guides

Operate

Create a credential

Start a session

Poll for completion

Read the answer

Import the full workflow

Event-driven alternative

Create a credential

Start a session

Poll for completion

Read the answer

​Import the full workflow

​Event-driven alternative

Import the full workflow

Event-driven alternative