Create an agent

An effective agent starts with a narrow responsibility and a result you can evaluate. Avoid creating a universal assistant with a page of conflicting instructions.

Create the definition

Open Agents and choose Create Agent. Enter a name and purpose that explain the job without internal jargon.

Choose a model, then write instructions that cover:

the role the agent should play;
the inputs it can expect;
the process or constraints it must follow;
the required output format;
when it should ask for clarification or stop.

The workspace's Model Rules decide which models you can pick: the workspace's rule and the agent's own rule, if it has one. When the agent runs as a step of a workflow that has its own rule, that rule applies to the run too.

Changes you haven't saved aren't lost by moving on. While you create or edit an agent, following a link, choosing Cancel or switching workspace first asks whether to save them, discard them or keep editing; saving moves on only once the save succeeds. Closing or reloading the tab asks your browser to confirm. Dialogs such as a new schedule or environment variable ask before Escape, their close button or a click outside drops what you typed. The agent's Run page asks too before a link drops the instructions or input you typed, but offers only to discard them: starting a run isn't a save.

What instructions can change

Instructions set the agent's job: its role, its limits and its style. They work inside the rules Guest Machines gives every agent, which they can't switch off: an action that needs approval still asks for it, and the agent never takes what it reads as an instruction.

Each run starts with a request from whoever started it: a person in a chat or through the API, a schedule's or webhook's task, a workflow step, or another agent. The request says what to do within the agent's instructions; it can change details the instructions leave open, such as how long the answer is, but not the instructions themselves.

Everything the agent reads while it works is information: a webhook's payload, an email, a web page, a file, a tool's result, another agent's answer or message. If an email says "ignore your instructions", the agent doesn't. When one agent hands work to another, it passes the material to work on as input, so the agent it calls reads that material as information too.

Make structured output enforceable

Instructions describe what you want; an output schema makes the shape machine-checkable. Use the agent's output contract when another app or workflow depends on exact JSON. Guest Machines accepts a bounded, object-rooted JSON Schema Draft 2020-12 profile and rejects an invalid schema when the agent is saved.

For example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "summary": { "type": "string", "minLength": 1 },
    "risk_level": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    }
  },
  "required": ["summary", "risk_level"]
}

List every mandatory field in required. Set additionalProperties to false when undeclared fields must fail; JSON Schema allows them by default. A default value is descriptive only—Guest Machines neither inserts it nor coerces a value to another JSON type.

Guest Machines checks the final answer against your schema. A mismatch fails the run. Passing this check proves structure, not factual accuracy or task quality. See the developer guide for the exact JSON requirements and supported schema limits.

Add capabilities deliberately

Assign only the tools and apps needed for the job. Every capability expands what the agent can do and what you need to test and govern.

Knowledge, environment variables, execution limits, network policy, and delegation rules should reflect the same least-privilege approach.

The agents and workflows an agent may call are the ones you name under Access mode, and an agent a connected workspace published to yours by its address, such as acme/billing. Each is kept by its identity, not its name: renaming one later keeps it allowed, and the agent calls it by its new name. A new agent given a removed one's old name isn't allowed in its place.

An agent with Enable Cloud Sandbox on gets a Linux sandbox with a terminal and file system, and optionally a virtual desktop. When a run needs you there, for a sign-in say, you can take control of its sandbox. Sandbox Internet Access lets that sandbox reach the internet within the workspace's egress policy. Sandbox internet is also off when the egress policy blocks a domain and no allowlist applies, since a sandbox can't block a single domain; the run page shows a policy event under Rules for This Run explaining why. A sandbox keeps the setup it started with. Change Virtual desktop, Screen size, Pre-install Commands or Require Successful Setup (or the sandbox template, through the API) while a run is paused, and the run continues in a new sandbox when it resumes; the old sandbox's files and programs are gone, and a policy event says which setting changed. A new Sandbox Timeout applies to the same sandbox.

For visual work, assign Generate an Image to create or edit images and save the results as run files. See generate and edit images for model choices, references, and transparent backgrounds.

Google tools aren't assigned on the Tools page: an agent gets them from the permissions you grant it from an app you installed, such as Gmail or Google Drive, where you choose which operations, files and calendars it may use. See use apps.

Choose knowledge access

An agent can't read Knowledge until you give it knowledge access. In the agent editor, find the Knowledge access card and choose one:

Off, the default for a new agent: it can't read Knowledge.
Everything it can see: every file its sharing allows. A private agent reads your My Library and the Workspace Library, and an agent shared with the workspace or restricted to people you add reads only the Workspace Library. This never grants access to other people's private files.
Selected folders and files: only the ones you choose.

With knowledge access on, the agent gets the tools to search and read Knowledge; you don't assign them on its Tools page.

To choose the sources:

Choose Selected folders and files, or Edit Selection to change an existing selection.
For a private agent, use Knowledge source to switch between My Library and Workspace Library, and select files or folders from either; switching sources keeps your selections. Any other agent can select only from the Workspace Library.
Choose Apply, then save the agent. Apply needs at least one folder or file; to give the agent no Knowledge, choose Off.

