# Design Guide

Creating one project means settling on one way of carrying out a piece of work. This guide covers the choices and the criteria for deciding **what to settle for the work, how to divide it into steps, and what to put on each of them.**

What steps and agents are is covered in [Projects and steps](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/concepts/project-and-steps.md). Reading that first will make the decisions here quicker.

**Where a section has a place on screen**, you will find **where to set or check** what it asks you to decide at the end of it. Steps and agents are configured on the screen you reach through **Edit** at the top of the project screen (shown to owners only). That screen has “**Editing tools**” (for adding steps and agents) and a list (**Agents** / **Steps**) on the left, a diagram of the whole thing in the middle (“**Editing canvas**”), and the settings for whatever you selected on the right (“**Properties**”). Where the "Where on screen" lines below say "Edit ＞ …", that screen is what they mean. The diagram in the middle can be shrunk with “**Display size**”, and pressing and dragging an empty spot with the mouse moves the view.

## What to settle for the work

**Before deciding the type, the steps and the agents, settle four things about the work.**

- **How much to hand over.** There are three clues. **Can a mistake be undone?** Before an operation that cannot be undone, such as writing to an outside system, put a review step or block it with the execution rules ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md)). To have a person check before a connector is used, set “Confirm before connecting” on the connector ([Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/connection-guide.md#asking-a-person-before-use-connection-confirmation)). **Can the criteria for the judgement be written down?** The criteria an agent judges by go into its goal or a skill; a judgement that cannot be put into words stays with a person. **Can the information it needs be reached?** List the information needed and what to connect to, and check that it can be used before you start building ([Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/connection-guide.md))
- **What has to be true for it to be done.** Settle first when the work is done, then break it down into each agent's goal ([later section](#start-by-settling-the-goal)) and the criteria a reviewer uses to decide whether to advance. How to read a run's result is in [Records and metrics](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/concepts/records-and-metrics.md)
- **Where to divide projects.** Work that differs in who may see it, which authentication it uses, which operations it allows, or which project memory must not be mixed goes into separate projects. Note that projects of the same organization, even when divided, show their definition and state to people with the organization operations role for that organization (they cannot see run outputs or files). What is decided per project is in [Projects and steps](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/concepts/project-and-steps.md)
- **Where the results go.** If a person receives them, put a review step at the end of the workflow ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md)). To get them back into a business system, add the destination as a connector and write into the agent's goal what to write, where, and how. The same goes for a run started from the external API ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md#starting-it-from-outside))

For applications, “Check the contents” is handed over and a person approves before “Register it and reply”. Done means “the entries and attachments are complete, it has been checked against its requirements, it is registered, and the applicant has had the result”. If the system that receives applications differs by department, the projects are divided.

## Choosing the type

The first thing to settle is the type. **It cannot be changed afterwards.**

|               | Cycle                                               | Workflow                                         |
| ------------- | --------------------------------------------------- | ------------------------------------------------ |
| How it ends   | No start and no end; it continues                   | It runs from a start to an end, step by step     |
| How it runs   | Each placement runs on its own schedule             | One single run goes through the steps in order   |
| How it starts | The schedule on each placement, a webhook, or email | By hand, at a time, through the API, or by email |

**The criterion is whether there is an end.**

If the work **starts and finishes one item at a time**, use a workflow. It has a beginning and an end, so you can follow each run. **A workflow is also the only type where a review step can hold the run itself, for certain** (a cycle holds one subject at a time).

If it **has no end and simply keeps going**, use a cycle. The placements run on their own schedules, and there is no start or finish to the whole.

