# Trigger Guide

The ideas behind starting are the same as in the SaaS edition ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md)). This page sets out what differs in the Marketplace edition.

## What each type can use

|                           | Workflow                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Cycle                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| Starting it by hand       | “**Start case**” (project participants and people with the organization operations role)                                                                                                                                                                                                                                                                                                                                                                     | No                                                          |
| Starting it at a set time | Time triggers. **Parameters cannot be passed at the start**                                                                                                                                                                                                                                                                                                                                                                                                  | A sweep schedule set on each placement                      |
| Starting it from outside  | The external API (a service account token, or an application token of project participants and people with the organization operations role). Parameters can be passed when starting a run. **They cannot be passed when calling a webhook trigger**. Once the owner publishes it under “External access (A2A, MCP)”, external agents (A2A) and MCP clients can also start it with a request, in environments where an administrator has opened the entrance | The external API calls a webhook trigger (registered first) |
| Starting it by email      | No                                                                                                                                                                                                                                                                                                                                                                                                                                                           | No                                                          |

## Creating and enabling automatic starts

**To create or enable starts that run automatically — at a set time, by webhook or by sweep — the administrator must allow you “Scheduled run creation” in Feature permissions.** People who are not allowed are refused these operations: creating or enabling a trigger (time or webhook), setting or changing a step's time (workflow), enabling a sweep or changing the schedule of an enabled sweep, and importing from a file or creating from a company template a definition that contains any of these. **Starts that already exist do not stop.** Stopping or removing, saving a step's time with the same value, and changing an enabled trigger's settings while leaving it enabled can be done without the permission. Changing the schedule of an enabled sweep is refused.

**Everything that runs automatically is listed under “Automations” at the top of the project area.** The triggers, first-step times and sweeps of the projects you take part in are shown with their kind, where they belong, their status and their next start. **Of the step times, only that of a workflow's first enabled step is listed** (nothing is listed when that step has no time). In a project with an enabled time trigger, it shows as “Inactive”, because that time does not start a run. Create, change or stop each one on its own screen, opened from its name.

Where in the UI The permission: “Connections and Usage Scope” > “Feature permissions” > “Scheduled run creation” in the admin console (system administrators). The list: “Automations” at the top of the project area

## Starting a workflow

