> For the complete documentation index, see [llms.txt](https://docs.ai.insly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent.md).

# Build an agent

This section is for **developers building an agent** that runs as a step in a Nora [agentic workflow](https://docs.ai.insly.com/nora/agentic-workflows.md), for example an n8n workflow or your own service. If you only want to start runs and read results, see [Run agentic extraction via API](https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api.md) instead.

An agent is an HTTPS endpoint. For each step, Nora sends it one JSON request (the **envelope**) and reads back one result (the **completion**). Nora treats every agent the same way, whether Nora hosts it or you do.

### The envelope

For each step, Nora sends `POST <your webhook URL>` with `Content-Type: application/json`:

```json
{
  "workflowRunId": "1d2e3f4a-…",
  "agentRunId": "7b8c9d0e-…",
  "threadId": "5f0c3a6e-…",
  "messages": [
    { "role": "user", "content": "Please quote the attached fleet, renewal from 1 November." }
  ],
  "attachments": [
    { "fileId": "a1c2e3f4-…", "name": "fleet-schedule.xlsx", "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "size": 40211, "source": "thread" }
  ],
  "authToken": null,
  "schema": null,
  "workflowParams": { "submissionId": "3b7f0a1e-…" },
  "previousPayload": { "submissionId": "3b7f0a1e-…" },
  "assistant": {
    "name": "Nora",
    "descriptor": "Insly's AI assistant",
    "tone": "friendly/casual",
    "styleNotes": null,
    "instructions": "…"
  },
  "callbackToken": "eyJhbGciOiJIUzI1NiIs…"
}
```

<table><thead><tr><th width="170">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>agentRunId</code></td><td>This step's id. Return it in your completion.</td></tr><tr><td><code>workflowRunId</code>, <code>threadId</code></td><td>The run and the conversation this step belongs to.</td></tr><tr><td><code>messages</code></td><td>The conversation so far, oldest first, ending with the message that triggered the run. At most 30 messages. <code>role</code> is <code>user</code> for the sender and <code>system</code> for Nora.</td></tr><tr><td><code>attachments</code></td><td>The conversation's documents, as ids only, never as bytes or URLs. Download them with <a href="https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints.md#download-a-file">the file endpoint</a>.</td></tr><tr><td><code>workflowParams</code></td><td>The run's parameters: what was gathered from the sender, what is pinned for this step, and what earlier steps produced (see <a href="https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent.md#declaring-what-your-agent-needs">configuration</a>).</td></tr><tr><td><code>previousPayload</code></td><td>The previous step's <code>outputPayload</code>. <code>null</code> on the first step.</td></tr><tr><td><code>authToken</code></td><td>Your organisation's token for this agent, if your agent's settings declare one. Otherwise <code>null</code>.</td></tr><tr><td><code>schema</code></td><td>The JSON Schema stored in your agent's settings, if any, forwarded as is. Useful for an agent that extracts data against a schema. Otherwise <code>null</code>.</td></tr><tr><td><code>assistant</code></td><td>Your organisation's assistant name and tone. If your agent writes text for the customer, paste <code>assistant.instructions</code> into your system prompt, so your messages sound like Nora's own replies.</td></tr><tr><td><code>callbackToken</code></td><td>A credential for this step only. Use it as <code>Authorization: Bearer</code> on the <a href="https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints.md">agent endpoints</a>. It is valid for your agent's configured timeout.</td></tr></tbody></table>

{% hint style="warning" %}
Treat everything in `workflowParams` and `messages` as untrusted input. Values come from the sender's messages, from your organisation's configuration, and from other agents' output.
{% endhint %}

### Answering: right away, or later

Answer with any `2xx`. Nora reads the response body and decides which of these two cases applies.

**Answer right away.** If the body is a completion, the step finishes straight away:

```json
{
  "type": "completion",
  "agentRunId": "7b8c9d0e-…",
  "isComplete": true,
  "outputPayload": { "quoteReference": "Q-10442" },
  "outputMessage": "Your quote Q-10442 is ready."
}
```

A body counts as a completion only if it has `type: "completion"`, a string `agentRunId`, a boolean `isComplete` and a string `outputMessage`. `outputPayload` is an optional JSON object.

**Answer later.** Any other `2xx` body, including an empty one or `"OK"`, counts as an **acknowledgement**. The step waits until you send the same completion JSON to the [callback endpoint](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints.md#send-a-completion-or-progress-update). Use this for anything that takes longer than a few seconds.

{% hint style="info" %}
A completion with a typo (for example, a missing `outputMessage`) also counts as an acknowledgement. The step then waits until it times out. If a step seems to hang, check the body first.
{% endhint %}

You must answer, or call back, within your agent's **timeout**. After that the step fails with a "took too long" message, and the whole run fails, even if the step is optional. A non-`2xx` response, or a connection error, fails the step with a generic error message.

### Outcomes

<table><thead><tr><th width="230">You send</th><th>What happens</th></tr></thead><tbody><tr><td><code>isComplete: true</code></td><td>The step succeeded. <code>outputPayload</code> becomes the next step's <code>previousPayload</code>. On the last step, <code>outputMessage</code> is the reply the customer receives.</td></tr><tr><td><code>isComplete: false</code></td><td>The step failed. The run stops here, later steps don't run, and the customer receives an error reply based on <code>outputMessage</code>. If the step is marked optional, the run carries on without it.</td></tr><tr><td><code>isComplete: true</code> with <code>outputPayload.haltWorkflow: true</code></td><td>The run stops here with status <strong>completed</strong>, not failed, and <code>outputMessage</code> is the reply. Use this when stopping early is a normal result. Nora's validation step uses it for "required fields are missing".</td></tr></tbody></table>

Write `outputMessage` for the customer. Nora may adjust the wording to match your organisation's tone and the conversation, but keeps the content.

### Declaring what your agent needs

Each agent is registered with two declarations. Insly stores them when it registers your agent.

**Settings** are fixed per organisation when the agent is installed: credentials, a tenant URL and similar. The agent's **settings schema** (`settings_schema`) is a JSON Schema (draft-07), and the organisation's `settings` must match it. Nora checks this when the workflow is set up and again before every call. If the check fails, the step fails with a "not set up correctly" message and your agent is not called.

* Declare an `authToken` property if you want a per-organisation token. Nora sends it as `authToken` in the envelope, and only if you declare it.
* Declare a `ledger` property if your agent works with the organisation's Insly Ledger. Nora then adds `tenantId`, `ledgerBaseUrl` and `role` to `workflowParams`.
* An agent that needs no settings declares none.

**Configuration (`configuration`)** describes each run: what the agent needs and what it gives to later steps.

```json
{
  "parameters": {
    "type": "object",
    "properties": {
      "submissionId": { "type": "string", "description": "Submission to quote" },
      "inceptionDate": { "type": "string", "format": "date", "description": "Policy start date" }
    },
    "required": ["submissionId", "inceptionDate"]
  },
  "produces": ["quoteReference"]
}
```

* **`parameters`** is a JSON Schema for what your agent reads from `workflowParams`. Before the first step runs, Nora asks the sender for every required parameter that nothing else supplies. On the API nothing is asked; the start request fails with `400` instead. The `description` appears in the question sent to the sender, so write it for the customer.
* **`produces`** lists the keys of your `outputPayload` that later steps may use. After your step completes, Nora copies those keys into `workflowParams` for every later step. This is how `submissionId` gets from the conversion step to every later one.

A workflow asks the sender only for what is actually missing. That is every step's required parameters, minus anything an earlier step produces and anything pinned on the step.

**Pinned inputs.** A workflow can set a fixed value for a parameter on one step (`inputs`), for example `{ "productCode": "MOTOR-FLEET" }`. The pinned value goes to that step only and is never asked for. `tenantId`, `ledgerBaseUrl` and `role` are reserved for Nora and can't be pinned.

### Registering an agent

There is no self-service API for registering agents yet. To register one, send Insly:

* the webhook URL (HTTPS, reachable from the internet),
* a timeout in seconds. This is how long you may take to answer or call back. It also sets how long the `callbackToken` is valid,
* the `settings_schema`, and the organisation's `settings`,
* the `configuration` (`parameters` and `produces`),
* which workflow the agent belongs in, and at which position.

Next: [Agent endpoints](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints.md), for sending a completion later, reporting progress, and reading or attaching files.
