> 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/worked-example.md).

# Worked example

A real HubSpot-to-Google-Sheets build, from plain-words prompt to bound trigger.

This is an actual run, screen by screen. The request was one sentence:

> When a new contact is created in HubSpot, add a row to a Google Sheet with their name, email, and company.

Everything below is what the agent did with it.

{% stepper %}
{% step %}

#### Describe it in plain words

Type the whole thing into **What should your customers be able to do?** on Home and send it. There is no need to name connectors, pick a trigger, or know what a workflow is yet.

The session is added to the **Sessions** rail on the left, named after your prompt, so you can leave and come back to it.

Three things on this screen are worth knowing before you go further:

* **The approval-mode chip** sits under the composer: here set to **Manual**. It decides whether the agent pauses before acting. See [Approval mode](https://docs.fastn.ai/build/agent/approval-mode.md).
* **The context meter** on the right (`19k / 1000k`) shows how much of the session's context window the conversation has used.
* **AI credits** in the top bar (`50 of 50 AI credits left`) are what agent runs draw down. Only Owners and Admins see this badge.
  {% endstep %}

{% step %}

#### It asks before acting, because Manual mode was on

The agent needed to create connect links for the two systems. In **Manual** mode it does not just do that; it stops and shows you each call.

Every gate shows you the same five things:

| On the card                  | What it is                                                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Create connect link**      | The action in plain language                                                                                                               |
| `create_connect_link`        | The literal tool being called                                                                                                              |
| The change preview           | What the call will change, drawn as a before/after                                                                                         |
| **VIEW RAW INPUT**           | The exact arguments as JSON, here the `connectorId` it is acting on. Secrets are redacted, and an input over 50,000 bytes is not displayed |
| **NOTE TO AGENT (OPTIONAL)** | Free text: *"On reject, this note is sent to the agent so it can re-plan…"*                                                                |

And three ways out: **Accept** runs this one call, **Always allow** stops asking for that tool for the rest of the session, and **Reject** refuses it: with your note attached, so the agent re-plans rather than simply retrying.

{% hint style="info" %}
The note is the useful part of rejecting. *"Use the sandbox sheet, not the production one"* gets you a corrected plan; a bare reject just gets you a stuck agent.
{% endhint %}
{% endstep %}

{% step %}

#### It asks what you actually meant

Rather than guessing at the ambiguous parts, the agent puts the question back to you as selectable cards. This run got two.

**How much should it sync?**

* **Ongoing sync only**: *Sync new contacts as they are created in HubSpot from now on.*
* **Initial import + ongoing sync**: *Import all existing HubSpot contacts into the spreadsheet first, then continue syncing new ones in real time.*
* **Other…**: *Type a free-form answer.*

**Who is it for?** The tenancy question, answered here with **For customers (Multi-tenant)**.

Those two answers change the generated code materially, which is exactly why it asks instead of assuming. Every question also offers **Other…**, so you are never boxed into the options it drafted.
{% endstep %}

{% step %}

#### It writes a plan you can read before anything is built

The agent produces an **Integration Plan** (a real markdown document, here `/plan-hubspot-to-sheets.md`), in a side panel, and the **Build progress** tracker beside it.

The plan spells out the mechanism, not just the intent:

1. **Trigger**: the real-time `contact.creation` event from HubSpot.
2. **Fetch details**: retrieve the contact's full profile (`firstname`, `lastname`, `email`, `company`) using HubSpot's `getContact` action.
3. **Target action**: Google Sheets `appendValues`, appending `[First Name + Last Name, Email, Company]` to the designated tab.
4. **Delivery**: ongoing real-time sync, with an optional initial backfill of existing contacts.

Below that sits a **Field Mapping** table with a worked example per row, and a **Tenancy** section reflecting the multi-tenant answer:

| HubSpot contact field              | Google Sheet column | Example                |
| ---------------------------------- | ------------------- | ---------------------- |
| First Name + Last Name / Full Name | Name                | Jane Doe               |
| Email (`email`)                    | Email               | <jane.doe@example.com> |
| Company (`company`)                | Company             | Acme Corp              |

The panel header carries a download icon (**Download document**): the plan is a portable artifact, useful for review before you let it build.
{% endstep %}

{% step %}

#### It builds in tracked phases

**Build progress** is the honest view of what is happening. It counts completed steps against the total (`0/6` → `2/6` → …) across the phases the agent has written steps into (up to four), each expandable into named substeps.

| Phase             | Substeps in this run                                                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Use cases**  | Plan & confirm HubSpot to Google Sheets contact sync                                                                                      |
| **2. Connectors** | Create and authorize the two connectors                                                                                                   |
| **3. Workflows**  | Review & approve field mappings and test cases · Build and test contact sync workflow · Bind HubSpot `contact.creation` app event trigger |
| **4. Widget**     | Expose the integration in the widget                                                                                                      |

A completed phase collapses to a green check and **Complete**. The one in flight shows a spinner against the current substep, so you always know which of the six things it is doing.

Notice that the last substep of **Workflows** is binding the trigger. The agent does not stop at generated code. It wires the thing that makes it run.
{% endstep %}

{% step %}

#### It brings the mappings back for approval

Before writing the workflow, the agent posted its **Proposed Field Mappings** into the chat, with a **Field Mappings & Connectors** artifact chip that reopens the full document:

* **Name**: combines the HubSpot contact's `firstname` and `lastname` into the Name column.
* **Email**: maps the contact's `email` to the Email column.
* **Company**: maps the contact's `company` to the Company column.

This is the moment to correct it. Replying *"put first and last name in separate columns"* here is far cheaper than editing generated code afterwards, and the agent updates the code, the mappings and the test cases together, so they cannot drift apart.
{% endstep %}

{% step %}

#### Then test and publish as usual

What the agent hands over is an ordinary workflow, a `<slug>.js` module. It opens in the [workflow editor](https://docs.fastn.ai/build/integrations/workflows.md) (the code itself is shown only where code view is switched on for your organization), its generated scenarios sit on the **Test cases** tab, and you run it from the **Test** tab. Publishing a snapshot and deploying it are the same steps as for anything you wrote by hand. See [Lifecycle](https://docs.fastn.ai/build/lifecycle.md).
{% endstep %}
{% endstepper %}

### What this run tells you about the agent

* **It asks rather than assumes.** Two ambiguities in a one-sentence brief became two explicit questions, each with an **Other…** escape hatch.
* **It plans in writing first.** The Integration Plan is readable, downloadable, and exists before any building starts.
* **It shows its work.** Six tracked steps across four named phases, not a spinner and a promise.
* **It finishes the job.** Binding the app-event trigger is part of the build, not homework left for you.
* **Manual mode is a real gate.** Every call surfaced its exact tool name and a preview of the change, with a note field that turns a rejection into a re-plan.

{% hint style="info" %}
Manual mode is worth the extra clicks the first few times, purely because the approval cards show you which tools the agent reaches for. Once the shape is familiar, switch to **Auto** (as this run did partway through) and let it work.
{% endhint %}


---

# 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/worked-example.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.
