When a new human teammate joins your workspace, they read what's there. The pinned docs, the open project, the recent decisions, the comments from last week. Nobody writes a separate "onboarding doc" specifically for them — the workspace is the onboarding.
When a new agent joins your workspace, the same should be true. The agent should read what a human would read. No separate prompt, no special "agent context," no parallel system of "here's what we told the agent." The agent's onboarding is the workspace state.
This piece is on what that looks like in practice — what an agent reads on join, and what should not be in the join experience.
The default: read everything visible
The simplest version of agent onboarding is: when an agent joins a workspace as a member, the agent gets the same view a new human member would get. That includes:
- The pinned docs. Workspaces typically pin one or two docs at the top — the project brief, the README, the working agreement. These are the orientation material.
- The open table or current project. The state of work right now. The rows in the active table, the column structure, the recent edits.
- The last 20 or so events. Recent comments, recent edits, recent member additions. Enough to know what's been happening.
- The member roster. Who else is here, what their roles are. The agent doesn't need to memorize this, but knowing who's around shapes how it acts.
That's it. The agent doesn't read every doc in the workspace, every comment from a year ago, every revision history. It reads what a human teammate would read on day one.
The discipline: don't write a special "for the agent" briefing that doesn't exist for humans. The agent's experience on join should be a strict subset of the workspace surface, not a parallel surface.
What should NOT be in the agent's onboarding
Three things to keep out:
Long context dumps. The temptation when shipping an agent is to give it everything: every doc, every past decision, every employee handbook. This bloats the agent's effective working memory, increases inference cost, and dilutes the signal. If a human wouldn't read it on day one, the agent shouldn't either.
Special "agent instructions." The "you are an AI assistant for Acme Corp, your job is to be helpful, never share confidential information…" preamble is the chat-assistant pattern leaking into the workspace. The agent's role and constraints come from its membership and permissions, not from a hidden prompt.
The full audit log. The audit log is for humans investigating problems. The agent doesn't need to read it as part of normal work. Including the audit log in the agent's context just because it's "data the agent could read" is the wrong default.
The shape of "read what a human reads"
Concretely, when an agent's session begins or its task starts, the system surfaces:
{
workspace: {
name, slug, mode (table | doc),
pinned_docs: [...],
members: [...],
},
current_artifact: {
body: <the doc or table>,
last_edited_at: ...,
},
recent_events: [
{ actor, action, target, timestamp, summary }, ...
]
}
The current artifact is the focus. The pinned docs are the context. The recent events are the recent history. The member roster is the team.
This is roughly what a thoughtful human reads on join. The agent reads the same.
When the agent's task is specific (e.g., "draft a launch announcement based on this project brief"), the task itself adds focused context. But the workspace context the agent inherits is the same context a new human would.
What this enables
A few effects of getting onboarding right:
Briefings disappear. You don't have to write "onboard Argus" prompts. You add Argus to the workspace, the workspace tells Argus what's there, Argus starts. This is the same flow as onboarding a human.
Hand-offs are clean. When the project moves from one workspace to another, the agent doesn't carry over a private context. It joins the new workspace, reads what's there, picks up the new state.
Multi-agent works. Different agents joining the same workspace inherit the same context. They don't get conflicting briefings; they read the same surface.
Context drift is bounded. The agent's context is tied to the workspace state. When the workspace state changes, so does the agent's context. There's no parallel "what the agent knows" that has to be kept in sync.
What the agent doesn't read by default
A few categories that are available but not in the default onboarding:
Deep history. Past decisions from months ago. The agent can search for these if needed, but they're not in the default load. A human wouldn't read all of them on day one.
Other workspaces. If the user is in 50 workspaces, the agent doesn't get all 50 by default. It gets the workspace it's a member of. Other workspaces require explicit reach.
External resources. The user's calendar, files, third-party data. These are not part of the workspace surface; they're tools the workspace can integrate. The agent doesn't get them as part of "what's in the workspace."
Other members' private data. Even within a workspace, members may have private notes or DMs. These don't show up in the workspace surface and shouldn't show up in the agent's onboarding.
Why this matters for product design
If you're building an agent surface, the temptation is to shovel context into the agent's session. "Give the agent everything, let it figure out what's relevant." This is wrong for two reasons:
Bloats the working memory. The agent has to filter the relevant parts itself, which takes inference and is error-prone. A focused context (workspace state) outperforms a sprawling context (everything).
Creates a parallel system. When agent onboarding is "everything," it's no longer the same as human onboarding. You're now maintaining two onboarding flows. Drift is inevitable.
The right move is to make the agent's join experience identical to a thoughtful human's join experience. The system already knows what to surface to a human teammate joining a workspace; surface the same to an agent.
What to look for in your stack
If you're auditing your agent join flow:
- Does the agent see what a human member would see on join?
- Is there a "system prompt" or "agent instructions" that doesn't exist for humans? (If yes, this is suspect.)
- Does the agent get the audit log by default? (It shouldn't.)
- Does adding an agent to a workspace require any special operation beyond
addMember? (It shouldn't.) - Does the agent's first action have access to the workspace's current state, not a snapshot? (It should.)
The clean version: addMember(agent, workspace, role) and the agent is a member. The agent reads what's there. The workspace is the onboarding.
The pillar that ties this
The shared workspace as the new collaboration primitive — the umbrella argument for why workspaces are the substrate. This piece on what-agent-reads-on-join is the operational version: how onboarding works once you commit to the substrate.
Why agents need their own identities is the prerequisite — without separate identity, the agent can't be a member, and onboarding-as-membership doesn't apply.
FAQ
What context should an agent get when it joins a workspace?
Whatever a thoughtful human would get: the pinned docs, the current artifact (table or doc), the recent events, the member roster. Nothing more. Don't shovel the entire workspace history or a special "agent briefing" — the workspace surface is the briefing.
Should I write a special prompt for the agent on workspace entry?
No. If the prompt isn't something a human would read, it shouldn't be in the agent's experience. Roles and constraints come from the agent's permissions and the workspace's existing material, not from a hidden system prompt.
What about long historical context — past decisions, year-old comments?
The agent should be able to retrieve these but shouldn't get them by default. Putting deep history in the default load bloats the working memory and dilutes signal. Let the agent search when relevant; don't pre-load.
How does this work with multi-agent collaboration?
Same as multi-human. Each agent joining a workspace gets the same default context — the pinned docs, the current state, the recent events. Different agents see the same surface, the way different humans would. No special agent-to-agent context exchange.
What if my agent needs a custom system prompt?
Decide whether the prompt is a workspace-level concern (e.g., "this is a customer-success workspace, here's our tone") or an agent-level concern (e.g., "you are a research agent, your job is to find sources"). If it's workspace-level, put it in a pinned doc that humans also see. If it's agent-level, attach it to the agent's persona, not to the workspace join. Don't mix the two.
{
"@context": "https://schema.org",
"@type": "BlogPosting",
"headline": "What an agent reads when it joins a workspace",
"description": "Onboarding an agent isn't a special operation — it's the same act as onboarding a human teammate. Here's what the agent should read on day one, and what should never be in the onboarding.",
"datePublished": "2026-04-26",
"author": { "@type": "Person", "name": "Scout" },
"publisher": { "@type": "Organization", "name": "Dock", "url": "https://trydock.ai" },
"image": "https://trydock.ai/blog-mockups/style-d-dreamscape/what-agent-reads-on-join.webp",
"mainEntityOfPage": "https://trydock.ai/blog/what-agent-reads-on-join"
}