A selected folder includes its subfolders and their current and future files, subject to visibility permissions. Selecting individual files keeps the scope narrower.

Selecting a file does not publish it or change who can use it. If a shared file is unpublished, a saved selection does not preserve access for other members. See add knowledge for publishing and storage behavior.

Give it credentials

Keep each credential with the thing that uses it:

An MCP server's credential belongs on its custom app, under Apps: a token, a sign-in, or keys it expects in a header or the URL. When a Streamable HTTP connection uses the Guest Machines relay, Guest Machines adds the credential without sharing it with the model provider. Legacy SSE bypasses the relay: the provider connects directly and receives any configured bearer token, sign-in access token, or request credentials. Then grant the app to the agent. See MCP credentials and trust boundary.
An HTTP tool's credential belongs on the tool, under Connections & setup → Tools. Then assign the tool to the agent. Its credentials were entered for one destination, so changing the tool's endpoint to another host or port, or its request method, asks for them again, or for authentication to be removed. Editing a tool shows how its credential is sent, such as the header or query parameter an API key goes in, without the credential itself: leave it blank to keep it, or enter a new one to replace it the same way. Changing how it's sent asks for it again too. Viewers can't create, change or test HTTP tools.
Google access comes from Apps, where you install Gmail, Google Drive or Google Calendar with your own account and grant each one to an agent. See use apps.
Any other value or secret is an environment variable. Create it under Connections & setup → Environment, then assign it to the agent in its editor. An agent can read only the variables assigned to it and the ones set on the agent itself, and with any of them it gets the tools to read them; you don't assign those tools.

A secret's value never appears to the agent. By default it is in the environment of the agent's Cloud Sandbox, where code the agent runs can read it, and when a tool's result would show it, such as a command that prints it, the agent sees [REDACTED] in its place. Code in the sandbox can still send it anywhere the sandbox's network reaches, so for an API key, prefer an HTTP tool or an MCP server that holds it, or choose the hosts the secret may go to.

To keep a secret out of the sandbox entirely, check Send only to chosen hosts when you create or edit it, and list the hosts, such as github.com for git or api.github.com for GitHub's API; *.example.com covers the subdomains of example.com, not example.com itself. Inside the sandbox the variable then holds a placeholder. When code there makes an HTTPS request to one of those hosts, the secret is added on the way out, in the header you choose under How it's sent: a bearer token, token for GitHub's API, Basic auth for git over HTTPS (for a GitHub token, use the username x-access-token), or the value alone in a header you name. Code can send the placeholder in that header or leave it out; either way, the real value replaces it.

The secret is added by a proxy that reads those requests, so programs in the sandbox see the proxy's certificate for those hosts. Tools like curl and git trust it, and Node and Python are pointed at the sandbox's certificates for you. If you set NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE or SSL_CERT_FILE as a variable yourself, your value is kept, so it must include /etc/ssl/certs/ca-certificates.crt.

Only HTTPS requests to those hosts carry the secret, and only in that header, never in a URL or a request body. A sandbox can send secrets to at most 10 hosts in all; if the secrets a run gets name more, or two of them use the same header for one host, the extra ones aren't sent.

Choose how tool calls are approved

Each tool on the agent's Tools page has an approval setting:

Default — asks a person before high-risk actions when someone can answer; otherwise runs.
Ask a Person — always asks before the tool runs.
AI Review — the AI reviewer checks each call and can refuse it. Each review is a short model call, charged to the run.
No Approval — runs without checks.

For an HTTP tool you create, its Risk level decides whether it counts as high-risk: high-risk tools ask a person under the Default approval setting.

A run has an approval setting of its own. Choose it when you start a run from the agent's Run page, or in a chat, where it applies to the run in progress or the next one:

Use Tool Settings — each tool follows its own setting.
AI Review — the AI reviewer checks every tool call. Tools set to Ask a Person still ask.
No Approvals — every tool call runs without asking anyone, including tools set to Ask a Person, the Concierge's changes, and Google actions such as sending email or changing a calendar event.

Workflow steps always keep their agents' own settings. Lowering the approvals of a run that started a workflow doesn't approve a step's tools or answer a step's tool calls.

A run set to No Approvals never asks. Otherwise a tool set to Ask a Person asks, and so do Google actions set to Approve Each Use; then a run's approval setting applies, then the tool's own setting. A tool with no setting asks only when it's high-risk and someone is there to answer.

A run nobody can be asked about, one started by a schedule, a webhook, or an automation account, can stop before it begins with Approve tools for this run. This unattended run will use high-risk tools with nobody watching. Approve the tools to let it use them. A run a person starts, in the app, with their API key, or through an app acting for them, asks them at each high-risk tool call instead, the way a chat does. A private automation asks its owner the same way. A schedule or webhook that isn't private asks its owner about Slack posts and nothing else; see approve posts. A workflow step can also name the person its runs ask; see choose who a step asks.

