Your agents

Set each helper’s instructions, model and capabilities for a specific kind of work.

An agent combines a role with an executable configuration. Its name helps you recognize it; its instructions, model, capabilities, and permissions determine what it can actually do.

Create distinct agents when responsibilities need different access or working styles. A project reviewer may need read access to documents, while a coding assistant needs a repository and command tools. Changing the mascot or name alone does not create that separation.

Create and test a specialist

Open the agents area and create an agent. Give it a clear description, choose a ready model, and write instructions about the result it should produce. Then enable the minimum capabilities needed for a representative task.

You help prepare product documentation.
Use the supplied source material and identify unverified behavior.
Return editable drafts with source references and unresolved questions.
Do not publish documents or contact people unless explicitly asked.

Test this role with one small task. Confirm the tools and output before adding automation, remote access, or delegation.

Configure the agent in layers

A concise description also helps a coordinating agent select the right specialist. State a job rather than a personality alone: “Reviews technical documentation against source code” is easier to delegate to than “Helpful and clever.”

The tool picker

Automatic tool mode begins with a compact available surface and loads relevant capabilities as needed. Manual mode uses the enabled selection more directly. Turning tools off removes the agent's ability to perform those operations even if its prompt still describes them.

Adding a tool does not complete its external setup. A calendar operation may need macOS permission; an MCP tool may need an authenticated server; a provider may need valid credentials. Inspect each dependency's status.

Working folders and the Sandbox

A Working Folder gives a conversation a selected host directory. Sandbox execution uses its own environment. They are different choices; selecting a host folder can turn Sandbox mode off for the agent.

A chat-specific folder takes precedence over a default. A project's folder can seed new chats in that project. Before a destructive or bulk edit, inspect the folder in the active conversation rather than relying on the agent's remembered default.

Sandbox permissions

Review execution, installation, network, and secret access controls supported by the current runtime. Sandbox availability and implementation vary with the Mac's operating system. Enabling Sandbox does not make an external service available or imply unrestricted host file access.

See Sandbox for the runtime details and Tasks for file workflows.

Memory per agent

Personal memory is scoped to an agent. Disable it when the role should not retain conversational context. Project memory is a separate shared scope governed by the overall memory setting; a chat within a project can still use that context.

For structured records such as a reading list, enable the agent database instead of relying on inferred memory. The two features solve different problems.

Knowledge per agent

Assign collections the role should consult. Project collections are merged into the current conversation as well, so review both sources when deciding which documents a role may receive. Read and write use should be considered separately.

Subagents per agent

Enable delegation and select the allowed specialists. Configure whether a call asks, is denied, or is allowed. Give delegates bounded jobs with explicit inputs and expected outputs. A child run uses the target agent's configuration; it does not simply inherit every assumption from the parent conversation.

The built-in Orchestrator

The built-in Mellow agent coordinates configuration and delegation. Its restricted surface is intentionally different from a custom hands-on agent. Rename it if desired, but use a custom specialist for file writes, execution, and other enabled task capabilities.

Share or move an agent deliberately

An exported configuration, a paired-device connection, and a Cloud workspace grant are different forms of access. Exporting a role is not proof that its provider credentials, models, local files, or permissions exist on another Mac.

After importing on another host, check dependencies and run a small task. For remote access, inspect the actual shared agent, allowed scope, expiration, and host identity. Keep access keys private; the public host address is not itself an authorization grant.

Diagnose the role, not only the model

Keep the role small enough to understand. Add a capability because a real responsibility needs it, then verify that operation before relying on it unattended.