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

# Build with AI

The chat-driven builder that picks connectors, drafts workflows and shows you the diff.

**Build → Build with AI** (`/agent`), or the **What should your customers be able to do?** prompt on Home

The agent is the primary way integrations get built in fastn, and there are two ways in: **Build with AI** in the sidebar, the first item under **Build**, or the **What should your customers be able to do?** prompt on Home. Both land on the same screen, headed **Build an integration**, which states its own contract:

> Describe what you need in plain words. fastn's agent picks the connectors, drafts the workflow, and shows you the diff before anything runs.

What it drafts is JavaScript: a `<slug>.js` module exporting `export default async function(ctx)`, opened in the [workflow editor](https://docs.fastn.ai/build/integrations/workflows.md) for you to test and publish. You can read the code there only where code view is switched on for your organization; where it is off, the editor shows diagrams and docs, and you change the workflow through the agent.

### Sessions

The left rail, headed **Sessions**, holds your session history. Each session keeps its full conversation, so you can come back to an integration weeks later and continue where you left off rather than re-explaining it. Before you start anything it reads *No sessions yet. Click New session to start.*

* **New session** starts a fresh build.
* **Search sessions** (⌘K) filters the rail by name.
* **Collapse sessions sidebar** widens the workspace when you are reading a long diff.

### Starting from an example

Four cards sit under **START FROM AN EXAMPLE**, each pairing a goal with the concrete detail that makes it buildable:

| Card                               | What it asks for                                             |
| ---------------------------------- | ------------------------------------------------------------ |
| **Sync deals into billing**        | Closed-won Salesforce opportunities, custom fields included  |
| **Alert before an SLA breaches**   | Post to Slack when a Zendesk ticket is close to its deadline |
| **Keep a sheet current**           | Append new HubSpot contacts to a Google Sheet as they arrive |
| **Give an AI agent scoped access** | Read-only Jira for one customer, nothing beyond that         |

They are written in the shape a good first message takes (a system, a trigger, and the specific thing that moves) and are worth reading before you write your own.

{% hint style="info" %}
Do not confuse these with the suggestion chips on **Home**, which are seeded per workspace and differ between them. The four cards above are the agent screen's own examples.
{% endhint %}

### Writing a good first message

The agent handles ambiguity by asking, but you get a better first draft by being specific about four things:

| Say                | Example                                                 |
| ------------------ | ------------------------------------------------------- |
| **The systems**    | "HubSpot", "Cin7 Core", not "our CRM"                   |
| **What starts it** | "when a deal is closed-won", "every night at 2am"       |
| **What moves**     | "the company name, the deal amount, and the line items" |
| **The rules**      | "skip anything under $500", "only the EU warehouse"     |

The composer carries **Attach a file**, the message box (*Write a message…*) and **Send**.

### What it does

The product's own summary is the reliable one: fastn's agent picks the connectors, drafts the workflow, and shows you the diff before anything runs. In practice that means working out which systems are involved, reusing connectors that already exist and creating the ones that do not, handling authentication in the chat (inline API-key fields, or an OAuth form with client ID, secret and pre-filled scopes) and then writing the workflow code and opening it in the editor.

Generated test cases land on the editor's **Test cases** tab, in groups the agent names for the integration, each row badged **Live** or **Mock**.

### The integration plan

Before building, the agent writes a plan: a markdown document that opens in a side panel. The agent writes it for each integration, so its name and sections vary, but it typically sets out the trigger, the actions and connectors involved, and how fields map between the systems. Its header has a download icon (**Download document**), so the plan can be reviewed or circulated before anything is created.

Read it. It is the cheapest place to catch a wrong assumption: correcting a mapping here costs a sentence; correcting it after the workflow is generated costs a rebuild.

### Build progress

Alongside the plan, the **Build progress** section of the right-hand rail tracks the work as a step count (`0/6`, `2/6`, …) across up to four phases:

| Phase             | What happens                                                                   |
| ----------------- | ------------------------------------------------------------------------------ |
| **1. Use cases**  | Plan and confirm the integration with you                                      |
| **2. Connectors** | Create and authorize the connectors it needs                                   |
| **3. Workflows**  | Approve mappings and test cases, build and test the workflow, bind the trigger |
| **4. Widget**     | Expose the finished integration in the widget                                  |

Each phase expands to its named substeps, a completed one collapses to a green check and **Complete**, and the one in flight shows a spinner against the current substep. Only phases the agent has written steps into are shown, so the count varies with the integration: a build with no customer-facing surface will not have a Widget phase.

### Clarifying questions

Where your brief is ambiguous, the agent asks rather than guesses, rendering the question as selectable answer cards, each with a title and a sentence explaining what choosing it means. Every question also offers **Other…** for a free-form answer, so you are never limited to the options it drafted. Typical questions cover sync scope (ongoing only, versus an initial backfill first) and tenancy (internal, versus per-customer multi-tenant).

### Reading what it did

The agent's tool calls collapse into a single summary line in the chat: **Worked · 3 steps**, with **Show details** to expand the individual calls. Documents it produces appear as artifact chips that reopen the full panel.

Two counters are worth watching: the **context meter** beside the composer (`19k / 1000k`) shows how much of the session's context window the conversation has consumed, and **AI credits** in the top bar show what is left of your quota. The credits badge is shown to Owners and Admins only.

### Iterating

Follow-up messages refine what exists rather than starting over:

* "Add error handling for when the API is down"
* "Filter out records without an email address"
* "Change the schedule to hourly"
* "Notify Slack on failure"

The agent updates code, mappings and test cases together, so they do not drift apart.

### Attachments

**Attach a file** accepts an API spec, a sample payload, a field-mapping spreadsheet. Giving the agent a real payload is the single fastest way to get accurate mappings.

{% hint style="info" %}
Agent usage draws on the AI credits shown in the top bar (visible to Owners and Admins): click it for the balance, an org total, and the reset date. Quota resets at the start of each calendar month, UTC. The popover also breaks usage down **By agent**, listing each fastn agent that used credits in the period. Plan and quota detail live under [Billing](https://docs.fastn.ai/settings/manage/billing.md), which is visible to Owners and Admins.
{% endhint %}

{% hint style="warning" %}
Build with AI needs two things: the **Operator** role or above, and Build with AI switched on for your organization (fastn turns it on). If either is missing, **Build with AI** does not appear in the sidebar. Access is by role, not by an individual permission, so a role below Operator cannot be granted it one permission at a time.
{% endhint %}

### In this section

* [Approval mode](https://docs.fastn.ai/build/agent/approval-mode.md)
* [Worked example](https://docs.fastn.ai/build/agent/worked-example.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fastn.ai/build/agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