For which one suits your work, see also [Examples of work each suits](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project.md#the-two-types) on the section entry page.

**The type decides which of the sections below apply to you.** Settings that assume the work moves through the steps in order — what to do when it does not go to plan — belong to workflows only.

Where on screen When you create a project ＞ Type

## Dividing the work into steps

**How you divide the work differs by type, right down to the thinking behind it.**

|                     | Workflow                                                                                     | Cycle                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Work it suits       | Taking one item and carrying it through to the end in a set order                            | Going on looking for subjects and doing whatever they call for                               |
| How it proceeds     | **The arrangement of the steps is the order.** A step begins after the previous one finishes | Each placement runs on its own schedule, independently. **The arrangement is not the order** |
| How stages join up  | **The platform hands the work over**                                                         | **The next stage picks up what was left in a shared record**                                 |
| A person's decision | **Holds the run itself, for certain, at a review step**                                      | **Holds one subject. The other rounds carry on**                                             |

**With “Build it myself”, you enter the type, name and tags to create a project.** Steps and agents are set in the editor afterwards.

If you create a project without specifying the steps, a workflow gets **run → a person reviews → run** and a cycle gets **run → run**, because **a cycle cannot have a review step**. If you had the AI (alpha) draft it, or copied another project, you get the steps that came with it.

**There are no product-imposed rules about the names of steps.** Name them to suit the work. **Nothing progresses differently because of a name**, but **the step's name is passed to the agent as context and appears in the records**. There is an upper limit on the number of steps ([Settings reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/settings-ref.md)).

**There is no rule that sets the number of steps from the amount of work**, and this holds whichever type you chose. When a single run does not finish reliably, **narrow what one run takes on in the goal, or split the agents and placements**. Adding steps is not necessarily the answer.

### Dividing in a workflow

A workflow is the type for **taking one item and carrying it through**. The arrangement of the steps is the order the work is done in, and a step begins after the previous one finishes. A Branch step passes only through the chosen lane (or through no lane when “Join directly” is chosen), and the destination options chosen at a review can skip the steps in between and go on to a later step.

Take, for instance, a workflow that handles applications as they come in, one at a time.

1. **Check the contents** — see whether the application and its attachments are complete
2. **A person approves** — the reviewer looks at it and decides whether to advance or send it back
3. **Register it and reply** — register what was approved and send the result to the applicant

**One item goes 1 → 2 → 3, and it is finished.** If it is sent back at 2, it returns to 1 and is redone.

**Divide where you want to mark off the progression.** In this example the seams fall either side of "a person approves". A seam you create there can carry any of the following.

- **A person deciding in between** → put a review step there. **The run stops there**, and from then on it proceeds either on the reviewer's decision or **on the setting for what happens once the deadline passes** ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md))
- **Somewhere for a send-back to land** → where a redo starts from is given per step ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md))
- **Letting a person choose where to go** → put “Destination options” on a review step, and the reviewer chooses a later step to proceed to ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md#what-happens-after-the-decision))
- **Waiting for a time** → a step can hold a time of its own; leave it unset and the step runs as soon as the previous one finishes ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md))
- **Changing what happens when it does not go to plan** → chosen per step (see [below](#what-to-do-when-it-does-not-go-to-plan-workflows))
- **Taking part of it out of the run for a while** → steps can be enabled and disabled one at a time. **A disabled step is not held at; it is skipped and the run moves on** (in a cycle, the placements on a disabled step take no new starts; see the [Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md#running-a-cycle))

**When you split the work between agents, decide by whether one result must feed the next.** Several agents can share one step, but **agents on the same step do not pass their output to each other**. If an agent is to carry on from another agent's result, divide the steps. Work that does not use each other's results can share one step. **The behaviour on failure changes too** — retries are counted for each agent placed on the step. How many to place on a step is covered [later](#placing-agents-on-steps).

**One run's flow can also be split partway** (to pick one lane by a condition, see [Branch](#external-automation-and-branch-steps-workflows) below). Choose “**Split into lanes here**” after a step, and from there the run divides into **2 to 11 lanes** that go forward at the same time, **joining again once every lane has finished**. In the application example, after “Check the contents” you could check the entries and the attachments in separate lanes, and go on to “A person approves” once both are done.

- **There is only one split.** A lane cannot split again
- **Within a lane, steps run from top to bottom.** Lanes do not wait for each other. When a lane waits for a review, only that lane stops; the other lanes go on and wait at the join
- **The step the lanes split from cannot be set to “Run at the same time”**
- **Steps to send back to, and the destinations in the sections below, are chosen from the same parallel lane.** Outside the parallel lanes, they are chosen from the same side of the split — before it, or after the join

### Dividing in a cycle

A cycle is the type for **going on looking for subjects**. Each agent starts on its own trigger, independently, and **does not wait for the other steps to finish**. So if one stalls, the rest keep running. Where there is nothing to act on, it ends that round without doing anything and looks again on its next round.

**A single stage is fine.** Looking at something at a set interval and acting if needed — for that alone, you do not need to divide the stages. Created without specifying the steps, you get two, but **you can delete the one you do not use and keep just one**.

**A cycle's steps are categories of responsibility.** They sit around a circle in the diagram, but **they carry no numbers or arrows, and there is no reordering**. If you want them to proceed in order, that is what a workflow is for.

Take, for instance, a cycle that gives a first response to incoming enquiries.

- **Find them** — look for enquiries that have newly arrived
- **Sort them** — read them and separate the ones a standard reply covers from the ones a person should see
- **Draft a reply** — prepare a draft for the standard ones
- **Check it** — before it goes out, see whether the draft fits the enquiry

**Enquiries keep arriving, so there is no end to it.** Each stage goes round at its own interval.

**Divide where the handling of the subject changes.** In this example each stage picks up something different. "Find them" takes what has not been dealt with; "sort them" takes what has been found; "draft a reply" takes what was judged standard — **what the previous stage left behind decides what the next one takes.** That is where the boundary falls.

Once you have the stages, **stagger the times they start.** Set them all to the same time and a stage **can run** before the previous one has left anything, and come up empty. Staggering the times **puts the opportunities to run in an order** ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md)). It is no guarantee, though, **that the previous stage has finished**. What each one picks up is settled not by the time but by **the marks on the record** (see the next section). **The schedule belongs not to the step but to each placement on it.**

**Agents handling the same stage can share a step even when their schedules differ.** How many to place, and how the same agent is treated, are covered [later](#placing-agents-on-steps).

### Joining the stages of a cycle

The stages of a cycle do not wait for one another, so **the hand-over is expressed through a shared record.** Combine these two.

- **A shared record** — mark a connector “Use as ledger” ([Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/connection-guide.md))
- **Rules for reading and writing** — set out how each agent picks its subject and updates it, in its goal or a skill

**Marking a connector “Use as ledger” does not by itself make anything read or written.** What you do is have each stage **change a mark** on the record you settled on above. For the enquiry example from the previous section, that looks like this.

- The **find them** agent — marks each enquiry it picks up as **being checked**
- The **sort them** agent — looks only at what is marked as being checked, and changes the mark to **standard** or **for a person**
- The **draft a reply** agent — takes only what is marked standard, and changes the mark to **drafted** when it is done
- The **check it** agent — looks only at what is marked drafted, and changes the mark to **checked** where there is nothing wrong

**Each agent's goal says what it takes and how it changes the mark when it is done.** Use whatever form the record supports for the marks — a column, a label, either is fine. The record then serves as the hand-over between the stages.

**When the same agent runs over and over, that is expressed the same way too.** **The platform keeps no list of what has already been dealt with.** So a goal that **picks its subject by the difference from last time** — “what I have not checked yet”, “what I have not looked at for a while” — can end up picking the same subject every time. **Leave a mark on what is done, and have the next round leave anything carrying that mark alone** — express the difference from last time in the record as well.

**A person's decision is expressed the same way.** Give the agent's goal an option of handing something to a person, and have it leave a different mark when it does. Tell the other agents, in their goals, to leave anything carrying that mark alone, and **that one subject waits on a person** while the rounds over everything else carry on. Once a person has decided, outside the product, and changed the mark, it starts moving again.

Here is where the two types differ. **A workflow holds the run itself, for certain; a cycle holds one subject at a time.** If what you need held is the whole run, choose a workflow. A hold built out of instructions is **not something the platform guarantees**, so where it absolutely must not be bypassed, use a mechanism on the connector or API side.

> **A cycle cannot have a review step**
>
> You cannot add a review step to a cycle. A person's decision goes in through the marks described above. Confirm before connecting (a connection confirmation) works in a cycle too ([Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/connection-guide.md#asking-a-person-before-use-connection-confirmation)).

Where on screen Edit ＞ “Editing tools” on the left ＞ “Add step” (in a workflow, then choose “Regular step”). In a workflow you can also use “+” between steps in the diagram in the middle ＞ “Run by Agent”. Select a step in the diagram in the middle and the settings for it appear on the right. **In a workflow** you can reorder them in that diagram (a cycle has no reordering). For the shared record, the Settings tab ＞ “Connectors (MCP, A2A)” ＞ the connector ＞ the “Ledger” switch. To split, right-click a step in the diagram in the middle ＞ “Split into lanes here”. Adding a lane and stopping the split are in the split's box in the diagram. To move a step to another lane, “Step settings” (“Review settings” for a review step) on the right ＞ “Trigger” ＞ “Lane”. Values and file roles passed to the next step: select a “Run by Agent” step of a workflow and use “Values and file roles passed to the next step” (“Values for the next step”, “File roles”) on the right

## External automation and Branch steps (workflows)

**An External automation step sends once to a destination you choose, without going through an agent.** It is for things such as waking up the intake of another in-house system. No agent can be placed on it, and it cannot have a review, a time, destination options, “Run at the same time” or a send-back target.

**The destination** is chosen from those your administrator has registered in the admin console (the URL is not shown). With no destination, or a disabled one, it cannot be saved or started. While DLP integration is on, an External automation step cannot be saved or started either.

**What is sent** is written in “Body shape (JSON)” as a JSON object (up to 16 KB, nested up to 16 levels). Inside string values you can insert the previous step's output (the full text, up to 20,000 characters) and its summary, the run ID, this step's ID and name, the project's ID and name, the subject and body of the start input, and the idempotency key (the same value on a retry). A body with a placeholder that cannot be used cannot be saved. **The timeout** is 1 to 300 seconds (60 by default).

**What happens to the result:** once the destination accepts it (an HTTP status of 2xx), the run goes to the next step. It does not check whether the outside process finishes. A refusal, a timeout, or a failure to connect fails the step. Of these, 5xx, 408, 429, a timeout and a failure to connect are sent again according to the project's retry setting, and the run ends as failed once they are used up.

**How to check:** the run record keeps the destination name, the HTTP status, the time taken and a digest (SHA-256) of the body sent, and the Records (audit trail) keep “External automation called”. The destination's reply body is not kept. Before saving, “Check settings” shows a destination that is not chosen or is disabled.

**When copied:** when someone who does not take part in the original project copies it (for example, copying a public project), the External automation step comes across, but its destination and what it sends do not; set them again. When someone who takes part in the original project (an owner, an operator or a member) copies it, they carry over.

**A Branch step reads the result of the previous step and decides which lane to go to.** Below the Branch step sit its **lanes** (each lane holds at least one step; there are up to 12 steps in all, so there can be up to 11 lanes). For each condition, you choose where to go when it matches: a lane, or “**Join directly**” (skip every lane and continue after the join). When a lane is chosen, only the steps in that lane run, from top to bottom, and the run then continues with the step after the join; the steps in the other lanes are not run (the run record shows “Not selected in the branch”). It uses no agent and no time can be set. It cannot have a review, a time, destination options, outcome handling, a send-back target or “Run at the same time”.

**How to split** is set in “Conditions” (up to 8). A condition pairs **what to check** (the result text, the result JSON, output files, the step's run, or a question), a **rule** (a value and a comparison) and **the lane to go to** (a lane, or “Join directly”). Examples: the result text contains a word; a JSON item equals a value (or is at least/at most); an output file exists (by type, name or count); the processing time is at least some minutes; the number of times it was sent back to this step; a write operation happened; the agent reported “no change was needed”. A “question” takes a yes/no question; a model that only judges reads the beginning of the previous step's output and answers, and yes counts as a match (the contents of files are not passed. Where it cannot be used in this environment, it cannot be chosen).

**Conditions higher up win**: they are checked from the top, and the run goes where the first matching condition points (a lane, or Join directly). If no condition matches, “When no condition matches” decides: **Join directly** (the default), **Go to a lane**, or **Let a person choose**.

**Asking a person:** with “Let a person choose”, a review request is created and the reviewer chooses the lane to go to or “Join directly” (the options are the lanes that have an enabled step, and “Join directly”). It is not decided automatically even when the deadline comes.

**Place the lane steps right after the Branch step, one lane after another.** A Branch step cannot be placed inside a lane. A Branch step and its lanes are placed outside parallel lanes. The step the parallel lanes split from cannot be a Branch step or one of its lane steps, and a Branch step's lane step cannot come right after a join (the Branch step itself can). A lane step can be chosen as a send-back target or destination only from steps in the same lane (from a lane step, steps outside the lane can also be chosen). A run cannot be started from a step inside a lane.

**A lane step does not receive the outputs of other lanes.** The steps after the join do not receive the outputs of lanes that were not taken either.

**Try it:** under “Try it” in the editor, enter a sample output of the previous step and the names of output files, and press “Check rows”, to see which condition matches and which lane it goes to (including joining directly or letting a person choose) (nothing is saved; the rules on processing time, the number of send-backs, writes and reports do not match when trying). The run record keeps which condition decided it (or that a person was asked), and the Records (audit trail) keep “Branch decided” and “Branch asked a person”.

Where on screen Edit ＞ “Editing tools” on the left ＞ “Add step” ＞ “External automation”, “Branch”. For External automation, select the step and use “External automation settings” on the right. For Branch, “Lanes”, “Conditions”, “When no condition matches” and “Try it” on the right. Add a lane with “+ Lane” beside the Branch step in the diagram in the middle, and add steps with “Add a step to (lane name)” in the lane (adding and removing lanes is done in the editor on a wider screen)

## What to give an agent

**Only two things are required: a name and a goal (instructions).** Guardrails, a playbook and skills are **added only where you need them**.

### Start by settling the goal

The goal says **what the subject is, what to do with it, and what state it should be left in**. This is the heart of the agent.

**Writing a goal does not, on its own, put anything external within reach, though.** In a cycle especially, write **where the work is to be found** into the goal, and **add the services it needs to the project's connectors** ([Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/connection-guide.md)). For the enquiry example from the previous section, the goal goes as far as "look for unhandled enquiries in the connector".

**For an agent that writes outside, also write that it should check whether it has already written before writing.** The same agent may run again (for a workflow see the [later section](#what-to-do-when-it-does-not-go-to-plan-workflows), for a cycle the [previous section](#joining-the-stages-of-a-cycle)). For “Register it and reply” in applications, write “if the same application is already registered, do not register it again”.

**Where “Personal information masking” is enabled under “Guardrails Settings” in the admin console, a step's instructions, like a conversation, have personal information masked before they reach the agent.** That covers the output of the previous step, and the subject and body of an email or the body of a webhook received. **Names and addresses that appear in instructions written by people (the agent's goal, reviewers' comments and reasons for sending back) are not masked, though, as they were written as the subject of the work.** The same strings are not masked where they also appear elsewhere, such as in the previous step's output. Terms registered as “Sensitive terms” in the admin console are still masked.

### Add only what you need

- **If there is behaviour you want it to steer clear of, guardrails.** For the enquiry example: "do not send the reply yourself", "do not touch amounts or contract terms". Mixing "do not do this" into the goal makes the account of what to do harder to read. **Be aware, though, that guardrails are instructions to the agent. Writing something there does not reliably stop an operation.** Operations you need stopped for certain are settled in the execution rules ([Execution Rules Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/control-guide.md))
- **If there is a set procedure you use again and again, a playbook.** For when you want the **draft a reply** agent to go through the same run of steps every time — "**find similar past enquiries → choose the form of the answer → write the draft → attach the articles it drew on**". Set out each step with its purpose, guidance and success criteria and the agent works through them. **The steps you write are not simply repeated, though.** The agent adjusts them to suit the request. To hold an order in a workflow, do not reach for a playbook — **divide the work into steps** instead
- **If you want it to hold the method for one particular piece of work, a skill.** Make **"how you classify enquiries"** a skill, for instance: the table mapping your product names to categories, the order of precedence when a judgement is close, examples you have got wrong in the past — **a method your organisation has settled on**, written down for the **sort them** agent to follow. Setting it out separately rather than repeating it in every goal lets **several agents work to the same standard**. "The form a reply should take" and "when to escalate" suit a skill as well. **A skill does not grant any permission on an external service** (what it can reach is settled by the connectors). In a cycle, **what the agent finds to work on** is settled by its goal, its skills and its connectors

You can also add a description and input files. Input files are chosen from your own library and are used wherever the agent is placed. To hand files shared among the project's members to a particular step, use the project library ([later section](#handing-project-library-files-to-an-agent)). The list of items is in the [Settings reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/settings-ref.md).

> **Agents are shared across projects**
>
> **A change to an agent's settings reaches every project that uses it.** A small change meant for one project changes how the others behave too. If you want different behaviour per project, use separate agents.
>
> When handing over, have the successor prepare agents they own and put those in place (how an agent's owner differs from the project's owner is in [Who decides what](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/concepts/roles.md)). When an agent's owner has left or been disabled, a system administrator can transfer its ownership with “Ownership handover” in the admin console.
>
> The card of an agent you own shows the projects where it is placed, as “**Placed in**” (“Not placed” where it is nowhere). Check how far a change will reach before you make it.

Where on screen Edit ＞ select the agent placed on the step in question, in the diagram in the middle, then “Agent on this step” on the right ＞ “Basic settings” ＞ “Edit Agent” ＞ “Goal (instructions)”. “Edit Agent” appears only to the agent's owner

## Placing agents on steps

Each single agent placed on a step is a **placement**. **Runs happen at the level of the placement.**

### How many to place on one step

**Where one agent can carry the whole step, leave it at one.** Placing several lets you do the following, according to the type.

**Placing several in a workflow lets you give separate jobs within the one step.** By default they run one at a time, in placement order. Set the step to “**Run at the same time**” and they run together. This suits work that does not wait on each other. Either way, **agents on the same step do not pass their output to each other**. Each works from the output of the previous step. On "Check the contents" in the application example, you can place **an agent that looks for anything missing** alongside **an agent that checks the application against its requirements**. Once every agent placed there has finished, the run moves to the next step, and **the next step receives all of their output**. If one agent is to carry on from another agent's result, divide the steps (see the next section).

**On a step set to “Run at the same time”, each agent whose result is “Not allowed by rules” or “Failed (reported by agent)” follows “Handling of results” on its own** (see [below](#what-to-do-when-it-does-not-go-to-plan-workflows)). Where that means asking for a review, a review request is raised for that agent, and the other agents carry on. **The run does not move to the next step until all of their results are in**. Where the agents point to different next steps, a review request is raised to choose where to continue. Send back a review request on this step, and the run redoes the work from the step it goes back to without waiting for the other agents. The results of agents that were still working, and decisions on the other review requests of that round, stay in the record but are not used to move on.

**Placing several in a cycle lets you divide one stage into rounds that differ in what they look for, or in how.** Each placement runs without waiting for the others. On "Find them" in the enquiry example, you can place **an agent that looks through the mail for anything unanswered** alongside **an agent that looks through the form for the same**. Placing several, however, **settles neither how the subjects are divided between them nor how duplication is avoided.** Which of them takes which is settled by the shared record and each agent's goal (see [above](#joining-the-stages-of-a-cycle)).

### What is handed over in a workflow

**What a workflow hands over automatically is the output of every agent on the previous step, and the files each of them produced.** Files saved in the Library reach the agents on the next step as input files. Where the previous step has several agents, their outputs arrive one after another, agent by agent. The output is the agent's last answer, and up to 20,000 characters of each is handed over (40,000 characters in total when several arrive). Anything beyond that is cut off, with a note that it was cut and how long the whole was, so have a longer result written to a file. **The previous step's output is handed over as data, not as instructions.** It is wrapped in a boundary that changes with every start, with a note to treat it as data, so that even when the previous step summarised something from outside, it is not taken as an instruction to the next step.

**Named values and files with roles can be handed over too.** Set “**Values and file roles passed to the next step**” on a “Run by Agent” step, and the agent on that step is asked to return values under the names you chose (text) and which output file is the file for which role; they are handed to the agents on the next step with their names and roles. They travel with the previous step's output, so they reach the same place as that output. Up to 5 values and 3 roles (names up to 40 characters, descriptions up to 200), and each value up to 1,000 characters; anything beyond that is cut off. A value the agent did not return, or a file not found among the output files, is not guessed; the next step is told that it did not arrive. **The values are not used for branch rules or for whether the run succeeded.** Cycles do not have this.

There are three things to watch for.

- **Nothing is handed over between agents on the same step.** Line two up on one step and the second does not receive the first one's output or new files; both receive what came from the previous step. **When they run in placement order, though, if the first rewrites a file that came from the previous step, it is the same file, so the second reads the rewritten version**. Agents on a step set to “Run at the same time”, and the lanes, are also handed the same files, so do not have them rewrite the same file at the same time
- **Only the last step where agents ran is handed over.** A review step is skipped, and what arrives is from the step before it. **What came from two or more steps back is not handed over automatically**. With lanes, the first step of each lane receives what came from the last step before the split where agents ran. **The first agent step after the join receives the last of each lane (outputs and files)**. When more than one output arrives, each is labelled with its lane name and step name (a single output is not, and files are not)
- **The exchange along the way is not handed over.** What an agent found while looking does not carry across

So **where an agent on a later step needs to see what was produced two or more steps back, have it saved to a shared record** ([Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/connection-guide.md)). The project library can do this too: sync the files the agents on each step write with the library, and sync the same files on the placement of the agent that reads them ([below](#handing-project-library-files-to-an-agent)). Where the previous step's output and files are enough to carry on from, lining them up is fine.

**A cycle has no such automatic hand-over.** How its stages join up is expressed through a shared record, as [above](#joining-the-stages-of-a-cycle).

### Placing one agent on several steps

**The same agent can be placed on several steps.** An agent is a setting you reuse, so you get one placement for each step you put it on.

- **In a workflow, placing the same agent on consecutive steps still runs it on each step.** On the later step, as on any other step, it receives the output of the previous step together with the files produced and saved in the Library ([Projects and steps](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/concepts/project-and-steps.md))
- **To run the same agent on two schedules in a cycle, divide the steps.** The same agent cannot be placed on one step twice

In a cycle, the schedule belongs to the placement rather than the agent. Setting it is covered in the [Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md).

### Handing project library files to an agent

**An agent placed on a step can be handed files from the project library.** The project library is the place for files shared among the project's members, on the project's “Library” tab. It is settled per placement, apart from the agent's input files (chosen from your own library and used wherever the agent is placed).

- **Registering** — on the “Library” tab, upload a file, choose one “From my library”, or use “Register to the project library” on an artifact in a run record. What you choose from your own library is registered as a copy as of that moment. A file with the same name cannot be registered, so for a file already there open “Manage versions” on its row and use “Upload a new version”. A new version must be the same type of file (extension) as the original. You can select up to 20 files at once when uploading. An artifact in a run record whose name is already in the library can be added with “Add as a new version of "(file name)"” ([Record Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/record-guide.md#reading-a-single-run)). If the content is the same, no version is added
- **Following the versions** — “Manage versions” on a file's row shows when, and by whom (or by which run), each version was written, and lets you download each version. From a version a run wrote, “View execution record” goes to that run record. “Make this the latest version” saves an earlier version's content as the new latest version (the current latest version stays in the history)
- **Deleting** — it is unregistered and can no longer be downloaded. The versions are kept, but cannot be opened from the screen

**The files to hand over are chosen, and given a name in the workspace, under “Files synced with the library” on the placed agent's “Resources” tab.** At every start, the latest version is put in the agent's workspace under that name. **If the agent rewrites the file of that name, it is saved as a new version of the same file in the library.** The next start is handed that version. “**Save to the library under this name every run**” on an artifact in a run record sets up the same link in one go (owners only; it is saved there and then, not through the editor's draft). Writing “Write the result to (name in the workspace)” in the agent's goal makes this reliable. Workflows and cycles work the same way.

- The name is a file name only; folders cannot be given. Names starting with “.”, and names such as .log, .tmp, .swp and .pyc, are not picked up as artifacts of a run, so they cannot be used
- The files you choose go into the draft, and are saved with “Apply changes”
- A file deleted from the library by the time of the start is not handed over. If a deleted file is still chosen, “Check settings” shows it as an issue to fix

**Members can register files, add new versions and go back to an earlier version.** Deleting, and choosing the files to sync, are for owners only. Registering (uploading) files and adding new versions, however, are not possible for people the administrator has not allowed “File attachment” under feature permissions. When a member adds a new version, the agent is handed that version from its next start. Who wrote which version can be traced in “Manage versions” and in the Records (audit trail) CSV ([Records reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/events-ref.md#the-records-audit-trail-csv)).

Where on screen Edit ＞ place from “Agents” in the list on the left into the diagram in the middle. Or select the step in the diagram, then “Step settings” on the right ＞ “Add Agent” (in a workflow, on the “Basic settings” tab). To take one off, press × (“Remove from step”) in the same list, or “Remove from step” at the bottom of the right-hand panel when the placed agent is selected. To run them together, select the step in the diagram in the middle, then “Step settings” on the right ＞ “Trigger” ＞ “Run at the same time” (it can be switched once two or more agents are placed). The company memory to read is under “Agent on this step” on the right ＞ “Basic settings” ＞ “Company memory” when the placed agent is selected. What you choose goes into the draft, and is saved with “Apply changes”. The files to hand over are under “Agent on this step” on the right ＞ “Resources” ＞ “Files synced with the library” when the placed agent is selected. Registering files and their versions are on the project's “Library” tab

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

A step can be told what to do in two situations where it did not end as intended. Both are chosen per step. **Both of them apply to workflows.** A cycle does not move through the steps in order, so it does not use them.

**“When not allowed by rules”** lets you choose from “Ask for review (awaiting review)”, “Close as failed” and “Go to a specific step”. This is when the platform forbade the run itself.

- **Ask for review (awaiting review)** — the work stops where it is and **a review request is raised for the owners** (such a step has no field for naming reviewers, so every owner at that moment becomes a reviewer. However, on a step switched from a review step to “Run by Agent”, the reviewers named while it was a review step become the reviewers, if they are still members). The run goes to awaiting review, and proceeds from there either **on the reviewer's decision or on the setting for what happens once the deadline passes** ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md))
- **Close as failed** — **the run itself ends**. No review request is raised, and **no later agent or step runs**
- **Go to a specific step** — no review request is raised, and the run goes to the later step chosen as the “**Destination step**”. The steps in between are not run (the run record shows them as “Not selected in the branch”). On a step that runs in placement order, agents on the same step that have not run yet do not run. On a step set to “Run at the same time”, the other agents are already running, so they are not stopped, and the destination is settled once their results are in. The output and files of the agent whose result led to the destination are not handed over to the destination step. Where the destination step was disabled before the run started, it behaves as “Ask for review”

**Asking for a review is the default.** As a rule of thumb: ask for a review if revisiting the settings might let it through, and close it if not. The execution rules themselves are covered in the [Execution Rules Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/control-guide.md).

**“When the agent reports it could not finish”** lets you choose from “Ask for review”, “Proceed anyway” and “Go to a specific step”. This is when the agent has itself reported that it could not complete the work, or said so in its final result. When the agent wrapped up at the run time limit and could not finish, this does not apply; it is handled as a timeout on the platform's side (next paragraphs).

- **Ask for review** — as above, **a review request is raised for the owners**. The run goes to awaiting review
- **Proceed anyway** — no review request is raised, and **the run moves on to the next agent on the same step if there is one, and to the next step if there is not** (on a step set to “Run at the same time”, it moves to the next step once the other agents' results are in)
- **Go to a specific step** — as above

**Here too, asking for a review is the default.**

**When a run stops for a connection confirmation** (the result is “Failed (reported by agent)” and the reason is “Stopped for connection confirmation”), this setting is not followed; a connection confirmation review request is raised instead. The setting is followed when it is rejected and when its wait limit passes ([Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/connection-guide.md#asking-a-person-before-use-connection-confirmation)).

Choose “Proceed anyway” when **the agents on later steps do not use this agent's output**. If they take that output and carry on from it, stopping for a review is the safer choice. Note that **when there was nothing to act on and the run never started, it moves on regardless of this setting.**

**In neither case is anything retried automatically.** Running it again risks writing to the outside world twice. Whether to run it again is for a person to decide, once they have looked at the situation.

**A failure on the platform's side — an abnormality in the runtime, or a timeout (including when the agent wrapped up at the run time limit and could not finish) — is retried automatically.** The limit on the number of retries is set for the project as a whole and **counted for each agent placed on the step, each time the run enters that step** (when a send-back brings the run back to that step, the count starts over). Once it is exceeded, that run ends as a failure (for the permitted range, see the [Settings reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/settings-ref.md)). **When something has been retried, the run record says “Attempt 2”.** A retry does not carry on from where it stopped; the agent on that step runs again from the beginning.

**When setting things right, decide whether to start a new run, or, if it is waiting for review, send it back to redo from a step partway through, or, if it closed with a rejection or a failure, resume it from a chosen step ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md#resuming-a-closed-run)).** What to check first is in the [Record Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/record-guide.md), and how operations already carried out are treated is in the [Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md).

Where on screen Edit ＞ select the step in question in the diagram in the middle, then “Step settings” on the right ＞ “Trigger” ＞ “Handling of results”. The number of retries is under the Settings tab ＞ “Execution rules” ＞ “Execution” ＞ “Retries per step (failed / timed out)”

## Publishing and reuse

Playbooks, skills, agents and projects can each be published. **How you reuse them differs.**

|              | How you use a published one                        | When the author changes it later                                                                                                                                  |
| ------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Skill**    | Can be used as it is                               | **It reaches you if you “Follow the latest version”** (after approval, in a tenant where publishing requires administrator approval); not if you pinned a version |
| **Playbook** | Copy it to your own library first                  | Copies are unaffected                                                                                                                                             |
| **Agent**    | Placing it on a step copies it to your own library | Copies are unaffected                                                                                                                                             |

**A published agent is copied to your own library the moment you place it on a step.** From then on it is yours, so you can edit it — but **anything the author changes afterwards does not come through**. To take a later version, place it again.

For playbooks, **only your own appear** in the choices for an agent. To use a published one, copy it to your own library first.

**Skills are the one case where you use the published item itself and the author's updates do come through.** They behave differently from the other two, so keep it in mind. When the author changes it, a new version is made, and an agent set to “**Follow the latest version**” uses the new version from its next run. When the tenant requires administrator approval for publishing, the new version is not used until an administrator approves it; until then, the previous version stays. If you do not want changes to come through, pin the version the agent uses. For another person's skill, you can pin only versions that were published while the skill was published.

**In some tenants, publishing skills and playbooks requires administrator approval.** A system administrator settles this for skills and for playbooks separately, under “Share requests” in the admin console (the default is no approval). While approval is required, “Share” becomes “**Request publishing**” (a reason is optional), and other users cannot see it until an administrator approves it in the admin console (which administrators can approve is in the [Roles reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/roles-ref.md#settled-for-the-whole-tenant)).

- While it is waiting, it shows “**Awaiting publishing approval**”. To withdraw, press “**Withdraw request**”
- If it is returned, it shows “**Returned by an administrator**” with the reason. Fix the content and press “**Request again**”
- Editing a published playbook is the same where publishing requires approval: the change waits for approval, and until then the approved content stays published
- When you change a public skill, the new version shows “**New version awaiting approval**”, and the current version stays public until it is approved
- What was published before approval became required stays public. An administrator may also stop publishing it

**When you publish a project**, other users can copy its steps and agents and use them. Its run records and ledgers are not published.

**When you create a project, you can also start from one that already exists.** Choose “**Create from an existing project**” under “How do you want to create it?” and pick one project you take part in (as an owner, an operator or a member) or one public project; a new project copied from it is made, and you are taken to its screen. Whoever copies it becomes its owner. A project an administrator has stopped, or a project that uses an agent an administrator has stopped, cannot be copied (“An administrator stopped this, so you can't do that. Ask an administrator to resume it” is shown). Fix the steps and agents in the editor after it is created. It is copied the same way as with “Duplicate” on the project screen and on the card in the list (shown to owners only). Where definition changes need approval in the tenant, the first definition of the copy waits for approval, and the project cannot run until it is approved. The other ways to create are “Build it myself”, “Create from a company template”, “Import from file”, “Create through consultation” and “Guided setup”.

On a project you copied, **check the following.**

- **Connectors** — the list carries over (and so do the “Ledger” marks and the “Confirm before connecting” settings). **The connection (authentication) does not**, so connect them again in the copied project
- **Playbooks, skills and input files** — the playbooks and skills used by other people's agents are **duplicated into your library and attached** (your own skills, and skills that are public and active, are used as they are). For a kind whose publishing requires administrator approval (skills, playbooks), those of other people that are not published are not duplicated but left off, and the names of the agents affected are shown. Of the input files, **only those not in your library are removed**
- **Additional instructions for this project** — each placement's “Additional instructions for this project” are copied
- **The review settings, a step's time, and the failure settings** — they are not copied. **The steps themselves and the send-back targets do carry over** (and so do “Run at the same time” and the lanes). The lanes and conditions of a Branch step carry over, with the lane steps re-pointed to the copied steps (a step that cannot be copied leaves its lane, and a lane left empty and the conditions that go to it are removed). The settings of an External automation step carry over only when someone who takes part in the original project (an owner, an operator or a member) copies it
- **The trigger settings** — a time trigger is copied but **arrives switched off**. A cycle's rounds do not carry their schedules over. The “Start by email” settings (the address, the allowed email addresses and, for a cycle, the placement to start) are not copied either; turning it on in the copied project creates that project's own address
- **The organization and the company memory choices** — they are not copied. Set the organization on the copy if needed, and choose the company memory again for each agent
- **The project library** — the files are not copied. A placement's “Files synced with the library” is not carried over and arrives empty. Register the files in the copied project's library and choose them again
- **Default contact when overdue** — it is not copied

**Duplicating your own project does not divide the agents.** Your own agents are placed, as the same agents, in the duplicated project. Edit an agent in the duplicate and the original project changes as well.

## Exporting, importing and sharing as a company template

A project's definition (steps, agents, triggers and connectors) can be saved to a file and taken to another environment, or published as a company template. Both start from “How do you want to create it?” when you create a project.

**Only an owner can export.** Press “Export” under “Export definition” on the Settings tab, and the confirmed definition is saved as a JSON file (`<project name>.definition.json`). Even where approval is required, what is exported is the approved definition. The export is recorded. **Connections, secrets, reviewers, the overdue contact, report-to addresses, run records, Library files, environment variable values and triggers other than time schedules are not included.** What you wrote yourself, such as an agent's goal and guardrails, goes in as it is, so choose who the file goes to.

**Anyone who can create a project can import.** Choose “Import from file” when creating, pick a file exported in another environment, and the steps, agents and schedules are listed. Check them and press “Import”. **An imported project is created paused, and its schedules (time triggers) are switched off.** Where approval is required, it cannot run until its first definition is approved. A file that cannot be read, has a different format version, or is too large cannot be imported (a half-made project is removed). Someone who is not allowed “Scheduled run creation” cannot import a definition that contains triggers, step times or an enabled sweep.

**When you import, what does not exist in this environment is not brought in and is listed under “Settings needed for the imported definition” at the top of the project screen.**

| Heading                                                            | What appears                                                                                                                                                                                                                            | Runs                                                                                                                                                                         |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runs can’t start until these items are set up again.               | A connector that is not in this environment, the playbook or skill an agent uses                                                                                                                                                        | Do not start until set up again. The project cannot be resumed from paused, so starting by email, by a time trigger or the like does not work. Re-running a sweep is refused |
| Items to set up again if needed                                    | Reconnecting a connector, choosing reviewers, triggers and Library links that were not brought in, input files, environment variable values, destinations of Branch steps, choosing an External automation destination again, and so on | Not stopped                                                                                                                                                                  |
| Settings removed because they aren’t available in this environment | Settings this environment cannot use, such as “Agents that can’t run in this edition”, “Branch rows judged by a question”, or a time trigger of a cycle definition                                                                      | Not stopped                                                                                                                                                                  |

Items in the first row clear when an owner sets them up again through “Open connector settings” or “Open editor”. Items in the second and third rows can be cleared by an owner with “Mark as reviewed” once checked.

**A company template is a model in which only the fields you decide are filled in by whoever uses it.** Only an owner can publish. On the Settings tab, under “Share as a company template”, choose the “Fields the user fills in” (destination, connector, input files, schedule), a “Note for users” (up to 2,000 characters) and the “Scope” (my organization / everyone in the company), then press “Publish as a template”. What is published is a copy of the confirmed definition as of that moment; fixing the project later does not change the template until you press “Update template”. “Stop sharing” removes it from the list (projects already made stay). To publish to your own organization you need an organization (otherwise choose “everyone in the company”).

**Anyone can use one, whatever their role.** Choose “Create from a company template” when creating, pick a template from the list (ones you published, ones for your organization, ones for everyone), and fill in only the fields it asks for. Connections are made afterwards, by you, on the connector. If a chosen destination is disabled, the project cannot be created. Like an import, the project is created paused, and “Settings needed for the imported definition” may appear. Someone who is not allowed “Scheduled run creation” cannot create a project from a template that contains triggers, step times or an enabled sweep.

Where on screen 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”／top of the project screen ＞ “Settings needed for the imported definition”

## Checking a draft and applying it

Changes to steps and placements, including a placement's “Company memory” and “Files synced with the library”, build up as a **draft**. **Until you apply it, the project does not change.** What you apply takes effect from the next run; it does not affect a run already under way.

**Where the tenant has turned on the setting that makes definition changes need approval, an applied change is not used until it is approved.** A change saved with “Apply changes” becomes a “Pending approval” version, and runs keep using the active version until it is approved. The approver is a project owner or an organization admin other than the person who saved the change, and both approving and sending back (a reason is required) are done from the pending-approval notice on the project screen or from the Inbox. Sending it back leaves the active version as it is. An owner can withdraw a pending change. **A project that has just been created (including by copying or importing) cannot run until its first definition is approved.** The name, description, tags, sharing and notifications change at once, without approval. What needs approval is the steps, placements, triggers and connectors, and definitions such as the type, basic rules and limits.

A draft stays **in that browser**. You can pick up where you left off next time you open the editor, but **it does not follow you to another browser or device**.

Before applying, you can **validate the settings**. Validation covers the draft as well, and **it neither saves anything nor runs anything against an external service**. Coming through validation cleanly does not mean the run will succeed: authentication on a connector, and the permissions it has at the time, are checked when the run happens.

**What validation reports is the same judgement as the “to fix” count shown in the editor.** It goes through the **enabled** steps by kind. On a step **that takes an agent**, it looks at **whether an agent is placed**, **whether that agent has a goal**, and **whether “Files synced with the library” still holds a file deleted from the library**. On a **review step**, at **whether it has reviewers** (in a workflow). On an **External automation step**, at whether a destination is chosen and still enabled. On a **Branch step**, at whether it has lanes and conditions, whether the lane steps sit right after the Branch step one lane after another, and whether any lane is reached neither by a condition nor by “When no condition matches” (not checked with “Let a person choose”). In a cycle it also looks at **whether the placement has a schedule**. **A schedule you have deliberately stopped does not count as a point to fix.**

**Apart from the points to fix, “Points to check” may appear.** They do not stop you applying. They appear when the project uses an external connector but has no review step and the connectors' “Confirm before connecting” is “Don't confirm” (the agent acts on the outside without a person checking), when it is started from outside by a webhook or an email but has no review step (the agent proceeds to the end without a person checking), and, in a cycle, when the sweep interval is shorter than the “Length of one run” (the next sweep may start before the previous one finishes). Check that it is what you intend. There is also a point to check when DLP integration is on and the project has an External automation step: that step cannot be used.

Changes are applied one by one. If some of them could not be applied, **those stay in the draft**, and the reason for the first failure is shown. Fix them and apply again. Where adding, deleting or reordering a step, or adding, placing or removing an agent, failed and held up the later changes of that kind, “**Discard this change**” removes just that one from the draft (this cannot be undone).

**One thing to watch. An agent's settings are not part of the draft.** When you edit an agent and save it, it is saved there and then. Discarding the draft does not undo the change to the agent. Do not think that discarding a reordering of steps will also roll back what you changed in an agent.

**To try out a change to an agent, try it on a new agent.** There is no way to duplicate your own agent, so create a new agent, carry over the goal and skills, place it in a project you test with (duplicating makes one), check the results, then apply the change to the original agent. **Keep your own note of what you changed and when.** Which changes Records (audit trail) keeps is in the [Records Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/events-ref.md).

**The Settings tab ＞ “Basic information” does not use the draft; it changes when you save.** If the project was updated by another change after you started editing, a notice appears when you save, and you choose “**Load latest**” or “**Keep my edits**”. Keeping your edits takes the latest values for the fields you did not change and lets you carry on; press “Save” again to save.

Where on screen The top of Edit ＞ “Check settings” and “Apply changes”

### Restoring an earlier version

**Each definition you apply is kept as a version; you can see what changed and restore the step settings of an earlier version.** Select a version to see its changes as “Added”, “Removed” or “Changed”, grouped into “Basics and execution rules”, “Steps”, “Placements”, “Triggers”, “Notifications” and “Connectors”.

**“Restore this version” restores only the settings of steps that still exist.** Adding, removing and reordering steps, placements, triggers, notifications, connectors, and basics and execution rules are not restored. Restoring loads that version's step settings into the draft and opens the editor; save them with “Apply changes” (in a tenant where definition changes need approval, they are not used until approved, as described above). If the current step settings are no different, a message says so and nothing is loaded. Only owners can restore, and only in the editor on a wider screen. A version that is “Pending approval” or “Cancelled” cannot be restored.

Where on screen The Overview tab ＞ “Project info” ＞ “Show All” ＞ “Versions” ＞ select a version ＞ “Restore this version”

## Letting the AI draft it for you

**The features for creating and consulting with the AI are alpha.** Their entry points on screen are marked “(alpha)”. How they behave and look may change. **Do not use what the AI made as it is; always check it.**

There are two ways to have the AI draft something when you create a project (drafting from the chat is described under “Drafting from the chat” below): choose “**Create through consultation**” or “**Guided setup**” under “**How do you want to create it?**” (both are marked “alpha”).

**The “Personal” tab of the dashboard shows “Candidates for a project”.** These are Schedules and Claws you run on a regular schedule, and playbooks and skills you use many times. Making repeated work into a project gives you its records and improvement consultations. “Guided setup” on a candidate starts creating one straight away.

### Talking it through to make one

Write what you want to do and the AI will **settle on a type, steps and agents, and produce a draft**. It may come back with questions along the way. The AI also draws on the shape (the order of the steps, where reviews sit, the placements and so on) and the results of projects you take part in and of public projects, and shows them in the proposal as “**Referenced projects**”. It does not draw on their goals or conversations. Playbooks and skills you have already registered are **picked out of the candidates by the AI and attached**. Anything it only knows by name is shown as “Not registered: …”, for you to attach. The proposal shows the names of the skills and the playbook it attaches to each agent, as “Skill: …” and “Playbook: …”.

Look the draft over and create it, and it is saved at that point.

### Answering questions to make one

Choose “**Guided setup**” and you **answer fixed questions one at a time**, starting from an official template. While you answer, the AI does not run and no project is created. A question that offers “**I don't know, next**” can be passed with that button, a question that lets you press “Next” without choosing anything can be passed without a choice, and you can go back to an earlier question to change the answer.

Once you have answered, a “**Suggested structure**” appears. It lists the type, steps, assigned agents, start and connected services, and **nothing is saved yet**. Press “**Refine with AI**” to finish it with the AI, starting from this structure. Look the draft over and create it, and it is saved at that point.

The skills and playbooks the template calls for are not attached by name. They are shown under “**Needs to be prepared**”; what gets attached is picked as when talking it through, or attached by you. **The connected services are not connected yet** (they show “**Not set up**”). Connect them in the project's connected services after it is created.

**For a workflow template with a fixed step structure, the number of steps and the sequence of agent steps and review steps stay as in the template, as long as it is created as a workflow.** A draft in which the conversation with the AI changed that number or sequence is put back to the template's steps (the screen says so). To change them, use the editor after the project is created. If you decide during the conversation to make it a cycle, the template's structure — lanes, destinations and the like — is dropped (the screen says so).

Where the official questions and templates cannot be used, the screen says that guided setup is not available right now.

### What to check either way

**Where a time trigger was proposed, it is registered switched off.** Where a schedule was proposed for a cycle, **the project is created paused**, and each placement's sweep is registered with that schedule; sweeping starts once you resume the project. Where the person creating it is not allowed “Scheduled run creation”, the sweeps are registered switched off and do not start when you resume. This is the same on both paths. Check the contents before you switch anything on or resume ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md)).

Look at the placements you ended up with and check **how many agents were placed on each step**. **Where the number or the arrangement is not what you need, adjust it after it is created.** A “Run by Agent” step with no agent assigned is marked “**No Agent**”. Place an agent on it after it is created. Above the diagram in the editor, “**Steps that need an Agent: N**” appears, and “**Create an Agent for “(step name)” with AI**” or “**Open “(step name)”**” lets you place an agent, starting from the first such step. Selecting the step also shows “**Create an Agent with AI (alpha)**” and “**New Agent**” in the panel on the right. Where the proposal has fewer steps than the minimum (2 for a workflow, 1 for a cycle; for a cycle, review steps are not counted), empty “Run by Agent” steps are added up to the minimum, and a warning tells you so. After creation, set the content and agent of the added steps, or replace them.

### Consulting the AI after it is created

**After a project is created, you can still consult the AI in the editor.** You can consult it on **reviewing the project setup** and on **creating an agent**. For eligible workflow step runs and cycle sweeps that did not go well, you can ask for improvement ideas in the run record ([Record Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/record-guide.md#revisiting-it-from-the-track-record)).

**For a private agent owned by someone else, what the AI receives stops at the goal (instructions).** Its guardrail and the skills and playbook attached to it are not visible to the AI, so the proposals may not take them into account. Check with the owner where needed.

**When you take in a proposal, changes to steps, placements and sweep schedules go into the draft.** They do not reach the project until you apply them. **A proposal to create or change an agent opens the agent's screen, and is saved when you save it there.** If a new agent has a step to be placed on, that placement goes into the draft too.

Where on screen When you create a project ＞ “How do you want to create it?” ＞ “Create through consultation” or “Guided setup”. After creating, Edit ＞ “Editing tools” on the left ＞ “Ask the AI (alpha)” ＞ “Discuss the project setup” or “Discuss creating an Agent”

### Drafting from the chat

**You can also have the AI draft a project from a flow you have settled in the chat.** Ask in the chat to turn the flow into a project (for example, “turn this flow into a project”). A “Project draft” card appears in the chat. **Nothing is created at this point.** Press “Open in new project” and project creation opens with this draft ready to import. Check the steps, agents and schedules and press “Import” to make the project (as with an import, it is created paused with its schedules switched off).

**You can ask in the chat to fix an agent that is not behaving, too.** Ask to change the goal or guardrails of one of your agents in a project, and an “Agent fix draft” card appears. Press “Open in agent editor” and, if your agent is found, its editor opens with the fix laid over it (if several agents share the name, you choose which to apply it to). **Nothing changes until you save, and saving applies to every project that uses the agent.**

**You can also ask in the chat for drafts of the Playbooks and Skills you attach to agents.** A “Playbook draft” or “Skill draft” card appears; press “Open in Playbooks” or “Open in Skills” and the creation screen opens with the draft filled in (if you ask by naming one of your own Playbooks or Skills to fix and exactly one has that name, its edit screen opens). Nothing is registered or changed until you save.

In each case, after it opens you check it on the current screen and save it yourself. You cannot fix someone else's agent (ask its owner). Changes to steps and placements are made with “Ask the AI” in the project editor.

## Distinctions worth keeping straight

These are the distinctions that cut across the sections above.

- **Thinking a guardrail stops an operation.** Writing “do not send the reply yourself” into a guardrail is **an instruction to the agent**; it is no guarantee that the operation is stopped. An operation you need stopped for certain is forbidden in the **execution rules** ([Execution Rules Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/control-guide.md))
- **Editing one agent and breaking several pieces of work at once.** Changing an agent's settings **reaches every project that uses it**. And **an agent's changes are saved separately from the draft of the steps and schedules — discarding the draft does not undo them.** If you want different behaviour per project, split the agents
- **Thinking that duplicating a project divides the agents.** **Your own agents are placed in the duplicated project as the same agents.** To try something, create a new agent
- **Taking the arrangement of a cycle's steps for an order.** However the steps are arranged in the diagram, **in a cycle that arrangement is not the order things run in**, and no step waits for the one before it to finish. To join the stages up, express it in [the marks on the record](#joining-the-stages-of-a-cycle). **To make the work itself proceed in order, choose a workflow**
- **Not checking the trigger settings once it is created.** A time trigger the AI (alpha) proposes is **registered switched off**, and a cycle it proposes a schedule for is **created paused**. On a copy, the time trigger is switched off and **a cycle's rounds do not carry their schedules over**. Once it is created, check that **what you want running runs, and what you do not want running does not** ([Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md))

## What to read next

- [Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md) — where to put review steps, and who to let decide
- [Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/trigger-guide.md) — when, and on what, to set it running
- [Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/connection-guide.md) — what to connect to, and where to send word
- [Execution Rules Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/control-guide.md) — how far an agent may go
- [Settings reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/settings-ref.md) — the limits and defaults for steps, skills, retry counts and the rest
