> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an HVAC answering agent

> An answering agent backed by your field-service software — recognizes customers, captures requests, checks job status, and escalates emergencies.

This guide builds a working answering agent for a home-services business (HVAC, plumbing,
electrical — same shape), backed by your **field-service software**. It recognizes returning
customers, captures new jobs straight into your system, tells callers when their tech is coming,
and escalates emergencies to a person. Every step is one API call against
`https://builder.flowyte.com/api/v1`.

<Note>
  Authenticate every request with a secret API key: `Authorization: Bearer flowyte_sk_…`. See
  [Authentication](/get-started/authentication) to mint one.
</Note>

## What you'll wire up

| Action                              | Endpoint                                          | Scope                |
| ----------------------------------- | ------------------------------------------------- | -------------------- |
| Create the agent                    | `POST /agents`                                    | `agents:write`       |
| Add knowledge                       | `POST /agents/{id}/knowledge/sources`             | `knowledge:write`    |
| Connect your field-service software | `POST /integrations/{kind}/connect`               | `integrations:write` |
| Provision its skills                | `POST /agents/{id}/integrations/{kind}/provision` | `skills:write`       |
| Add a transfer skill                | `POST /agents/{id}/skills`                        | `skills:write`       |
| Publish                             | `POST /agents/{id}/publish`                       | `agents:write`       |
| Simulate                            | `POST /agents/{id}/simulate`                      | `agents:read`        |
| Assign a number                     | `POST /numbers/{id}/assign`                       | `numbers:write`      |

<Steps>
  <Step title="Create the agent">
    Give it a name and a primary language. Capture `data.id` as your `AGENT_ID`.

    ```bash theme={null}
    curl -X POST https://builder.flowyte.com/api/v1/agents \
      -H "Authorization: Bearer $FLOWYTE_API_KEY" -H "Content-Type: application/json" \
      -d '{ "name": "Capital Comfort Heating & Air", "primaryLanguage": "en" }'
    ```
  </Step>

  <Step title="Give it knowledge">
    Add your service area, pricing, and FAQs. Ingestion is **asynchronous** — poll the source until
    `status` is `indexed`.

    ```bash theme={null}
    curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/knowledge/sources \
      -H "Authorization: Bearer $FLOWYTE_API_KEY" -H "Content-Type: application/json" \
      -d '{ "kind": "url", "label": "Services & pricing", "url": "https://capitalcomfort.com/services" }'
    ```
  </Step>

  <Step title="Connect your field-service software">
    Find your provider's `kind` in `GET /integrations/catalog`, then start the connection. For an
    OAuth provider this returns an authorization link — open it once to approve access to your account.

    ```bash theme={null}
    curl -X POST https://builder.flowyte.com/api/v1/integrations/$KIND/connect \
      -H "Authorization: Bearer $FLOWYTE_API_KEY"
    # → { "data": { "oauthUrl": "https://provider.example.com/oauth/authorize?…" } }
    ```
  </Step>

  <Step title="Provision its actions as skills">
    Turn the connected account into skills on the agent in one call. By default it provisions the
    key actions — recognize a customer (`find_client`), capture a request (`create_lead`), and check
    a job's status (`get_job_status`).

    ```bash theme={null}
    curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/integrations/$KIND/provision \
      -H "Authorization: Bearer $FLOWYTE_API_KEY"
    ```

    Now the agent can greet a returning caller by name, open a request for a new job, and read back a
    customer's next scheduled visit.
  </Step>

  <Step title="Add an emergency transfer">
    For a burst pipe or a no-heat call, add a `transfer` skill that routes to your on-call person.

    ```bash theme={null}
    curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/skills \
      -H "Authorization: Bearer $FLOWYTE_API_KEY" -H "Content-Type: application/json" \
      -d '{
            "name": "Transfer to on-call",
            "description": "Transfer the caller to a person for emergencies like no heat, a gas smell, or a flooding leak.",
            "skillType": "transfer",
            "executionConfig": { "destination": "+14155550199" }
          }'
    ```
  </Step>

  <Step title="Publish">
    Editing changes a **draft**; phone and chat serve the last **published** version. Publish to
    freeze a version your channels can serve.

    ```bash theme={null}
    curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/publish \
      -H "Authorization: Bearer $FLOWYTE_API_KEY"
    ```
  </Step>

  <Step title="Simulate a call">
    Test before a real caller hits it. `simulate` streams over SSE — read it with `fetch()` streaming
    and stop on `event: done`.

    ```bash theme={null}
    curl -N -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/simulate \
      -H "Authorization: Bearer $FLOWYTE_API_KEY" -H "Content-Type: application/json" \
      -d '{ "message": "Hi, my furnace stopped working and I need someone out today.", "draftMode": false }'
    ```
  </Step>

  <Step title="Put it on a number">
    Buy a number and point it at the agent (search → reserve → purchase → assign). See
    [Buy a number & go live](/guides/buy-a-number).
  </Step>
</Steps>

<Tip>
  No field-service integration? You can still capture requests by email or webhook and book to a
  connected calendar — the same shape, different skills.
</Tip>