Skip to main content

Connection Guide

A registered agent may use external services. This guide covers what a project connects to, and where it notifies about reviews and results. Whether outbound traffic is allowed is in the Execution Rules and Network Access Guide.

A connector is something this project connects to​

A registered agent reaches an external service through the connection slots set in its contract. In the project, you assign this project's connectors to those slots.

  • Workflow: In the step settings' “Connectors”, choose from this project's connectors for each connection slot of the contract. You can choose only connectors the administrator allowed for the slot. If an allowed connector is not among the project's connectors, add it first under Settings > Connectors (Agent Guide)
  • Cycle: There are no slots to assign in the step settings. The tokens of this project's connectors that are enabled are passed to the agent (Agent Guide)

In a workflow, if a connector cannot be used, the agent does not launch. In a cycle, the token of a connector that cannot be used is not passed to the agent, and the agent launches (if the token can no longer be obtained just before launch, it does not launch). Reasons such as “The connector selected in the step is unavailable” and “The connector's credentials are missing or invalid” appear in the execution record (Record Guide). Before running, check that no connector's authentication has lapsed.

To put a person's judgment before an agent that writes to an external system, place a review step before it. (Review Guide).

For external wait, you choose the review step's “Connector used for observation” from this project's connectors. To move on sooner with webhooks from GitLab, also enter the connector's “Webhook secret for external wait” (Review Guide).

Where in the UI Settings tab > “Connectors (MCP, A2A)”. For a workflow, assigning connectors is under Edit > select the step's agent > “Step settings” on the right

A review is notified to the reviewers​

Review requests and notices that a review's deadline has passed reach the reviewers without any setup (on by default). They come as in-product notifications, browser push notifications, and email. Push reaches only people who have allowed (subscribed to) notifications in that browser. What an owner has switched off for that event, or a channel someone has turned off in their own notification settings, is not sent. A delegate the reviewer has handed it to for a period also gets the in-product notification and an email with a dedicated link. The email uses the sending method and sender decided under “Announcements and Notifications” > “Notification Settings” > the “Mail Provider Settings” tab in the admin console. If no mail provider is set, no email is sent (Review Guide).

You decide a review on the review screen that the link in the email opens.

A review is not decided automatically even after its deadline. The overdue notice goes to the reviewers (and to the contact for overdue reviews, if one is set), and the case keeps waiting for a decision.

Turning notifications off​

An owner can switch notifications on and off for each event. The events are “Review requested”, “Review deadline reminder”, “Review overdue”, “Run past its deadline”, and “Run stalled”. Review emails for an event you turn off are not sent.

  • The recipients of review requests, reminders, and overdue notices are the reviewers (the last reminder also goes to the contact for overdue reviews)
  • “Run past its deadline” and “Run stalled” go to all owners of the project (Record Guide)

An owner can send events to a URL of an outside system (outbound webhooks). The URL must be an HTTPS one reachable from outside. The events you can send are the five above and “Run finished” (when a case closes). What is sent is only the event, the IDs of the project, run and review request, the time, and a link (“Run finished” also carries 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, after 1, 5, and 30 minutes.

Where in the UI Settings tab > “Triggers and notifications”. Outbound webhooks are in the same place

Receiving run results yourself​

A member can receive, for themselves only, a notice when a project run completes. It goes only to people who turned it on, while they are still members, by push and email (a channel you have turned off in your own notification settings is not used). It contains the name, the time it ended, the first paragraph of the output, and a link to the record.

For a workflow, it arrives when a case closes as completed. In a cycle, the result notice arrives only for runs where the agent reported completion, and at most once per placement in each clock hour. It does not arrive for “Run ended (completion not measured)” (Record Guide).

Where in the UI Settings tab > “Triggers and notifications” > the “Result notice” switch

Checking whether it was sent​

The result of trying to send the review email is kept in that review request's activity. It is not a confirmation that it reached the person. What is kept is “Notification queued for sending”, “Notification was sent”, “Notification failed”, and so on. When something does not arrive, look here first.

Connectors on a project you copied​

When you copy a project, the list of connectors is copied. Connections (authentication) are not copied, so connect the connectors again in the copied project.

Easy to get wrong​

  • Thinking that once you add a connector, every agent can use it. In a workflow, you can assign only connectors the administrator allowed to the contract's connection slot
  • To stop a write to an external system, place a review step. The connector settings alone do not stop it
  • Thinking the review moves on automatically after the deadline. It does not. It notifies about the overdue review and waits
  • Thinking a result notice arrives for a cycle's “Run ended (completion not measured)”. It does not
  • Agent Guide — Assigning connectors, and the tokens passed to the agent
  • Review Guide — Notifications for reviews, and external wait
  • Record Guide — Reasons it could not launch