Core concepts

Guest Machines treats agents like programs: they accept input, use tools and knowledge, call other agents when allowed, and return output. The product builds on that model with a few reusable concepts.

Chat

A chat is a conversation with an agent. Use it to explore a problem, test behavior, and iterate before introducing automation.

Agent

An agent is a reusable AI worker with a purpose, instructions, model, tools, knowledge, and execution policy. An agent definition is the program; each execution is a run. With memory turned on, an agent keeps documents between runs: its own, which every run reads, and personal memory for each person who runs it, which only that person's runs read.

In a shared workspace an agent has owners, who manage it: whoever created it, and anyone an owner or admin adds. A private agent has one owner and may use that person's own access, such as their Google account; a shared agent can have several owners and uses nobody's own access. When an agent's last owner leaves, workspace admins manage it until someone owns it again. See choose its owners.

Knowledge

Knowledge is the context an agent can retrieve from files you upload. My Library holds private working material. Workspace Library holds material intentionally shared with the rest of the workspace.

An agent reads Knowledge only when its knowledge access is on. A private agent can then read your My Library and the Workspace Library; an agent shared with the workspace, or restricted to people you add, reads only the Workspace Library. Knowledge access can narrow that to specific files and folders from My Library (private agents only) or the Workspace Library. It does not override the files' visibility permissions.

Where files live

Publishing moves a file from My Library into the Workspace Library, and unpublishing moves it back. Add to Knowledge makes a copy of a run file instead, and removing either copy leaves the other. In a chat, Add From Knowledge works the other way: it attaches a copy of a Knowledge file to your message, for that chat only.

Workflow

A workflow puts several agents to work on one job. It is a list of steps that run in order: an agent step runs one agent, a parallel step runs an agent on several parts at once, and a workflow step runs another workflow. Each step can read the run's input and what earlier steps returned, run only when a condition holds, and decide what happens if it fails. Part of a workflow can repeat until a condition holds, such as a review approving a draft.

Start a workflow from its own page, the API, a schedule, an inbound webhook, a step of another workflow, or an agent that calls it. See build a workflow.

Agent or workflow

So how a job starts rarely decides between them. What differs is who decides the steps.

An agent decides as it goes. It reads the request, picks its tools, and chooses what to do next from what it finds. If it's allowed to call other agents, it also decides when to hand them work. Choose an agent when:

• the steps depend on what turns up, such as researching a question or triaging a request;
• the work is a conversation, or needs a person to steer it in a chat;
• one set of instructions and tools covers the whole job.

A workflow follows the steps you set. You decide which agents run, in what order, and what each one receives; each agent still does its own work inside its step. Choose a workflow when:

• the job has stages that should always happen in the same order, such as draft, check, then format;
• different stages need different tools, models or access, so no single agent should hold them all;
• a result should be checked by a separate agent, and redone until it passes;
• the same work should run on every item in a list at the same time;
• you want a limit, a retry or a backup agent for each stage, and to rerun a failed run from the stage that failed.

For example, "answer questions about our pricing from the Workspace Library" is one agent. "Research each competitor on this list, then write one comparison" is a workflow: a parallel step researches every competitor at once, and an agent step writes the comparison from their results.

Start with an agent. When its instructions turn into a long list of stages, or you want a second agent to check its work, split the job into agents and connect them with a workflow. An agent that uses your personal access, such as your Google account or your private environment variables, can't be a workflow step, so keep that part of the work in an agent of its own.

When two agents each do their own work and one just needs to ask the other something, such as support checking a clause with contracts, turn on messaging instead. See let agents talk to each other. Messaging can also reach agents another business's workspace publishes to yours; see connect with another workspace.

Not sure which fits? Describe the job to the Concierge. It proposes an agent or a workflow and explains its plan before building anything.

Run

A run is one execution attempt. Its execution status and verification status answer different questions: Completed means execution finished, while Checks passed means Guest Machines ran every required result check and all passed. A completed run can show Not checked, so completion alone is not a claim that the output is correct.