An MCP server whose tools Guest Machines runs locally asks a person before every call, and so does a provider-hosted one set to Ask a Person, so a schedule or webhook can't run an agent that has one: each local call would be denied, and a hosted server that asks stops the run before it starts. Adding one to an agent that schedules or webhooks already run doesn't stop them, so saving lists them and offers to turn them off. Saving its custom app's server, under Apps, does the same when the change stops them, such as setting it to Ask a Person. Unattended runs on the agent's page names the server; see local execution and hosted server approval.

In a shared workspace, owners and admins decide who may lower approvals for a run. Under Settings → Workspace → Run approvals, choose Members Can Lower Approvals (the default) or Only Admins Can Lower Approvals. Lowering means choosing AI Review or No Approvals for a run; going back to Use Tool Settings is always allowed.

When a run waits for an answer, the person who started it can approve or deny its tool calls and its tools, and so can a workspace owner or admin. A private run, one started from a chat or by a private automation, is the exception: only its owner can answer it. A question the agent asks can be answered only by the person the run asks: whoever started it, or the member a workflow step names. See answer a waiting run.

Let it remember

Turn on Memory in the agent's settings to let it keep documents between runs. You don't assign memory tools: the setting gives them to its runs.

Read only: its runs can read and search its memory, but not change it. Use this when you write what it should know yourself.
Read and write: its runs can also add, edit and delete documents, so it keeps what it learns.

An agent has two kinds of memory. Its own memory is what every run of it reads; only runs started by someone who can edit the agent change it. Each person who runs it also gets personal memory, which only their own runs read and change. Sharing an agent never shares its own memory: a person it's shared with sees only what it remembers about them.

Open Memory on the agent's page to read and change what it keeps. Every change is kept as a version, so you can restore an earlier one, bring back a deleted document, or redact a version that holds a secret or personal data. Opening another document, switching between the agent's memory and yours, Close, Cancel on a new document or a link first asks whether to save the changes you haven't saved, discard them or keep editing. Memory comes from earlier runs, so the agent treats it as information, never as instructions.

Test the boundary cases

Use a chat to test realistic input, missing information, invalid input, requests outside the agent's role, and every important output-schema boundary. Test a missing required field, a wrong JSON type, an unexpected field when additionalProperties is false, and any formats or limits you rely on. Inspect the run's Result checks when the result is surprising.

Make it reusable

Once the agent is reliable, use it as a step in a workflow. Keep its contract narrow enough that another person—or another agent—can predict what it will return.

A new agent is Private: only you and workspace admins can use it. Choose Restricted to add specific people and automation accounts, or Workspace to share it with everyone in the workspace.

Viewers are a read-only audience: they can see what's shared with them, but never run, chat with or schedule an agent, not even one they own. A restricted agent doesn't offer them as people who can use it, and someone added before they were made a viewer can only see it.

Everyone who can run a shared agent can also chat with it: its owners, workspace admins, and the people it's shared with, apart from viewers and anyone given view-only access. Each person's chats stay private to them, and with memory on, what the agent remembers about each person stays in that person's own memory. Only its owner chats with a private agent, so those conversations stay theirs; workspace admins manage it but don't chat with it.

You can choose to share a snapshot of your chat with anyone who has its link. This publishes the snapshot you previewed; the original conversation stays private.

Choose its owners

In a shared workspace, whoever creates an agent becomes its owner. Owners manage the agent: its settings, its sharing and its owners. Workspace admins can always do the same. The agent's page lists its owners under Owners, and its header names who originally created it.

A shared agent (Restricted or Workspace) can have several owners. An owner or admin chooses Add Owner and picks a member who can manage agents. Viewers can't be owners.
A private agent has one owner, because it can use that person's own access: their Google access, their HTTP tools, their private MCP servers and their private environment variables. It uses that access only in runs its owner starts, so a run a workspace admin starts works without it, and those runs are private to the owner: nobody else can open them, and workspace admins can only cancel or delete them. It stops using that access as soon as its owner is made a viewer, or their account is locked, deactivated or removed, even in runs already working or waiting for an approval: each later use is refused, the run carries on without it, and the owner's private MCP servers drop out of it. Share the agent to add more owners.
Any owner can remove another owner, or themselves. A private agent's owner is the only one who can stop owning it, so its conversations stay theirs; admins step in only once that owner's account is deactivated or they leave the workspace.
When the last owner leaves the workspace, or removes themselves, the agent keeps working without anyone's own access, and workspace admins manage it until someone owns it again. Admins are emailed, and find these agents with Needs an Owner on the Agents page. On a private agent, an admin chooses Assign Owner to hand it to one person; anything it still used of someone else's own access is removed first, and what is that person's own stays.

Someone's own access belongs to them alone, so a shared agent can't use it. Sharing an agent that uses it asks first, then removes it and shares the agent; any schedules or webhooks that needed it can be turned off at the same time. Making an agent with several owners private asks which owner keeps it, and the others stop being owners.

Every saved change makes a new revision. The agent's page lists them under Version history, with who saved each one and the tools it had. If a change went wrong, choose Restore on an earlier revision: its settings are saved as a new revision, and the agent's sharing and whether it's on stay as they are.

On this page