**To start from the screen, use “Start case”.** You can enter the parameters, connectors and instruction files for each placement for that case ([Case Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/case-guide.md#starting-a-case)).

**When starting a run through the external API, you can pass the same parameters, connectors and input files as “Start case” at the start** (`config`; [System Integration API Reference — Start a run](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/api-reference.md#start-run)). **A case started from a time trigger or a webhook trigger call cannot be given parameters at the start.** In that case, each agent's parameters are the contract's defaults overlaid with the step settings. When you attach `payload` to an external API call, its content is passed to the agent of the first step as a request. It does not become parameters. Whether the request is used depends on how the agent is built ([Workflow Guide — Request of a run started from outside](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/workflow-guide.md#request-of-a-run-started-from-outside)).

**If the required parameters, connectors and input files are not all in place from the step settings (with the values passed in `config` layered on top when you pass `config` from the external API), that case does not start.**

- With a time trigger, that round does not start, and it moves on to the next scheduled time
- With the external API, an error is returned

**If you run it from a time trigger, a Webhook trigger, or the external API without `config`, put all the required values in the step settings** ([Agent Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/agent-guide.md#step-settings-workflows)).

The external API can be called with two kinds of tokens.

- A service account token (system integration): created in the admin console. A service account can perform its allowed operations on every project in this environment ([System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/api-reference.md))
- An application token: obtained when a user signs in from an external tool. It is available only in environments where an administrator has opened the entrance for sign-in from an external tool. The participants of the project (owners, operators and members) and people with the organization operations role can start a case or call a webhook trigger ([User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md#common-access)). A token obtained by signing in to the Main Screen cannot be used

## Running a cycle

How to set the sweep schedule is the same as in the SaaS edition. In the Marketplace edition, the following are fixed.

- **A round that comes while the same placement is running is skipped.** Rounds are not piled up to be run together later
- **A round more than 5 minutes past its schedule is recorded once as skipped, and it moves on to the next scheduled time.** Rounds from while the environment was stopped are not all run afterwards
- **For 60 seconds after the same placement's previous execution ends, the next sweep is skipped.** Webhook calls wait 60 seconds before starting
- **While a webhook call is waiting to start on the same placement, sweeps are skipped too**

**If the agent does not exit after processing, the next round of that placement keeps being skipped.** If skips continue, have the agent's developer check how it exits ([Your First Agent](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/quickstart/quickstart-sdk.md#exit-after-run)).

## Time of day per step (workflows)

**In a workflow, a step with an agent placed can have a time at which it runs.** There are two choices.

- **Right after the previous step** — The default. It runs as soon as the previous step finishes
- **At a set time** — After the previous step finishes, it waits until that time, then runs

**Only the second and later steps wait for the time.** The first enabled step runs as soon as the case starts (its time is treated as the case's start time; see the paragraph below). When a review sends the case back to a step that has a time, that step runs without waiting for the time.

**Use it to hold the start until a time you choose.** **It does not limit the time once it has started** (how long a run may take is set by the execution limit in the agent's contract). **A cycle does not have this setting.** In a cycle, the time is set by the sweep period.

**The time of the first enabled step becomes the case's start time** (**when there is no enabled time trigger**). Putting a time there alone is enough to start on a schedule. **As with a time trigger, you cannot pass settings values when a case is started this way** ([Starting a workflow](#starting-a-workflow)).

Where in the UI Edit > select the step in the middle diagram > “Step settings” on the right > “Trigger”

## Running it by webhook (cycles)

Registering a webhook trigger works as in the SaaS edition. **What differs is how the calls received are handled.**

- **Calls are not merged.** Each call received is passed to the same placement one at a time, in order. The number of calls and the number of runs are the same
- Up to 20 can wait per placement. Beyond that, `429 queue_full` is returned
- A call that could not be started within 24 hours of being accepted is not started

**Delete or disable a webhook trigger, change the placement it starts, change the placement's environment variables, or pause the project, and calls not yet started become invalid too** (the delete confirmation shows “Start requests waiting to be accepted are also invalidated.”). A call made while paused is refused with `409`.

## The number that can run at once (workflows)

**There is a limit on how many cases can be in progress at once.** What is counted is the total of running cases and cases awaiting review, **up to 3** ([Settings reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/reference/settings-ref.md)).

If you try to start a new one while the limit is reached:

- **Manually (Start a case)** — It is refused
- **External API** — It is refused (`429`)
- **At a set time (a time trigger, or the first enabled step's time)** — **That time is skipped and is not made up later**

**When reviews pile up, new cases stop starting.** See the [Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/review-guide.md) for reviewers and how to proceed. If you start cases from the external API, the caller needs a way to hold refused requests and resend them later.

## Specifying times and time zones

**Time specifications come in forms you only have to choose.** Choose from Interval (every N minutes), Hourly, Daily, Weekdays, or Weekly. **You do not need to write a cron expression.** Choose “Custom (cron)” for finer control.

**A time also takes a time zone.** **Before saving, check that it is the one you intend.**

Where in the UI Every screen that sets a time has the same form: choose a preset and a “Timezone”. Time trigger = Settings > “Triggers and notifications”; step time = Edit > select the step > “Step settings” > “Trigger”; sweep period = Edit > select the agent > “Step's agent” > “Trigger” > “Sweep schedule”

## When it does not go to plan

**A registered agent's step follows a fixed handling for each way it ends (workflows).** There is no setting on the screen for choosing the handling.

| How it ends                                                                                                                       | Handling                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Completed, skipped as nothing to do                                                                                               | It moves on to the next step                                                                                                                                          |
| Not completed, stopped                                                                                                            | It is not redone automatically; a review request is created (sending it back to the same step can be chosen)                                                          |
| Not allowed by rules, other skips                                                                                                 | A review request is created (if the step's “when not allowed by rules” was set to “close as failed” through the external API, a case denied by rule closes as failed) |
| Failed, timed out (what happened is known, and the effect on external systems is “**Read only**” or “**Writes (safe to retry)**”) | **It is retried automatically.** Once the retries are used up, **the case closes as failed**                                                                          |
| Failed, timed out (the effect on external systems is “**Writes (retry may duplicate)**”)                                          | So that it does not write twice, it is not retried automatically; a review request is created                                                                         |
| An ending where what happened is unknown                                                                                          | Whatever the kind of effect on external systems, it is not retried automatically; a review request is created                                                         |

- Automatic retries go up to the smaller of the project's “Retries per step” and 2

- “An ending where what happened is unknown” covers cases where the agent's process ended abnormally, the Pod disappeared, the result could not be fully received, or **it was cut off at the contract's execution limit** (900 seconds by default). A timeout due to the execution limit is not retried automatically

- **When the execution rules could not be read before starting** (for example, when there is a forbidden operation pointing to a connector that does not exist), it checks again after a short while, and creates a review request once the attempts are used up

## Stopping and resuming

As in the SaaS edition, pausing the project stops every run from starting anew. The Marketplace edition adds the following ways to stop.

| What you want to stop                | How                                                                                                                                                                                                                                                                               |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A case in progress (workflows)       | “**Cancel case**” on the case screen (owners, operators and people with the organization operations role, and the person who started that case). [Case Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/case-guide.md#cancelling-a-case) |
| One execution of a cycle in progress | “**Stop**” on that execution's run record (owners, operators and people with the organization operations role)                                                                                                                                                                    |

**When an administrator stops the project, or suspends the account of the user it runs as, the following happens.**

| What happened                                                                                | Behavior                                                                                                                                                                     | How to recover                                                    |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| An administrator stopped the project (“Agent inventory” in the admin console)                | New cases do not start and patrols stop. The screen shows “An administrator stopped this, so you can't do that” (the external API returns 409 `admin_stopped`)               | Ask an administrator to resume it                                 |
| An administrator suspended the account of the user the project runs as (the project's owner) | Starting and resuming cases are refused. The screen shows “The user this project runs as is suspended, so it can't run” (the external API returns 409 `principal_suspended`) | Ask an administrator to transfer ownership or lift the suspension |

## Distinctions worth keeping straight

- **Thinking the case settings can be entered from a time trigger or a webhook trigger too.** At the start, they can be entered only from “Start case” and when starting a run through the external API (`config`). A time trigger or a webhook trigger runs on the values in the step settings. The settings of a case awaiting review can be changed both on the screen and through the external API (owners only)
- **Thinking a time trigger always starts at its time.** When required values are missing, or the number that can be in progress at once (3) has been reached, and so on, that round does not start, and it is not made up
- **Thinking cycle webhooks are merged into one run.** In the Marketplace edition, they run one at a time, in order
- **Thinking a review moves on at the deadline.** It does not ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/review-guide.md#the-deadline-does-not-decide))
- **Thinking it can be started by email.** Starts are done by time, manually, by webhook, and so on

## What to read next

- [Case Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/case-guide.md) — starting a case, and versions of settings and artifacts
- [Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/review-guide.md) — deadlines and external waits
- [Record Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/record-guide.md) — how to read the results
