n8n

Run agents from an n8n workflow with plain HTTP Request nodes.

Build the workflow

1. 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.

2. Start a session

   Each call in this workflow 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 }}

   For the US region, replace agp.eu.hcompany.ai with agp.hcompany.ai.

   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 to 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
   }
   
3. 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, idle	Done (idle: an interactive agent answered and waits for a follow-up)	Go to step 4
   failed, timed_out, interrupted	Ended without an answer to use	Stop, read error
   queued, pending, running, paused, awaiting_tool_results	Still going	Loop back to Wait

   Status response

   {
     "status": "running",
     "error": null,
     "steps": 7
   }
   
4. Read the answer

   The status endpoint doesn’t carry the answer. Once status is completed or idle, 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.

{
  "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','idle','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.

1. Add a Webhook trigger node in n8n

   Copy its Production URL.

2. Register the 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).

3. 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.

Other automation tools

The same pattern works with Make, Zapier, Pipedream, or any tool that can make HTTP requests.