# AI agent workspace

URL: https://tfw.how/tool-classes/ai-agent-workspace/
Description: An AI agent workspace holds the instructions and reference material that AI agents use for one topic. Each topic has one workspace, named with the topic code and the canonical name.

AI agent workspace is the [tool class](/glossary/#tool-class) for the context that AI agents use when they work on a topic: the instructions, the reference material, and the conversations with the agent. Examples of products in this class are a Claude project and a ChatGPT project.

## Role in TFW

The AI agent workspace is the source of truth only for its own instructions to the agent. It tells the agent which topic it works on, what the topic is for, which terms the topic uses, what the agent may and may not do, and where the topic's records are.

The workspace is not the source of truth for anything the agent produces. Agent output is a draft until a person or an authorized agent writes it to the right [source of truth](/glossary/#source-of-truth): a task in [task management](/tool-classes/task-management/), a page in the [knowledge base](/tool-classes/knowledge-base/), a file in [document storage](/tool-classes/document-storage/), or a change in a [code repository](/tool-classes/code-repository/). A conversation with an agent is [conversation](/glossary/#conversation), like chat.

## One topic's surface

The example topic Example Co Operations (topic code EXOP) has one AI agent workspace.

- **Container.** One project or workspace in the agent product, owned by the organization where the product allows it.
- **Name.** The topic code and the canonical name: `EXOP Example Co Operations`.
- **Instructions.** A short description of the topic: its purpose, the outcomes it works toward, its terms, the limits on what the agent may do, and links to the topic's records. The instructions link to the [registry](/glossary/#registry) and to the [topic profile](/glossary/#topic-profile); they do not copy lists that change.
- **Reference material.** Only stable material that improves the agent's work and that is allowed inside the topic's [access boundary](/glossary/#access-boundary). Link to the current version of a record instead of uploading a copy that will go out of date.
- **Permissions.** Shared with the topic's participants, within the topic's access boundary.
- **Maintainer.** One named [maintainer](/glossary/#maintainer) keeps the name, instructions, reference material, and sharing correct.

## Rules

- Each topic has at most one AI agent workspace in each agent product. Create a separate workspace only when the access boundary or the purpose is different, and record the reason.
- Name the workspace with the topic code and the canonical name.
- Treat agent output as a draft until it is written to the source of truth.
- Do not put credentials, secrets, or material outside the topic's access boundary into the instructions or the reference material.
- Look up topic codes in the registry for the current session. Do not copy the list of codes into the instructions.
- Give the agent authority to change other tools only for specific, approved actions.

## Common mistakes

- **One workspace for everything.** An agent with every topic in one workspace mixes context and access across topics.
- **A workspace per task.** Many small workspaces for one topic split its context. Use one workspace for the topic and link to the task.
- **Copied records as reference material.** An uploaded copy of a page or a task list goes out of date. Link to the record.
- **Decisions only in the agent conversation.** A result that must last is written to the source of truth, and the conversation links to it.
- **A connection treated as permission.** A connection to another tool does not mean the agent may change records there.

## Tools

This site does not yet have a tool page for this class. Products in this class follow the same rules.