> For the complete documentation index, see [llms.txt](https://docs.autommate.com/userguide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autommate.com/userguide/mcp-and-ai-reference/structured-service-authoring.md).

# Build a service with an AI assistant

Build around a business outcome, reuse installed components and retain verified context. Do not invent actions, identifiers or mappings.

**Scope:** This procedure uses tool declarations exposed by the **Autom Mate New connection on 21 October 2026**. It is a declaration-based authoring guide, not an end-to-end runtime verification or a promise that every installation exposes these tools. Read the active schemas and [capability scope](https://docs.autommate.com/userguide/mcp-and-ai-reference/capabilities-and-version-scope) first. Product build and release availability must be checked for your environment.

## 1. Establish the brief and context

Record the requested outcome, source event, target systems, acceptance check and allowed side effects. Resolve the current environment, Hub/tenant context and account permissions before authoring.

On an MSP Hub connection, the declared `tenants_list` / `tenants_select` procedure requires the user to select or confirm the tenant for Hyperflows. Work Items, Services and deployments use Hub context. Follow the tool's current scope rules; switching context changes subsequent calls on that connection.

Maintain a **working decision record**. This is an agent artifact, not an API payload:

| Item       | Record                                                                      |
| ---------- | --------------------------------------------------------------------------- |
| Context    | Environment, account, selected tenant/Hub and discovery time                |
| Outcome    | Exact business result and how it will be verified                           |
| Components | Application, action, Work Item and version references returned by discovery |
| Inputs     | Type, source, scope, sensitivity and any unresolved decision                |
| Changes    | Object/version/revision, preview result and authorized scope                |
| Evidence   | Readback, test run/Case and target-system result                            |

Reuse an explicit decision already made for this task when it remains valid. Ask about unresolved choices together rather than asking again at each step. Do not reuse an unrelated tenant's context.

## 2. Discover native components first

1. Search existing Services, Work Items and Hyperflows before creating duplicates.
2. Use `applications_search` and `libraries_search` to find the installed application and integration. Discover actions with `library_search_actions`; inspect the chosen `action_ref` with `library_get_action`.
3. Inspect existing reusable Work Item contracts with `work_items_search`, including their released versions, input bindings and declared outputs.
4. For an application event, call `trigger_events_search` before designing a custom webhook or polling flow. Inspect the event's delivery mode, setup form and payload fields.
5. Where an action uses Data Manager, read its model with `data_manager_get`. This reads configuration; it does not execute an arbitrary lookup. Use an exposed supported read action or documented API path when actual source data is needed. `data_manager_capture_sample` stores a previously obtained response; it does not run the action.

Use an existing native action when its contract covers the requirement. Introduce a custom action or direct HTTP integration only after identifying the specific native gap. Preserve that decision in the working record.

**Current trigger boundary:** `automs_set_trigger` configures an App Trigger on an Autom draft. `services_create` declares several Engage entry types, but the inspected declarations do not establish a complete mapping from every App Trigger event to Service Engage. A `saas` label alone is not proof of that integration. Confirm the supported route before building it.

## 3. Resolve the contract before building

Separate request data, tenant configuration, credentials and values computed by earlier Work Items. Bind an Engage field or earlier output when its semantics, type and scope match. Avoid unnecessary manual deployment constants. Follow [deployment input resolution](https://docs.autommate.com/userguide/mcp-and-ai-reference/deployment-input-resolution) and the active tool contract.

Use descriptive names that explain the outcome. For example, a service could be **Create a linked Xurrent request from Jira**; its Work Items could be **Validate request**, **Create linked request** and **Verify target request**. These are naming recommendations, not required API values. Use stable machine keys and readable labels; retain IDs and names already relied on by dependencies.

Specify what each Work Item returns: real fields, types, missing-value behavior and success/failure meaning. The actual Stop response produces runtime data; Example response only describes its shape. A fixed success string is not a Prove check.

## 4. Build, validate and read back

```mermaid
flowchart TD
    A[Outcome and active context] --> B[Discover native components]
    B --> C[Resolve inputs and output contracts]
    C --> D{Unresolved decision?}
    D -->|Yes| E[Ask one focused question set]
    E --> C
    D -->|No| F[Prepare typed change plan]
    F --> G[Preview and structural validation]
    G --> H[Apply within authorized scope]
    H --> I[Read back and controlled test]
    I --> J{Expected result verified?}
    J -->|No| F
    J -->|Yes| K[Release and configure deployment]
    K --> L[Authorized activation and Case evidence]
```

Use `automs_create` with the appropriate `autom_kind` for a Hyperflow, agent or Govern/Execute/Prove Work Item. Read its draft with `automs_get_flow`; use the returned step IDs and revision in `automs_edit_flow`. Batch related edits where possible. Use the step's Error Configuration for retry/stop behavior instead of constructing REPEAT/IF/DELAY retry loops.

Follow each mutation tool's preview/apply contract and authorization requirements. Preserve concurrency guards and use one idempotency key per intended operation. Keep the arguments consistent between preview and apply. Read back the resulting object before releasing or using it.

Release Work Items through the advertised operation, then use their published version references in Service lanes. **Service creation is not draft-only:** the inspected `services_create` preview states that apply creates the blueprint **and publishes version 1.0.0**. Review that publication before apply. It does not by itself create a tenant deployment or prove execution. Configure the intended deployment and inspect its checklist, bindings, versions and scope.

## 5. Verify and hand over

Test with authorized data and systems. Verify missing inputs, duplicate requests and relevant failure paths. Check the actual downstream result as well as the platform state.

The inspected `services_run` declaration supports **live deployments with webhook Engage**. Do not use it as proof of draft execution or other Engage types. Follow service execution with `cases_search` and `cases_get`.

Report states separately: **drafted → validated → released → deployment configured → live → executed → business outcome verified**. Include the actual object/version, tenant, Case/run reference, target-system evidence and any remaining owner/action. Do not call a service complete because its generated diagram looks correct.

See [AI entry index](https://docs.autommate.com/userguide/mcp-and-ai-reference/for-ai-agents-read-this-first), [reusable-service recipe](https://docs.autommate.com/userguide/mcp-and-ai-reference/use-cases-and-examples/reusable-tenant-service) and [read documentation from an AI client](https://docs.autommate.com/userguide/mcp-and-ai-reference/read-documentation-from-an-ai-client).

## Stop at a useful manual handover when that is the task

A Service-authoring task can finish with a reviewed, versioned blueprint and a manual configuration/deployment plan. Automatic deployment and go-live are separate capabilities and must not become an implicit prerequisite. Provide the operator with selected Work Items, published version IDs, native action contracts, tenant-specific fields, typed source mappings and unresolved decisions.

For a practical example, use [configurable employee offboarding](https://docs.autommate.com/userguide/mcp-and-ai-reference/use-cases-and-examples/configurable-employee-offboarding). Start with a small working path and improve it through versions. A longer flow or more Govern blocks is not evidence of a better service.

When a release result omits a published version ID, recover it through a supported read only if the match is unambiguous. Keep the omission visible. If authoring is interrupted, return saved IDs, versions, completed steps and remaining work so the next session can resume without duplicates.
