Skip to main content

Work With an AI Agent

An agent is an AI member of your project. Anyone on the project can @ mention it in a comment, ask it for a review or assign it a task, and it replies in the record's Activity.

One person sets up an agent, on an AI model they choose, and runs it. Everyone else on the project works with it the way they would with a colleague, with nothing to install.

Agents come with every paid plan. On the free plan, contact us to try one.

How an Agent Differs From Your AI Assistant

Your AI assistant and an agent both use an AI model to read and change your lab.

Your AI assistantAn agent
Where you talk to itIn the AI app's own chat, outside ConspectaIn comments on records in Conspecta
Who can ask itYouAnyone on the projects it's in
When it worksWhile you chat with itWhen the person who runs it starts it, by hand or on a schedule
Whose account it usesYours. History marks its changes "via assistant"Its own, shown with "(AI Agent)" after its name. History marks its changes "asked by" and the person who asked
What it can reachThe projects you choose when you connect itThe projects it's added to
How it connectsYou sign in from the AI app, or use a keyWith a key of its own

Use your assistant for your own questions and writing. Use an agent for work a colleague hands off on a record, such as a task on the Planner or a protocol to check. Connect your AI assistant covers assistants.

Ask an Agent for Help

Anyone on a project that the agent is in can hand it work in three ways.

ToDo this
Ask it something about a recordIn a comment in the record's Activity, type @ and its name
Have it check a recordAsk it for a review, as you would a teammate. It is listed under Agents, below your teammates
Hand it a taskAssign it the task on the Planner. It is listed under Agents in the assignee list

An agent answers a review with a comment. Only people can approve, request changes or reject.

Follow a Request

The agent's status shows in the record's Activity, and on the task on the Planner.

StatusWhat it means
"Waiting for" and the agent's nameQueued until the person who runs the agent starts it. Everyone else also sees that person's name
"Working"The agent is working on the request
"Needs your input"The agent asked you a question in a comment. You also get it in your inbox
"Finished"Done. A task goes back to whoever assigned it, with a comment, in the same column
"Couldn't do it"The agent stopped and posted the reason in a comment

When the agent asks you a question, answer with a comment on the same record. You don't need to @ it again. It picks the request back up the next time it runs. To ask for more after it finishes, @ it again in a comment on that record.

Cancel, beside the agent's status in Activity, withdraws a request that is waiting to start or waiting on your answer. The person who asked and the project lead can cancel.

Set Up an Agent

You set up an agent in a terminal or in your AI app's settings. Once it runs, nobody else on the project sets anything up.

Choose the Model It Runs On

An agent runs on an AI model you choose. What it reads from your projects goes to that model.

  • A model from an AI company, such as Claude, ChatGPT or Gemini, under your account with them. Check whether your institution has an agreement with one.
  • A self-hosted model, one your institution runs on its own servers. What the agent reads stays inside your institution. The app the model runs in has to connect to Conspecta with a key, as described in Which AI assistants work.

Create and Connect It

  1. Open Settings → Connectors and choose Agents. Give it a Name, such as Claude, and choose Add agent. The name is what people type after @.
  2. Copy the agent's key. It is shown once. If you lose it, Rotate key makes a new one.
  3. Add Conspecta to the AI app the agent runs in, using the agent's key. For Claude Code, run the command shown under the key. For another app, follow its steps in Use a key in your AI assistant with the agent's key.
  4. Add the agent to projects. In Settings → Connectors, under Your connections → Agents, choose Add to projects on its row. In a project you lead, you can also click the members button beside the project name to open Project Members, then choose Add agent.

In each project, the agent has the same access you have. If you can only view a project, the agent can only read it.

Run It

A request waits until you run the agent. Its row under Your connections → Agents in Settings → Connectors shows how many requests are waiting and when it last checked in.

  • By hand. In your AI app, say "Check Conspecta for requests waiting on you, and work through them." The agent works through what is waiting, then stops.
  • On a schedule. Send the app that same sentence at regular times, using your AI company's scheduled tasks or a computer your lab keeps on. How you set the schedule depends on the app.

Tip: Run an agent by hand for a week or two before you schedule it. You see what people ask it, and you can read each request before the agent starts.

Safety and Security

An agent follows the requests people write to it, including ones you haven't read. Anyone on its projects can write one, and a request can ask the agent to use anything it can reach.

Give a scheduled agent what its work needs, and leave out the rest.

  • Connections. Conspecta with the agent's key, plus the other tools and data sources its requests call for, such as a reference database or your lab's analysis scripts.
  • Data. Load the files its work uses into its workspace. Leave out anything you wouldn't share with everyone on its projects.
  • Ways to send data out. Add email, messaging or open web access only when its work needs them.
  • Where it runs. A workspace of its own, such as a separate user account, a virtual machine or your AI company's cloud workspace, so it reaches nothing else on your computer.
  • The key. Stored where only the agent's setup can read it.

Set up this way, a request can only make the agent use what you gave it, and history records every change it makes in Conspecta with who asked for it.

Stop an Agent

Your agents are listed in Settings → Connectors, under Your connections → Agents.

ToDo this
Pause itStop running it. Requests wait, showing "Waiting for" and its name
Take it out of one projectIn Project Members, remove it as you would a person
Replace a lost or exposed keyRotate key on its row. The old key stops working
Remove it everywhereRemove on its row, then confirm

The team Owner can turn off AI assistants, keys and agents for everyone with the Member role, with Use AI assistants and API keys on Roles and permissions. An agent a Member runs stops with them.