Skip to main content
A Reason is the long-running agent you keep. You have a main Reason, and you can add named ones for areas of work, such as release notes or support. Each Reason has its own:
  • Instructions: plain-text guidance every new Session started with the Reason receives.
  • Conversation: one long-running chat where you give it work.
  • Sessions: the tasks it starts, which are filed under it.
  • Loops: its scheduled and event-driven work.
  • Defaults: the model, reasoning effort and repositories its new Sessions start with.

Your main Reason and named Reasons

Every person has exactly one main Reason in a Workspace. It is listed first, is never deleted, and holds the Sessions and Loops you have not filed under another Reason. Your main Reason stays personal: its Sessions are yours alone, and Workspace owners and admins do not get them either. Named Reasons are the ones you create. You can make one of your own named Reasons your main one, as long as it is personal and has never been shared. It keeps its name, instructions, memory and Sessions, and the former main Reason becomes an ordinary named Reason. In the app, your main Reason’s menu has Replace with different Reason.

Give a Reason work

Messaging a Reason is the main way to give it work. Your message goes into its conversation, and the Reason decides how to do the work: it answers, starts Sessions, or sets up Loops. A message sent while the Reason is working steers its running turn. Anyone the Reason is shared with may message it, and each turn acts as the person who sent the message. From a terminal:
NAME is a Reason’s name in any case, its id, or main. --queue waits for its running turn to end first, --detach returns once the message is accepted, and --json prints machine-readable output. reason agents is the same command.

Create and set up a Reason

In the app, choose New Reason in the sidebar. The Reason opens on its empty conversation; tell it what it is for. To change a Reason, ask it in its own chat, for example “Rename yourself to Release notes” or “From now on, keep answers short”. The API changes the same settings. What you can set: A change applies from then on. Sessions that are already running keep what they started with.

Default model

A Reason’s default model is what its new Sessions start on when they pick none. In the app, open the Reason, choose Details, and set Default model under Instructions. Its owner and managers can change it; asking the Reason to change its model does the same.
  • Workspace default follows the Workspace’s default model in Settings › Models, and changes when that does. A Reason starts here.
  • A fixed model is one of Reason’s models or a connected account’s model, with its reasoning effort. The list shows which account each model runs on.
A new Session uses, in order, the model picked for that Session, the Reason’s default, then the Workspace’s default. This covers Sessions you start in the app, the Sessions the Reason or another Session starts, its Loops and its Slack conversations. Sessions that have already started keep their model.
  • If the fixed model’s account is disconnected, or no longer has the model, new Sessions start on another model the Workspace can run, when there is one, beginning with its Model priority list. The row says so until you reconnect the account or pick another model.
  • A Session that runs on a connected account keeps that account’s model for the Sessions it starts, unless the Reason’s default is another connected account’s model. Work on your subscription does not move to Reason credits.
  • A Session created with the REST API names its own model or uses the Workspace’s default.
The row appears once the Workspace has connected a model account of its own. Without one, every Session runs on Reason’s model for the plan. A named Reason can also have a start step and an end step that every Session under it carries out. They are in preview: see Start and end steps.

Share a Reason

  • In a Workspace with two or more people, a new Reason starts shared with everyone. In a Workspace of one it starts private.
  • Share this Reason on a Reason sets who has it: everyone in the Workspace, people you invite, or only you.
  • Sharing has two levels. A Collaborator can chat with the Reason. A Manager can also edit its settings and share it with others.
  • Everyone a Reason is shared with can talk to it, start Sessions under it, and read and continue its Sessions and Loops. Each person’s own chat with a team Reason stays theirs.
  • Sharing a Reason makes it a team Reason: its Sessions run in the cloud and never use anyone’s personal secrets.
  • Your main Reason cannot be shared. To share work from it, use Share on a Session, which makes a new shared Reason.
See Workspaces and sharing for what a Workspace shares with every Reason in it.

Delete a Reason

Only a Reason’s owner deletes it, and the main Reason is never deleted. Deleting a named Reason:
  • Removes it from every Reason list.
  • Deletes its Loops, so nothing scheduled or triggered runs for it.
  • Removes its own Slack app, if it has one.
  • Archives its conversation with its history.
The Sessions it started stay where they are. Nothing restores a deleted Reason. The API’s Archive a Reason is the same operation as delete, under its older name.

Limits

  • A Workspace holds at most 500 live named Reasons. Main Reasons do not count.
  • A name is at most 80 characters and instructions at most 16,000.
  • A Reason has at most 6 default repositories.

API

Every call needs an API key with the scope shown. See Authentication and scopes. Creating a Reason allocates no computer and starts no work. Send it a message to start:
The message call returns once the message is accepted, not when the Reason answers. Poll the Reason’s messages with the last end_cursor for its reply. The Reason’s owner and its managers change its setup. Anyone else it is shared with gets 403 reason_manager_required.

Next steps

  • Loops: standing work a Reason does on a schedule or an event.
  • Memory and Skills: what Reasons know and how they work.
  • Slack: talk to a Reason from Slack.
  • GitHub: the repositories a Reason works in, and its pull requests.