# Design Guide

Creating one project means deciding one way of carrying out a task. This guide covers the options and criteria for deciding **what to decide as a business matter, how to divide it into steps, and what to hand to each step and how far**.

What steps and registered agents are is in [Projects and Steps](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/concepts/project-and-steps.md). Reading it first speeds up the decisions here. The settings of the registered agents you place on steps are in the [Agent Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/agent-guide.md).

## What to decide as a business matter

**Before deciding the type, the steps, and the agents, decide four things as a business matter.**

- **How far to delegate.** There are three clues. **Can it be undone if it goes wrong?** Put a review step before an agent that does something that cannot be undone (such as writing to an external system). You can tell the effect on external systems from the contract's “Effect on external systems” ([Agent Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/agent-guide.md#reading-the-contract-summary)). **Can you put the criteria for judging into words?** Leave judgments you cannot put into words to a person. **Can you reach the information you need?** List the information and destinations you need, and check before you start that outbound traffic is allowed ([Execution Rules and Network Access Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/control-guide.md#restricting-outbound-traffic))
- **What counts as done.** Decide the business end first, and turn it into the criteria a reviewer uses to decide whether to proceed. How to read execution results is in [Records and Metrics](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/concepts/records-and-metrics.md)
- **Where to divide projects.** Divide projects when the audience, the connectors, or the operations you allow differ. You can have up to 5 projects in one environment (deleted and archived projects are not counted; [Settings Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/reference/settings-ref.md))
- **Where to deliver the result.** If a person receives it, put a review step at the end of the workflow. If it goes to another system, either read the result through the external API or build the registered agent to write to a connector ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/trigger-guide.md))

## Choosing the type

The first thing to decide is the type.

|                             | Cycle                                                                | Workflow                                                               |
| --------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| How it ends                 | No start and no end; it continues                                    | Goes from start to end through the steps in order (one item is a case) |
| What can be placed on steps | Registered agents used in chat (no contract or certification needed) | Registered agents with a contract registered and certified             |
| How it starts               | A period per placement, or a webhook                                 | Manually (Start a case), by time, or by the external API               |

**The default on the project creation screen is workflow** (if you omit the type when creating through the API, it becomes a cycle). The criterion is “does it end?” If **each item starts and ends**, choose a workflow. You can follow the result item by item, and a review step can stop the case for a while. If it **has no end and keeps running**, choose a cycle. Placements run on their own periods, with no overall start or end. **Review steps and Branch steps can be placed only in a workflow.**

Where in the UI When creating the project > Type

## Dividing into steps

**How to divide into steps differs from the way of thinking onward, by type.**

|                    | Workflow                                                                         | Cycle                                                                                  |
| ------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Suits              | Take one item and process it in a fixed order to finish it                       | Pick up targets and keep processing them                                               |
| How it proceeds    | **The order of steps is the order.** The next starts after the previous finishes | Placements run independently on their own periods. **The arrangement is not an order** |
| How stages connect | **Only when you connect files**, the previous step's output is passed            | Outputs are not passed between steps                                                   |

If you create a project without specifying steps, a workflow gets three (a step for an agent, a review step, a step for an agent) and a cycle gets two. **A step's name has no rule set by the product.** Give it a name that suits the business. **The name never changes how it proceeds.**

### When dividing a workflow

A workflow is the type that **takes one item and finishes it**. The order of steps is the order of processing, and the next step starts after the previous one finishes. At a Branch step, only the chosen lane is passed through.

For example, consider a workflow that processes arriving documents one at a time and returns them.

1. **Check the contents** — A registered agent checks the document's entries and attachments
2. **A person approves** — The reviewer looks at the artifacts and decides whether to proceed or send back
3. **Register and return** — Another registered agent registers what was approved and returns it

**One item goes 1 → 2 → 3 and ends.** If it is sent back at 2, work restarts from the step it returns to. **You divide where you want to break up the progress.** Once divided, you can put the following at the break.

