Working with your agent

The heart of biopb is the conversation with your AI agent. This page covers what that feels like and how to get good results.

Workflow

1. Open your agent app. This is the chat interface to talk to your LLM agent, e.g., Claude Code, opencode, etc. From there, the agent can launch biopb the first time it needs it, which opens a napari window.
2. Ask in plain language. Describe the data and what you want done with it.
3. Watch it happen. The agent writes and runs code; image results appear as layers in napari, and numbers and tables come back in the chat.
4. Iterate. Adjust a layer by hand, ask a follow-up, or refine the analysis. The agent sees the current state of the viewer and continues from there.

The agent works by a perceive → act → verify loop: it runs code that changes the viewer, then looks at a screenshot to confirm the result actually looks right — the same way you would.

What LLM should you use?

If the agent workflow is new to you, you should first check what LLM you are using. In opencode (and many other agent tools), you type:

/model

to see current and other available models.

Use a frontier model or not

Frontier models such as Anthropic's opus can consistently handle more complicated tasks, but you don't necessarily need them. We routinely run benchmark tests against smaller models. Two low cost models stand out as being very competitive:

• deepseek-v4-flash: an open-weight model available through many providers
• gpt-5.6-luna: the little brother of OpenAI's famous gpt series models

Adding plugins

You can extend your agent's ability by giving it new python modules to use.

Drop a .py file into ~/.config/biopb/kernel/. Every file there is loaded at the start of each session and bound as one module named after the file — rolling_ball.py becomes rolling_ball, and the agent calls its functions as rolling_ball.subtract_background(...). The installer seeds a worked example at that path, rolling_ball.py, and never overwrites your edits, so open it to see the shape of one.

Write the module docstring for the agent. It is what the agent reads when deciding whether your plugin is relevant to the task at hand — the file is parsed for it, never imported — so say what the module is for and what each function does:

"""Ratio two channels, masking out the background.

- `ratio(num, den, thresh=None)` — per-pixel num/den as float32, NaN wherever
  `den` falls below `thresh`.
"""

def ratio(num, den, thresh=None):
    ...

Check that it loaded. Ask your agent to run server_status and look at its Kernel plugins section, which lists what actually loaded. The loader is fail-open per file, so a .py sitting in that directory but missing from the list failed on load, and the session log says why. You can also see the list of plugins in the biopb dashboard.

What to ask for real

Some examples to get a feel for it:

• "Open embryo.nd2, show channel 2, and max-project over Z."
• "Segment the nuclei in the current image with Cellpose and count them."
• "Measure the area and mean intensity of each segmented cell and give me a table."
• "Threshold the membrane channel, clean up small objects, and overlay the result."
• "Connect to the tensor server at grpc://lab-data:8815 and list what's available."

Tips

• Name your files and channels. "the DAPI channel" works better than "the blue one."
• Work in steps. Ask for one transformation, check it, then build on it.
• Let it see. If a result looks off, ask the agent to take a screenshot and re-check — it often catches and fixes the problem itself.
• Point it at the right data. If your images live on a remote server, add that server as a source once — see Connecting to a server someone else runs — and its catalog is there for every session after.