Each check proves something specific. An output-schema check confirms that the result matches the required JSON structure, not that the facts are true or that the result solved the task well. A schema mismatch fails the run; execution that pauses, is cancelled, or fails before producing a terminal result is not evaluated by the output verifier.

A run can also be required to create at least one downloadable file. The API calls this setting require_artifact=true. The run shows Checks passed only after it creates a file; finishing without one fails both the run and its result checks. Creating or providing a file when this setting is off does not, by itself, verify the run's result.

Open Run Files to find every downloadable file you can access in the workspace. Supported files can be previewed there without downloading them. You can also download a file, use it in another run or automation, add an independent copy to Knowledge, or remove uploads and run outputs you manage. A file cannot be removed while an active run is still using it; the page shows which runs must finish or be stopped first. A Knowledge copy has its own lifecycle, so removing either copy does not remove the other. When the source was a run output, the Knowledge copy also keeps that run link.

Every workspace has a shared run file storage allowance. A file starts using space as soon as it begins saving, and deleting a file frees that space after cleanup finishes. The Usage page shows storage used, available storage, the file limit, and files still being saved. It also reports Files used by runs as activity: reusing the same file in three runs counts as three uses, but it remains one stored copy and does not use more storage.

Adding a run file to Knowledge creates an independent copy. The original uses run file storage and the new copy uses Knowledge storage; either can then be removed without deleting the other.

In a shared workspace a run also carries three optional attribution tags — project, ticket, and cost center. They are a reporting dimension and nothing more: a tag never changes whether a run is admitted, what it costs, or which budgets and limits apply to it. Child runs inherit their parent's tags, so a workflow reports as one unit of work rather than as scattered fragments. Personal workspaces have no attribution, because there is nobody to charge the work back to.

Events, tool calls, child runs, output, verification evidence, errors, and resource usage provide the operational record of what happened. A run can also stop and wait for a person — to answer a question, approve a tool call, or approve the tools an unattended run will use — until someone responds. Home lists the runs waiting on you; see answer a waiting run.

Trigger

A trigger starts work without a person clicking Run. Guest Machines supports scheduled work, inbound webhook flows, and app triggers that start an agent when a selected Google or Outlook calendar changes, new mail arrives in Gmail or Outlook, someone mentions the bot in a Slack channel, or Linear or GitHub sends an event.

A trigger points at exactly one target. A schedule or inbound webhook can point at an agent or a workflow. You choose the target when you create the trigger and it stays fixed for the trigger's life, so sending the same work somewhere else means creating a new trigger. Add a trigger only after the agent or workflow behind it is stable. Nobody is watching a triggered run, so the target is checked before the trigger is saved; build a workflow describes what can stop it.

A trigger that uses your Google access is private to you: its target is a private agent you're the only owner of, never a workflow, and you review what it may do before it runs.

Other schedules and inbound webhooks run as the person who created them, with that person's own credentials when they alone own its agent. So only the creator changes one, runs it now, turns it back on or replaces its URL; a workspace admin can pause, stop or delete it. When that person leaves the workspace, they stop, until an owner of the agent or a workspace admin takes them over from the agent's page. If they stay a member but can no longer start work, because they were made a viewer or their account was locked or deactivated, while a run the trigger started waits for a slot, that run is recorded as a failed run (dequeue.actor_unavailable). The trigger stays on until its next fire checks its creator again. See use apps.

In a shared workspace a trigger also carries its own attribution tags. Nobody is present when a schedule fires or a webhook arrives, so there is no launch form to ask at: the tags belong to the trigger's configuration, and every fire stamps them onto the run it starts. An untagged trigger produces untagged runs, so tag it when you create it rather than after it has been running for a month.

A trigger can also provide the same files on every run. Choose a file from a completed run, then add it while creating or editing the schedule or inbound webhook. The platform checks that the file is still available and that the trigger's owner can still use it each time the automation fires. For a workflow, the file's name must match a file the workflow expects when a run starts.