Connect an AI Agent to Notion or Confluence Without Chaos

To connect an AI agent to Notion or Confluence, give it a dedicated read-only account that can see a small, named set of spaces, and let it answer only from pages carrying an explicit approved marker. Keep drafts out by status, by location and by review date, so that unfinished text never reaches the agent in the first place. The work is mostly editorial: deciding which pages count as the truth before any integration touches them.

Key takeaways

• Expose spaces by the questions the agent must answer, not by convenience. Start with a few owned, maintained spaces and leave everything else out.
• Use a dedicated account for the agent with read-only access. Its permissions are the ceiling on what it can ever repeat.
• Mark approved pages with metadata: status, owner, audience and review date. Only the page owner applies the marker, never the agent.
• Filter before indexing, not after. Text that was never loaded cannot appear in an answer.
• Make the agent cite the page, owner and review date, and say plainly when no approved page covers the question.

Why does connecting an agent to a wiki go wrong?

A wiki is written by many people over a long time. It holds current procedures next to retired ones, proposals nobody finished, meeting notes full of opinions, and pages pasted from somewhere else. A person reading it notices a draft banner, checks the date, or asks a colleague. An agent that retrieves passages sees text, and an outdated rule reads just as confidently as the current one.

Four failures show up again and again:

• Stale answers: the agent quotes a rule that was replaced, because the old page was never archived.
• Leaked content: a private space (HR, finance, legal) was reachable because the connection was granted at workspace level.
• Unresolved conflicts: two pages disagree and the agent silently picks one.
• Embedded instructions: a page contains text that reads like a command, and the agent treats it as one. Guidance such as the [OWASP prompt injection prevention cheat sheet](https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html) explains why page content must always be handled as data, never as instructions.

Here is an illustrative scenario. A services firm connects its assistant to the whole workspace. A client asks how long onboarding takes, and the agent answers from a brainstorming page in which a manager sketched an ambitious target. The page was never meant for clients, was never approved, and was still the best textual match. Nothing was broken in the integration. The wiki simply had no way to say which pages were true.

Which spaces should you expose first?

Start from the job, not the tool. Write down the ten or so questions the agent must answer in its first role, then find where the authoritative answers live. That usually points to a handful of spaces, not the whole workspace.

Use this decision guide:

• Expose first: operating procedures, service descriptions, customer-facing policies and onboarding guides, each owned by a named team that still maintains them.
• Expose later, after review: project spaces, internal FAQs that mix audiences, and team handbooks with uneven quality.
• Never expose: HR, finance, legal, board material, personal or private pages, client-confidential notes, and any page where someone pasted a credential. Remove those credentials from the pages regardless of the agent.
• Leave out: archives, migrated spaces and anything with no owner. If nobody can vouch for a page, the agent should not speak for it.

Then shape the connection itself. Create a dedicated identity for the agent instead of borrowing a person's login. In Notion this usually means an integration that can see only the pages and databases explicitly shared with it. In Confluence it means a service user granted permission on the chosen spaces and nothing else. Make it read-only until the read path has proven itself. The reasoning is the same as in least privilege for AI agents: start with the smallest access and widen it deliberately. If you are choosing between a service account and delegated tokens, service accounts or OAuth tokens covers the tradeoff.

Audience matters too. If the agent serves staff, it may read internal procedures. If it serves customers, it must read only customer-safe pages, even though the wiki holds more. The [OWASP authorization guidance](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) is a useful reminder that access decisions belong in enforced permissions, not in a sentence in the prompt asking the agent to be careful.

How do you mark a page as approved?

Approval has to be visible in the page's metadata, so that a script or a retrieval filter can read it. A paragraph saying that the page is reviewed is not enough.

In Notion, a database with properties works well: a status property, an owner, an audience and a next-review date. In Confluence, labels and page properties do the same job: a label such as agent-approved, plus a properties block holding owner, audience and review date. The exact fields matter less than using the same ones everywhere.

A page qualifies as approved when it meets all of these conditions:

• It has a named owner who is still with the company and still responsible for the topic.
• It covers one topic clearly, instead of mixing a policy with commentary.
• It states its audience: staff, customers or both.
• It carries a review date that has not passed.
• Its owner applied the approved marker, not a bulk script and not the agent.

Two rules keep the system honest. First, an edit cancels approval. If a page changes after it was approved, it drops out of the agent's reach until the owner approves it again. Neither tool may do this natively in the way you want, so a small sync step that compares the last edit time with the approval time is a sensible safeguard. Second, review dates expire. A page past its date leaves the agent's sources automatically, which nudges owners to review instead of letting the wiki decay quietly.

