Bring your own AI agent

Overview

Agent access lets an admin “use agents to do their work” without Diligio running (or paying for) a second AI. Your agent calls a small, fixed tool set: it searches your knowledge base, reads projects and questions, writes answers it composed, moves questions through review, and (at the highest level) exports a finished project. Every call is authenticated, permission-checked, and written to the audit log.

• Two transports, one tool set. Connect over MCP (Claude Desktop, the Agent SDK, and other MCP clients) or over a plain REST API. Both use the same bearer token and expose identical tools.
• Off by default. Nothing is reachable until the Diligio team enables it for your workspace and the individual user opts in.
• Never more than the human. A token can never exceed the permissions of the person who created it, re-checked live on every request.

How it works

A token always acts as a specific person in your workspace. When a request arrives, Diligio hashes the token, looks up the live token row, confirms the workspace switch and the user's opt-in are both on, reads that user's current role, and then runs the requested tool through a database session bound to that user. The database enforces exactly the rows the human can see; the tool's own role rules apply on top. The agent supplies the answer text; Diligio only embeds the search query (cheap) and stores what the agent produces. No Diligio answer-generation happens on an agent call.

Turn agent access on

Two independent switches must both be on. This is by design: the workspace owner controls the capability, and each user controls their own tokens.

1. Per workspace

Agent access is off by default for every workspace. A Diligio team member switches it on for your workspace when you ask, and can switch it off again at any time as an instant kill switch: every token stops working immediately.

2. Per user (self-serve)

Once the workspace switch is on, every user sees an AI agent access card in their profile (Account Settings). It defaults to off. A user turns it on and mints their own tokens there. Turning their switch back off revokes all of that user's tokens at once.

Access levels & the RBAC ceiling

When a user mints a token they pick its level. The effective permission is always min(level, the user's live role) — the level can only ever narrow what the user can already do, never widen it.

• Live resolution. The user's role is read fresh on every request. Demote or offboard them and their tokens narrow or stop working on the very next call.
• Library-only users are pinned. A library_only account is forced to read-only no matter what level the token stored.
• Finalising is still admin-only. A “full” contributor agent can move a question to SME review but cannot finalise to Final, exactly like a human contributor. A full admin agent can.

Mint a token

In your profile's AI agent access card, create a token and choose its level. Diligio shows the full secret once — copy it then. We store only a SHA-256 hash, so we can never show it again; if it is lost, revoke it and mint a new one. Tokens look like this:

dgo_agent_<43 url-safe characters>

# example (do not use)
dgo_agent_K7m2xQ9...

Treat a token like a password. Anyone holding it can act as you, up to your token's level. Put it in a secret manager or your agent's credential store, never in source control.

Connect over MCP

Diligio exposes a Model Context Protocol server at https://www.diligio.co/api/mcp (Streamable HTTP, JSON-RPC 2.0). Point any MCP client at it with your token as a bearer header. For Claude Desktop, add a remote MCP server:

{
  "mcpServers": {
    "diligio": {
      "url": "https://www.diligio.co/api/mcp",
      "headers": {
        "Authorization": "Bearer dgo_agent_..."
      }
    }
  }
}

On connect, the client calls initialize and tools/list; Diligio returns only the tools your token's level grants. Your agent then calls them with tools/call. The same works from the Claude Agent SDK or any MCP-capable client — see the MCP section of the API reference for the raw JSON-RPC.

Connect over REST

If your agent is not MCP-based, the same tools are available as plain HTTPS. Start by confirming the token works:

BASE=https://www.diligio.co
TOKEN=dgo_agent_...

# Who am I, and what can this token do?
curl -s $BASE/api/agent/v1/me -H "Authorization: Bearer $TOKEN"

# List the tools this token's level grants (with input schemas)
curl -s $BASE/api/agent/v1/tools -H "Authorization: Bearer $TOKEN"

# Call a tool
curl -s -X POST $BASE/api/agent/v1/tools/kb_search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"data retention policy"}'

A worked example: answer a questionnaire

A “full” agent answering open questions in a project typically runs this loop. Notice the agent does its own writing — kb_search is grounding, and the agent must not invent facts beyond it.

BASE=https://www.diligio.co; TOKEN=dgo_agent_...

# a small helper so we don't repeat the headers each call
dgo() { curl -s -X POST "$BASE/api/agent/v1/tools/$1" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "$2"; }

# 1. Find the project
dgo list_projects '{}'

# 2. Pull the questions still being drafted
dgo list_questions '{"project_id":"<id>","status":"Drafting"}'

# 3. For each question, retrieve grounding...
dgo kb_search '{"query":"<the question text>","limit":5}'

# 4. ...your agent composes the answer from those hits, then writes it
dgo write_answer '{"question_id":"<id>","answer":"<text your agent wrote>"}'

# 5. Hand it to a human for review
dgo set_question_status '{"question_id":"<id>","new_status":"SME Review"}'

Answers written by an agent are flagged as agent-authored and enter the normal human review workflow — they are never silently published.

What an agent can do

The full tool set, and the level each tool needs. Read-only tokens see only the first row.

Each tool's exact input schema, an example call and its response are in the API reference.

Security & audit

• Hashed tokens. Only a SHA-256 hash is stored; the plaintext is shown once at creation.
• Trusted facts come from the token row only. Workspace, user and level are read from the database, never from the request body or headers.
• The database is the ceiling. The agent acts through a session bound to the human, so row-level security enforces the human's exact access. Capability checks and the existing role rules narrow from there.
• Everything is audited. Every agent action is written to the audit log with an “agent” actor type, the token id, and the self-reported agent label.

Revoke & kill switches

• A single token: the user revokes it from their profile; it stops on the next call.
• All of a user's tokens: the user turns their AI agent access switch off.
• The whole workspace: the Diligio team turns the workspace switch off.
• Implicitly: demoting or offboarding the user narrows or kills their tokens automatically, because the role is resolved live.

Troubleshooting

The complete status / code table and the MCP error behaviour are in the API reference. Still stuck? Email support@diligio.co.