Skip to main content
A connected account can still lack access that a task needs. For example, a GitHub App might be installed on other repositories but not the one the task needs, or a Google Drive grant might not include the file the task works on. Instead of failing, or asking the requester for access in a text reply that might bounce between agents, the task calls requireAccess() (require_access() in Python).

Ask for access

requireAccess() takes the connection that lacks access, a reason shown to the human, and a verify function that checks whether the task has the access yet. It resolves once verify returns true. In this example, github is the skill’s githubAppConnection():
The task moves back to requires_action, with an oauth action that carries the reason. The request reaches the human no matter how deep the task sits in its chain. The top requester’s action handler receives it, every task handle above the task lists it, and delegate_task and wait_for_tasks return it to the model at the top. A model inside a task never needs to relay the link itself. The SDK runs verify after the human finishes with the link. It also runs verify on its own every few seconds, gradually slowing to once a minute, so it notices access granted elsewhere. If the check still fails after the human returns from the link, the human is asked again.

Choose where the human goes

By default, the link opens the connection’s own page for granting more access: Pass accessUrl (access_url in Python) when you create the connection, or url to requireAccess(), to send the human elsewhere. For example, your own page with the Google Drive Picker can give the task access to the file it needs. Here, google is the skill’s googleConnection():

Check access before committing

Gather and verify every account and resource a task needs before the task commits, since a committed task can’t wait on its human. Calling requireAccess() on a task that has committed throws a TaskCommittedError and fails the task. A task with a flat price commits with its first result chunk, so check access before streaming. Canceling the task stops the wait. If the human doesn’t finish within an hour, the task fails with the code action_expired.

Access in schedule runs

A schedule run calls requireAccess() the same way, and checks access through its schedule’s connection. Only that run waits, and the action appears on the run’s handle. The schedule’s requester hears about it. If the schedule was delegated as part of a task, the human at the top of the chain hears about it instead. The schedule stays active, but starts no new runs while a run is waiting. If the human doesn’t finish within an hour, only that run fails, and the next run asks again.