This also shapes how the agent searches. In a retrieval setup (the [AWS overview of retrieval-augmented generation](https://aws.amazon.com/what-is/retrieval-augmented-generation/) describes the basic pattern), load only approved pages into the index. Filtering at ingestion is stronger than filtering at question time, because an unapproved page that was never indexed cannot be matched by accident.

How do you keep drafts out of agent answers?

No single control is enough. Layer several, so that one mistake does not become a wrong answer.

• Location: keep drafts in a separate space or section that the agent's account cannot see. This is the strongest layer, since it does not depend on anyone remembering a label.
• Status: anything without the approved marker is excluded, including pages marked in progress, proposal or archived.
• Published versions only: where a tool distinguishes an unpublished draft from the live version of a page, the agent reads the live version only.
• Freshness: pages past their review date are removed from the index.
• Answer behavior: every answer cites the page, its owner and its review date. If no approved page covers the question, the agent says so and routes it to a person instead of improvising.
• Content as data: text inside a page never changes the agent's rules, however it is phrased.

Conflicts deserve their own rule. When two approved pages disagree, the agent should report the conflict and name both owners, not choose silently. That turns a hidden wiki problem into a visible task for the people who can fix it.

Smaller is also better for answer quality. The [Anthropic guidance on context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) makes the case for giving an agent a tight, relevant set of information instead of everything available. A curated set of approved pages is easier to retrieve from and easier to audit than a whole workspace.

What is a safe step-by-step plan for the first connection?

Use this order. Each step has a clear output, and none requires rewriting the whole wiki.

• Step one: define the role and list the questions the agent must answer, with the audience for each.
• Step two: map those questions to candidate spaces and pick the few that have active owners. Write the excluded spaces down as well.
• Step three: add the approval fields (status, owner, audience, review date) to the chosen spaces and ask owners to approve their key pages. Approve a small core first.
• Step four: create the dedicated read-only identity and grant it only the chosen spaces. Store its credentials in a managed secret store, never on a wiki page.
• Step five: build the index from approved pages only, with a scheduled refresh that removes pages when their marker, review date or access changes.
• Step six: set answer rules: cite source, owner and review date, report conflicts, and decline when nothing approved applies.
• Step seven: test with real questions, including trick ones. Ask about topics that exist only in drafts, in excluded spaces and in expired pages, and confirm the agent declines each time.
• Step eight: decide what happens next. If the agent may ever create or edit pages, let it write only to a quarantined drafts area and require a person to approve, as described in where your AI agent should stop and ask.
• Step nine: run the connection through an acceptance checklist for AI agent integrations before anyone relies on it.

Illustrative check for step seven: a tester asks the agent about a leave policy that exists only as a draft in a private space. A correct result is a refusal with a pointer to the policy owner. A wrong result is a confident summary. Keep that test in the permanent set, so it runs again every time the setup changes.

What does ongoing upkeep look like?

A wiki connection is not finished at launch. Pages change, owners leave, spaces get reorganized and someone eventually moves a draft into an exposed space. Plan for these recurring tasks:

• Review the list of exposed spaces on a regular schedule and confirm each still has an owner.
• Check that the agent's permissions match the list, and remove any access nobody can justify.
• Re-run the draft and expired-page tests after any change to the wiki structure.
• Read a sample of real answers and compare them with the cited pages.
• Track questions the agent declined, because they show where the wiki has gaps worth filling.

Be Human handles this as part of designing and operating an agent's infrastructure. A first engagement defines the role, the spaces it may read, the approval markers and the success criterion. Managed operations then cover monitoring, recurring evaluations, integration maintenance and permission review, so the connection stays inside its boundaries while the wiki keeps changing. Your team keeps control of which pages are approved and what the agent may do with them.

Frequently asked questions

Do we need to clean up the whole wiki first? No. Clean up only the spaces the agent will read, and approve a small core of pages to begin with. The rest of the wiki can stay as it is, because anything unapproved is simply invisible to the agent.

Should the agent be allowed to edit or create pages? Not at the start. Begin read-only, and if writing becomes useful, limit it to a separate drafts area where a person reviews and approves every change. That keeps agent-written text from entering the approved set without a human decision.

Can we connect it with an employee's personal login to save time? It is better not to. A personal login carries all of that person's access, breaks when they leave, and makes it impossible to tell the agent's actions from theirs. A dedicated account with narrow, read-only permissions is easier to audit and to revoke.

What should the agent do when no approved page answers the question? It should say that it has no approved source, and offer to pass the question to the owner of the nearest relevant topic. A clear refusal is more useful than a plausible guess, and the logged refusals show which pages the team should write or approve next.

Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.