Connection Guide
This guide covers the settings that let an agent reach an outside service, and the settings that tell a person something has happened.
What to give an agent is covered in the Design Guide, and how much to allow is covered in the Execution Rules Guide.
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.
A connector is something this project connects to
Writing it into a goal does not by itself put an outside service that needs authentication within an agent's reach. That service has to be added as a connector and authenticated.
There are two kinds of connector: external services, and agent-to-agent integrations. They are added and authenticated the same way, and neither is stopped by the basic rules. To stop one you name it as a forbidden operation, but how you name it differs by kind (Execution Rules Guide).
The authentication belongs to the project. It is stored separately from your personal connections under Settings. Even where you have authenticated it yourself, it is authenticated again as a connector on the project.
Only an owner can add or authenticate one. Members cannot change them (Who decides what).
You are asked to confirm before removing a connector from the project. Once removed, the agents in this project can no longer use it. The connection (authentication) is not undone.
You cannot add to the candidates. What you can pick from is the set that has been made available. Where the service you want is not among them, talk to a system administrator. The candidates are narrowed by the organization and job role of the project's owner (the one person whose name the runs go out in); other owners' organizations and roles are not considered. If an MCP server is limited to certain organizations and roles and the project's owner does not match, it does not appear as a candidate and is refused on save; a connection already attached is not deleted, only hidden.
There are two ways to authenticate, depending on the service: following the prompts on screen, and entering a token. Where an MCP server has “Allowed account domains” set, you can connect only with an account whose verified email is in that domain, and a connection by pasting a token is not possible.
The authentication status is shown on screen. “Authenticated”, “Re-authentication required” and “Not connected” appear there, so check that no “Re-authentication required” is left before you run anything. “Status unavailable” can also appear. That is not the same as “Not connected” — the status simply could not be read — so look again a little later.
“Authenticated” is no guarantee that future runs will succeed. The permissions it has at the time are checked when the run happens. When it was last used appears in a separate field from the authentication status.
Where on screen The Settings tab > “Connectors (MCP, A2A)” > “Add connector”. Authentication and status are in the same place
Use as ledger
Joining the stages of a cycle needs a shared record (Design Guide). On the connector you are using as that record, put “Use as ledger”. Where definition changes need approval in the tenant, this switch also takes effect only once approved (Checking a draft and applying it).
More than one connector can carry it.
Putting it there, however, makes nothing happen on its own. It is a mark, and the following do not follow from it.
- No reading or writing begins. What to read and write is written into each agent's goal (instructions)
- No permission is added. It does not let anything be done beyond what the authentication allows
- No duplication or conflict is prevented. Keeping several agents off the same subject at once is expressed through the marks on the record and each agent's goal (Design Guide)
What putting it there does is show that the team has settled on this as the shared record. It is there so that whoever writes an agent's goal knows where to read and write.
Where on screen The Settings tab > “Connectors (MCP, A2A)” > the connector > the “Ledger” switch
Asking a person before use (connection confirmation)
For each connector, you can ask a person to confirm before an agent uses it. Under the connector's name, choose “Confirm before connecting” from “Don't confirm” (the default), “Confirm first use only” and “Confirm every time”, and set the “Wait limit (minutes)” (1 to 1440 minutes; 60 by default). While it is “Don't confirm”, the wait limit cannot be chosen. It cannot be set for an agent (A2A) connector. Only an owner can change it. Where definition changes need approval in the tenant, a change to this setting also takes effect only once approved (Checking a draft and applying it).
When an agent is about to use a connector set to confirm before connecting, the run stops there and a review request is raised (a connection confirmation). This is the same for a workflow step and for a cycle sweep. The stopped run shows “Failed (reported by agent)” as its result and “Stopped for connection confirmation” as its reason, but it is not counted as a failure (Results Reference). The review request shows the connector the agent was about to use and the purpose the agent declared.
A connection confirmation can only be approved or rejected. It cannot be sent back, and its deadline cannot be extended (it is not a target of the bulk actions in “Action needed” either). Like a review request raised from the result of a “Run by Agent” step, as a rule its reviewers are every owner at that moment (Review Guide).
- Approving starts the stopped step or sweep again, using this connector. A workflow runs the agent of the same step again as a new attempt, and a cycle runs the sweep of the same placement once. A cycle's restart uses the same slot as rerunning a sweep, so if a rerun of the stopped run has already been requested, it does not start again. The run record of the restarted run says “This run was started again after a connection confirmation was approved”
- Even after approval, it may not start again. In a workflow, if the placement was removed while waiting, it is handled the same as a rejection; if the workflow run has closed or the step has moved on, nothing happens. In a cycle, nothing happens when the sweep cannot be rerun, for example because the placement was removed
- Rejecting does not start it again. In a workflow, the stopped run is handled by the step's “When the agent reports it could not finish” setting (Design Guide). In a cycle, nothing happens
- When the wait limit passes, it is decided as rejected. It does not start again. The “Confirmation” section of the run record shows “Expired”
How far an approval applies depends on the choice. “Confirm first use only” applies, in a workflow, to the later steps of the same workflow run as well. “Confirm every time” applies only to the restarted run and to runs restarted from it after it asks for confirmation again. A cycle has no workflow run boundary, so both choices work like “Confirm every time”.
The request reaches the reviewers (and their delegates) both inside the product and by mail. This is so for a cycle too. It can also be approved by replying to the mail (the section below). Word that the wait limit has passed reaches the reviewers (and their delegates) inside the product and by mail. The confirmation is already closed, so it cannot be decided from that mail. It does not reach the escalation contact.
Where on screen The Settings tab > “Connectors (MCP, A2A)” > under the connector's name > “Confirm before connecting” and “Wait limit (minutes)”. To decide: “Inbox” on the left > “Review requests” > pick one > “Approve” or “Reject”
A review is notified to the reviewers on its own
A review request, and word that a review deadline has passed, reach the reviewers without anything being set up. They arrive both inside the product and as mail, with a link of the reviewer's own (delegates during the delegation period get them the same way, inside the product and by mail; the mail telling that a connection confirmation was closed at its wait limit has neither that link nor the reply option). To stop them, turn them off event by event (next section). How reviewers are settled is covered in the Review Guide.
A passed review deadline is something that happens in a workflow. In a cycle, a review request also arrives only for a connection confirmation, because a cycle cannot have a review step (Review Guide). How a connection confirmation is announced is in the section above.
Word that the deadline has passed arrives where “Notify and keep waiting” was chosen. Under the settings that proceed, send back or reject automatically at the deadline, nobody is told so long as that goes through (Review Guide). A connection confirmation is decided as rejected when its wait limit passes, and the reviewers (and their delegates) are told, inside the product and by mail.
What arrives takes you to the screen where you decide. Both the notice inside the product and the link in the reviewer's mail open the request itself under “Inbox” on the left > “Review requests”, and that is where it is decided (Review Guide).
Where the reviewer's own link in the mail is still valid at the moment of deciding, the decision is recorded as having been made by mail. Even where the link has expired, a reviewer or their delegate can still decide on the screen — that decision is not recorded as made by mail, though.
The mail also says what each decision leads to (“After the decision”) and what happens once the deadline passes. That way a reviewer can tell from the mail alone what follows a decision.
You can also approve by replying to the mail. Where the mail says you can approve by replying with only “APPROVE”, reply with nothing but “APPROVE” (or “承認”) on the first line of the body, and it is approved. Rejecting and sending back need a reason, so do them on the screen opened from the button in the mail.
- Only the reviewer or delegate who received the mail can reply. The sender must be that person's registered email address, and the mail must pass sender authentication (DMARC)
- Only a reply to the latest mail received works. The mail saying the review deadline has passed offers replying too (except the one telling that a connection confirmation was closed), and once it arrives, replies to the earlier mail no longer work
- A reply can decide it up to 7 days after that mail was sent, or the review deadline, whichever is earlier. For the mail sent after the review deadline has passed, it is 7 days after it was sent. A connection confirmation is decided once its wait limit passes, so it is up to that limit
- A review with destination options cannot be approved by reply. The mail does not offer it either; choose the destination on the screen
- It is not approved when the sender differs, the time for deciding by reply has passed, someone else decided first, or the review's content has changed. A reply whose first line is not “APPROVE” or “承認” does not decide anything either
When approved by reply, the channel in the Records (audit trail) is mail_reply (Records reference). Approving by reply works only in environments where the mail feature is enabled.
In some environments mail is not sent at all. These are environments where mail delivery is not set up. There, the review request's activity keeps “Notification failed” (see a later section).
Where on screen “Inbox” on the left > “Review requests” > pick one. What arrives — the notice or the link in the mail — opens the same screen
Turning notifications off
Notifications are turned on and off event by event. There are five events, Review requested, Review deadline reminder, Review overdue, Run past its deadline and Run stalled, and all are on by default. A run completing and sweeps failing in a row are separate notices (next sections).
Turn one off and neither the notice inside the product nor the mail is sent. In the project settings, there is no switching to the product only, or to mail only. For yourself, you can stop push notifications and mail event by event under “Notifications” in your personal settings (the lists and history inside the product remain). Turning Review overdue off also stops it reaching the escalation contact.
Run past its deadline and Run stalled arrive when a workflow run passes its deadline, or does not move beyond the “Hours before a run counts as stalled”. They arrive once per deadline and once per stall, and the run does not stop (Record Guide).
Who receives the in-product notifications and mail is fixed by the event, and you cannot add a recipient. Review requested goes to the reviewers (and their delegates); Review deadline reminder goes, while a review request is still undecided as its deadline nears, to the reviewers (and their delegates), and its last reminder also to the escalation contact; Review overdue goes to the reviewers (and their delegates) and the escalation contact (an expired connection confirmation goes to the reviewers and their delegates only); Run past its deadline and Run stalled go to every owner of the project. There is no setting for adding another address. To tell other systems, use outgoing webhooks (next paragraph).
Only an owner can switch them. This section of five switches appears for workflows only, so the notifications of a cycle's connection confirmations cannot be stopped. The default escalation contact is settled in the same section too (Review Guide).
Events can be sent to an HTTPS URL of another system (outgoing webhooks). The events are the five above and “Run finished” (when a workflow run closes, including when it closes as failed). Each webhook takes one event, and up to 20 can be registered per project. What is sent is only the IDs of the event, project, run and review request, the time and a link (for “Run finished”, also the state it closed in). If you enter a signing secret, an HMAC-SHA256 signature is added in the X-Agentic-Star-Signature header. If delivery fails, it is retried up to 3 times. Only an owner can register or change them.
Where on screen The Settings tab > “Triggers and notifications” > “Notifications” > the switches for “Review requested”, “Review deadline reminder”, “Review overdue”, “Run past its deadline” and “Run stalled”, and “Default contact when overdue”. Outgoing webhooks are under the Settings tab > “Triggers and notifications” > “Outgoing webhooks”
When sweeps keep failing, the owners are told
When sweeps of the same placement of a cycle fail the number of times shown on the Settings tab in a row, a notice goes by mail and push notification to every owner and to the owner of that placement's agent (if a member). For sweeps that started, this is when the latest executions, as many as that number, are each “Failed (reported by agent)”, “Failed”, “Timed out”, “Failed (stopped)” or “Not allowed by rules” (a sweep stopped for a connection confirmation is not counted). When sweeps could not start, the notice goes when that happens that number of times in a row. Failures of sweeps that started and sweeps that could not start are not counted together. The number is the value of “Notify owners after consecutive failures (email, push)” shown on the Settings tab (3; it cannot be changed on the screen).
It arrives only once for the same run of failures. If a sweep succeeds and then fails again in a row, it arrives again. The notice carries the name of the placement's agent, the count, and a link to the latest execution record of that placement (or the run history if there is none).
It cannot be switched in the project settings. You can stop your own mail and push notifications for the “Consecutive failures” event under “Notifications” in your personal settings. It does not arrive while an administrator has notifications turned off.
Receiving run results yourself
Members can receive, for themselves only, a notice when a run of the project completes. It is off by default. It works for both workflows and cycles.
For a workflow, it arrives once when the run closes as completed. It does not arrive when the run closes as failed. For a cycle, it arrives when a sweep ends as completed, but at most once per clock hour (for example, the 10 o'clock hour) for the same placement. It arrives by mail and push notification, with the name, the end time, the first paragraph of the output and a link to the record. To stop only one of the two, choose the channels for the “Result notice” event under “Notifications” in your personal settings.
It stops arriving once you are no longer a member.
Where on screen The Settings tab > “Triggers and notifications” > the “Result notifications” switch
Checking whether it was sent
The result of trying to send the review mail is kept in that review request's activity. It is not confirmation that it reached anyone, though. What is mostly kept is “Notification queued for sending”, “Notification was sent” or “Notification failed”.
Where it could not be sent — no address, or the recipient has opted out — that is kept here too. Look at this first when something does not arrive.
Where on screen “Inbox” on the left > “Review requests” > pick one > “Activity”
Connectors on a project you copied
The list of connectors carries over, but the connections (authentication) do not. Where you copied the project from another one, connect them again in the copied project. The screen says so.
This is because authentication carries permissions. It would be a problem if whoever copied it could go on using the original project's authentication, so it does not carry over.
The “Ledger” marks, “Confirm before connecting” and “Wait limit (minutes)” carry over too.
Whether notifications are on or off does not carry over either. The copy starts with all five events on, so turn off again whatever you had turned off. The default escalation contact does not carry over either.
Distinctions worth keeping straight
These are the distinctions that cut across the sections above.
- Thinking that “Use as ledger” starts the reading and writing. It is only a mark. What to read and write is written into each agent's goal. No permission is added either
- Thinking that notifications can tell you about anything. The event notifications are five: “Review requested”, “Review deadline reminder”, “Review overdue”, “Run past its deadline” and “Run stalled”. Besides these, there are the “Result notice” you receive yourself and the “sweeps failing in a row” notice that goes to the owners. A run starting cannot be announced. A workflow run failing cannot be announced by in-product notifications or mail either, so look at it in “Action needed” (to tell other systems, use the “Run finished” event of outgoing webhooks)
- Thinking it can be sent to addresses other than the reviewers'. A review request and a passed deadline reach the reviewers without anything being set up. But there is no setting for adding a recipient of notifications and mail (to tell other systems, use outgoing webhooks) — all you can do is turn each event on or off, and settle the escalation contact
- Thinking any reply to the mail can decide it. Only an approval can be made by reply. Write nothing but “APPROVE” (or “承認”) on the first line of the body. Rejecting and sending back are done on the screen
- Taking a run stopped for a connection confirmation as a failure. It is not counted as a failure. It is only waiting for a person to confirm, and it starts again when approved. It does not start again when rejected, or when the wait limit passes
- Taking “Notification was sent” in the record as proof it arrived. It is not confirmation of arrival. It holds the result of trying to send, no more
- Thinking your personal connection can be used as it is. A project's connectors are authenticated separately from your personal connections
- Thinking you can add the service you want yourself. You cannot add to the candidates. You pick from the set made available
What to read next
- Design Guide — building the stages of a cycle around a shared record
- Review Guide — who to ask for a review, and how they decide
- Execution Rules Guide — how much to allow against a connector
- Who decides what — who can change the connectors
- Settings reference — the limit on the number of connectors