- **Put in a person's judgment** → Place a review step. **The case stops there for the time being**, and moves on by the reviewer's decision (or, for external wait, when the condition is met) ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/review-guide.md))
- **Make it a place to return to when sent back** → You specify where to restart, per step
- **Make it wait for a time** → A step can have a time. If you set none, it runs as soon as the previous step finishes ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/trigger-guide.md#time-of-day-per-step-workflows))

**When dividing who does what, decide by whether results are handed over.** If you place several agents on one step, they run one at a time in placement order, **The output of an agent that ran earlier is not passed automatically.** Connect the output you want the next agent to use, as the output of a placement that runs before it, to its input file ([Agent Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/agent-guide.md#step-settings-workflows)). Placements do not run in parallel; they run one at a time in placement order.

### When dividing a cycle

A cycle is the type that **picks up targets and keeps processing them**. Registered agents start independently on their own periods and **do not wait for other steps to finish**. So even if one stops, the rest keep running.

**One stage is fine.** If all you do is look at fixed intervals and act when needed, there is no need to divide into stages. If you create it without specifying steps you get two, but you turn off the one you do not use ([cycle quickstart](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/quickstart/cycle.md)). **A cycle cannot have a review step.** If you want a person's judgment in the flow, choose a workflow. **A cycle's steps are a classification of who does what.** They carry no numbers or arrows; if you want it to proceed in order, that is the workflow type.

**An agent in a cycle must be built to exit once it has finished one round of processing.** If it does not exit, the next round of that placement keeps being skipped ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/trigger-guide.md#running-a-cycle)).

Where in the UI Edit > “Editing tools” on the left > “Add a step”. Each setting appears on the right when you select a step in the middle diagram

## Branch steps (workflows)

**A Branch step reads the result of the previous step and decides which lane to follow.** No agent is placed on it. For each condition, you choose where to go when it matches: a lane, or “**Join directly**”. Only the steps of the chosen lane run, from the top, and then it goes on to the step after the join; the steps of the other lanes do not run.

- **Conditions are checked from the top**, and it goes where the first matching condition points. When no condition matches, the “When no condition matches” setting applies
- What a condition looks at includes the result text, the result JSON, artifacts, and the step's execution. **The conditions you can use look at the result text, the result JSON, artifacts, or the step's execution**
- The limits on the number of conditions and lanes are the same as in the SaaS edition ([SaaS Settings Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/settings-ref.md))

**Build workflow steps from a step with a registered agent, a review step, or a Branch step.**

## Placing registered agents on steps

The procedure for placing a registered agent, and the step settings and environment variables you decide afterwards, are in the [Agent Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/agent-guide.md). Rules of thumb:

- **You can place only certified registered agents** (workflows). If one is not certified, ask the administrator to register its contract and certification
- **You can place the same registered agent on another step too.** Each placement can have its own settings values and connectors
- **You cannot change a registered agent's behavior in the project.** What you want to change decides who you ask ([Agent Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/agent-guide.md#when-you-want-to-change-how-the-agent-behaves))

## What to do when it does not go to plan (workflows)

**A step with a registered agent runs by a fixed handling for each way it ends.** A failure where it is known what happened, and where the contract's “Effect on external systems” is “Read only” or “Writes (safe to retry)”, is **retried automatically**, and when the retries are used up the case closes as failed. For anything that may write twice (“Writes (retry may duplicate)”) or an ending where it is not known what happened, including a timeout at the execution limit, it is not retried automatically and a review request is made. So **you decide whether a job is safe to retry through the contract's “Effect on external systems”** (the full list is in the [Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/trigger-guide.md#when-it-does-not-go-to-plan)).

**To recover, either start a new case, or, if it is awaiting review, send it back and redo from a step partway.**

Where in the UI The number of retries is under Settings > “Execution rules”, “Retries per step (failed / timed out)” (for steps with registered agents, at most 2 take effect)

## Publishing and reuse

**A project can be published.** Once published, other users can copy its steps and the placements of its registered agents into their own projects.

**In a copied project, check the following.**

- **Steps, placements of registered agents, step settings, and the limits of the run rules** are copied
- For **connectors**, the list is copied. **Connections (authentication) are not copied**, so connect again in the copied project
- **Time triggers** are copied, but **arrive disabled**. Set the step to start from again
- A copy of a cycle does not get a review step

**The project creation screen offers three ways.** “Build it myself”, “Create from a company template”, and “Import from file”. An existing project can be copied with “Duplicate” on the project screen and on its card (owners only), or with “Copy to my projects” on a published project. Registered agents are registered by the administrator.

## Exporting, importing, and sharing as a company template

A project's definition (steps, placements of registered agents, time triggers, connectors) can be made into a file and carried to another environment, or published as a company template. Exporting and publishing a template are done from the Settings tab. Importing and creating from a template start from “How do you want to create it?” when creating a project.

**Only the owner can export.** Under the Settings tab's “Export definition”, the confirmed definition is saved as a JSON file. Connection credentials, reviewers, the values of environment variables, and starts other than time triggers (such as webhooks) are not included.

**If an imported definition contains features that cannot be used in this environment (an External automation step, a per-result next step, review routing, a notify-only review, automatic handling after the deadline, values and file roles passed to the next step, parallel lanes or “Run at the same time”, library linking, or a “Decide by a question” condition), that part is dropped on import and you are told in the import result.** A time trigger of a cycle definition is dropped in the same way (a cycle runs at set times through each placement's patrol).

Someone who is not allowed “Scheduled run creation” cannot import a definition that contains triggers, step times or an enabled sweep (nor create a project from such a template).

**A company template is a type in which the person using it fills in only the fields you decide.** Only the owner can publish one. **There is no input-file field among the fields the user fills in** (input files are chosen and passed on the case).

Where in the UI When creating > “How do you want to create it?” > “Import from file”, “Create from a company template” / Settings tab > “Export definition”, “Share as a company template”

## Checking a draft and applying it

Changes to steps and placements pile up as a **draft**. **The project does not change until you apply.** Applied settings take effect from the next run and do not affect runs in progress. However, placing a registered agent on a step **for the first time** does not go into the draft; **it is saved to the project right away** ([Agent Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/agent-guide.md)).

**When the tenant has the setting that requires approval for definition changes turned on, an applied change is not used until it is approved.** The first placement also becomes a version awaiting approval.

Before applying, you can **check settings**. The check covers the draft and **does not save**. For example, an enabled step with no agent placed, a review step with no reviewer chosen, and a cycle placement with no period set appear as points to fix before applying. That nothing is found does not mean the run will succeed.

**The Settings tab > “Basic information” does not use a draft; it changes when you save.** If the project was updated by another action after you started editing, a notice appears when you save, and you choose “**Load latest**” or “**Keep my edits**”.

Where in the UI The top of the editor > “Check settings”, “Apply changes”

### Going back to a previous version

**An applied definition is kept as a version.** On the Overview tab, under “Project info” > “Show All” > “Versions”, you can see what changed in each version. **An owner can return the step settings to an earlier version.** What returns is only the settings of steps that still exist: the step settings of that version are loaded into the draft and the editor opens. Save with “Apply changes”. You can go back to an active version or a rejected one. If there is no difference from the current step settings, a notice says so and nothing is loaded.

Where in the UI Overview tab > “Project info” > “Show All” > “Versions” > select a version > “Restore this version” (in the wide-screen editor)

## Easy to get wrong

- **Thinking the arrangement of a cycle's steps is the order of execution.** Placements run on their own periods
- **Thinking the previous step's output is passed to the next step automatically.** It is passed only when you connect files
- **Thinking the output of an agent on the same step is passed to the next agent automatically.** Only the files you connect are passed
- **Thinking it always retries automatically on failure.** An agent whose effect on external systems is “Writes (retry may duplicate)” is not retried; a review request is made
- **Thinking you can change an agent's behavior in the project.** What you can change is only the per-step settings

## What to read next

- [Projects and Steps](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/concepts/project-and-steps.md) — How steps and placements are thought of
- [Agent Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/agent-guide.md) — Place registered agents
- [Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/review-guide.md) — How to put in a person's judgment
- [Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/trigger-guide.md) — When to run and how to stop
