Document a mental model for "what is a persona?"

[mfisher87]

I wasn't sure what kind of issue to open -- this isn't really a feature for the project, more of a feature for the docs. And "blank issue" said "maintainers only" so I didn't do that. Anyway :)

Problem

Before thinking about "how do I make a persona?" I'm asking myself "do I want to make a persona?" and not finding a clear answer in the docs. I'm putting the pieces together by reading the "how to make a persona" docs, and that's hard -- the puzzle pieces are given to me slowly and it's hard to keep them all in my head in a clean mental model.

I also am coming in to this with a pre-existing mental model for the word persona from project management. In that space, a persona is a fictional user type (often with a real person as a proxy) like educator, student, glaciologist without a software engineering background, local government decision-maker without a science background, etc. And that pre-existing mental model causes me to think a "persona" is somehow related to the concept of "skills" (in the LLM sense). But I think that's wrong, or at best incomplete.

Proposed Solution

Create a dedicated page in the user guide for personas. They're a high level concept of jupyter-ai so I think it's important to provide a mental model. I would want to know:

• Is a persona a set of skills? (could be?) Would I want to build e.g. a "GeoJupyternaut" 🙃 that knows about e.g. cloud native geospatial data formats? Is there a way to share skills between personas?
• Is a persona a specific model? Jupyternaut can be configured to a specific model, so that persona is coupled to that choice. Is that the case for all personas? (no)
• What kind of cool things could I do if I made a custom persona?
• How does the "persona" metaphor work? Is it just that the thing can be @ mentioned and has an avatar and behaves like a collaborator in the chat, or does it go further?
• ?

Additional context

I'm just getting started with JupyterAI 3.0 so I'd appreciate feedback about how to best channel my "new user" feedback. I don't want to put things in the wrong place, but this feels right because it's a concrete request instead of a question 🤷

[dlqqq]

This is great feedback, thank you. 100% agree this is something we can elaborate upon more in the documentation.

Personas are named entities that can be @-mentioned in the chat, which can reply in the chat when @-mentioned. So personas can be anything from:

• Bare LLMs (no ability to run tools),
• General-purpose agents (like Claude, Kiro, etc.),
• Specialized agents (e.g. an agent that helps manage a Kubernetes stack),
• Multi-agent managers/orchestrators (no demo yet, but this is WIP),

Jupyter AI allows for you to engage with any of these personas simultaneously in the same chat, which is unique with respect to other IDE-native AI assistants.

Happy to review any PR if somebody else would like to pick this up.

[dlqqq]

We are still exploring and imagining the possibilities just like our users are, so this list shouldn't be taken as complete :)

[cboettig]

Thanks for this clarification but I am having trouble squaring it with the documentation and what is currently implemented. It appears that currently @ personas correspond specifically to "harnesses" -- like claude code cli, opencode, etc, all of which are specifically multi-model interfaces.

I really like that Jupyter-ai v3 is wrapping around existing harnesses like opencode rather than merely having a competing jupyter-specific harness (as we had with jupyter-ai v2). Existing harnesses already bring a lot to the table, including well-defined semantics for configuring access to a wide range of LLM models and providers.

However, I think the UI semantics of "persona" are deeply confusing in the current framing for a whole range of levels. For one, all of the harnesses jupyter-ai currently wraps like opencode and claude code already use the @ and / commands to provide huge set of critical functionality that is both mechanically lost in the current interface (there is no way I can see to invoke the claude-code's / , @ commands from jupyter-ai's binding), and semantically different. Also, the UI is confusing, most users will associate @Claude as meaning a command that is sent to a Claude model. But that is not the architecture implemented here -- it sends it to the claude-code harness, which can actually be configured to talk to a wide range of models (just like @OpenCode in jupyter-ai isn't a model, but a harness that could be configured to talk to Claude or just about any other model).

It seems like a much more natural approach here would be to allow the user to simply configure their harness as a setting in jupyter-ai config and then pass-through the @ and / commands, and leverage the existing multi-agent and multi-model support already in the harnesses jupyter-ai is already wrapping around. Does that make sense?

[srdas]

@mfisher87 @dlqqq @cboettig, awesome discussion! Part of the excitement of the v3 launch!

IM(strictly personal)HO (sic), "Persona" (Latin for the mask worn by an actor) is an excellent word to describe a human or AI acting in the chat panel. Some blue-sky thinking: The idea of a single chat thread in which humans and AIs interact through their personas (named entities) is extremely appealing in a world where real-time collaboration (maybe) becomes the norm. These interactions can be peer-to-peer (human with human, human with AI, and of course, even AI to AI). The interactions can also be based on principal-agent relationships (agentic hierarchies). Another cut on personas is that they are very general and can use and deploy LLMs, harnesses, agents, tools, skills. While the current instantiations of personas may seem to be single harness-focused (Jupyternaut is not) and not interactive as described above, the term Persona suggests a lot more, all of which is possible to envisage, so I guess I am arguing for keeping the term as it is broader and forward-looking in scope, while we all make the semantics clearer as we work to document and build out more functionality.

The good thing is that anyone can build a persona and it behooves the builder to make sure what it does is clear, so that semantic ambiguity is minimized. And of course the implementation of existing harnesses through personas can always be improved (point well taken and future PRs on this will surely help). But it's also good to avoid making the definition of Persona purely harness focused. There are many ways in which the flexibility of building personas in Jupyter AI can be exploited. For example, you can BYOP like this one: https://github.com/srdas/jupyter-ai-quickagent/tree/main, and create similar ones for personal use. Maybe we can have a persona marketplace ... but I am getting ahead of myself here.

[cboettig]

Thanks @srdas ! It's slowly clicking for me. What you say makes a lot of sense, and I have a much better grasp of ACP now than I did. I think you are 100% right on about writing custom personas. 🤯

To make this a bit more concrete: @mfisher87 + I have this "proto-persona" that is an external (http) MCP server (that defines resources -- a list of datasets it knows about, a handful of tools, and a geospatial-analyst "prompt", along with a handful of local skills (mix of SKILL.md + local scripts or (stdio mcp) tools for common geospatial tasks. Since most 'harnesses' understand both the agent skills and MCP standards, this is is reasonably portable to users that use claude code, and users that prefer opencode.

It sounds like the right mental model then is that we should wrap all this up behind a single persona abstraction, an @geoagent, instead of trying to use it in jupyter-ai via @Claude or @opencode? But then I would be hard-wiring choices about what harness (which is essentially, what payment plan) a user is using, which feels like it should be entirely orthogonal question. Our current setup is agnostic to whether a user has an anthropic subscription and thus must use only claude code to avoid the high fees of the API route imposed on third-party harnesses, or whether they are an open-model-lover and want to use opencode, right?

Also, it seems that some aspects of the CLI then need to still be re-implemented in Jupyter-AI that aren't there, e.g. we have @file but we don't have model switching or effort switching etc within a persona?

[mfisher87]

Personas are named entities that can be @-mentioned in the chat, which can reply in the chat when @-mentioned.

This is helpful, and I think it's useful to be explicit that this is the extent of the metaphor -- it's not coupled necessarily to other concepts like specific skills or models, i.e. a persona could use multiple models or learn new skills at runtime.

To make the concept of "personas" useful to users though, not just developers, I think personas shouldn't be a thing you must install, but a thing you may configure in the UI at runtime, and take that configuration with you to other deployments (or publish for others to install the same persona). The Python classes that define personas now should IMO be defined as a more generic and configurable thing than "Persona". "Archetype"? I don't know. Like a thing a user can instantiate, like a "class", to create their own personas.

For example, I want to be able to have a Claude-Sonnet and Claude-Opus persona in the same chat, and I want to be able to set that up myself out of the box instead of writing code! I think right now the way I change models with the @claude persona is to open the claude CLI then run /model. And then the @claude persona changes models? I'm not sure. It's coupled directly to the Claude Code harness as far as I can tell.

I might want to have a "reviewer" persona, and maybe I start by copying my Claude-Sonnet persona and add a system prompt or skill in the UI. Then when I'm ready for a review I could do @reviewer, do your thing and it knows what to do because that's baked in to its persona that I designed.

Then I might make a copy of Claude-Opus persona and give it a system prompt or skill to make it a "researcher" persona. And then I could prompt the "researcher" and "reviewer" personas to chat with each other, something like:

You're a reviewer and you review code. When you're @'d in chat, you review the most recent changes for X, Y, Z properties, and you care the most about property Y. When you're unsure about whether some code is idiomatic, send a message to @researcher and ask them to research that while you continue reviewing before commenting on that aspect of the code.

[cboettig]

I've looked into this a lot more and I am worried we are conflating two things both called ACP. there is "Agent Client Protocol" which Jupyter-AI is using currently to bind to different harnesses, developed by Anthropic and Zed (an IDE much like juypter) and others to avoid 'plugin explosion' where each harness needs not only a TUI but a GUI plugin.

This is entirely unrelated to IBM's ACP, the Agent Communication Protocol, that is now folded under the banner of "agent2agent", A2A. A2A sounds a lot like the notion of "personas" here, and I agree it is an interesting blue sky idea. But it is deeply different from Agent Client Protocol -- which is also needed here and solves the simpler, more straight-forward problem.

Jupyter-AI v3 is currently written as an Agent-Client-Protocol (ACP) Client -- which can already talk to any ACP-compliant harness (opencode, claude code, github copilot, gemini-cli, codex, goose, etc). That's great. But these should not be seen as "personas". That's an orthogonal issue! The choice about harness to first order can be seen much more as a choice about price mechanism than anything else -- if I access Claude via GitHub Copilot (e.g. via the free educational account), vs if I access Claude with a subscription (which requires I go via the claude harness) vs if I access claude via API (any harness, e.g. openrouter).

This really clicks for me looking at the Zed IDE, screenshot below, who were closely involved in creating the ACP that Jupyter-AI v3 is using:

Note the user interface. The top-left shows the currently active "Agent" (Claude Agent here, i.e. claude code harness), while the right hand menu you see the selector for all the "ACP Registry". Note that these are not "Personas", they are all general-purpose harnesses. Note also on the bottom left -- we retain the selectors for model (sonnet, opus, haiku with the Claude client), the selector for effort, and a selector for controlling the auto-approve behavior -- all essential toggles that are currently lacking in jupyter-v3 but would be natural to add.

I think it is mistake of type to tell users to essentially wrap an existing harness to provide a custom "Persona" (say, the "geospatial agent"). That's what the IBM ACP -- Agent-communication-protocol -- now called A2A is for. It's a different standard entirely, (very confusing!) and doesn't lock us in to picking a harness when we try and extend a persona. A2A is much more aligned with the vision @srdas describes. Jupyter-AI v3 can first do zed-style ACP, (which should be a configuration, not a @ toggled feature), and then (optionally) allow users to extend with A2A in whatever harness they are using.

But for now, @ should not be used to select harnesses, and these shouldn't be called personas. -- I don't think there's a use case for actively working a single task simultaneously with the gemini cli and the github copilot cli and claude cli, all of which already do much the same thing and access much the same list of models but just have different billing infrastructures.

[cboettig]

@dlqqq I think this is deeper than a documentation problem, but maybe you can clarify?

As currently implemented, a Persona is one of two classes: a BasePersona, or a BaseAcpPersona.

I think a BasePersona is essentially inherited from jupyter-ai-v2, and seems to be what you refer to as a "Bare LLM", yes (i.e. the jupyter-ai-jupyternaught)? While one could obviously extend this class to make more specialized Personas would it be fair to call this a legacy/escape hatch?

Then there are the BaseAcpPersonas, which connect to existing 'general-purpose-agents' -- that is, harnesses, like claude code, opencode, goose, codex-cli, gemini-cli, or github-copilot-cli.

I think it is absolutely wonderful that JupyterAI supports ACP and connects to these existing harnesses rather than reinvent the wheel. They not only remove the problem of how to connect to a model (including being the ONLY option now to connect to, say, Claude via a subscription account, since all third-party harnesses have been banned), but also give substantially better user experience than going to a 'bare LLM' with no local tools.

However, I think it is a substantial design bug to (1) use ACP as a conceptual model to try and support a multi-agent workflow in a single chat. I also think it is a mistake to (2) use ACP as the mechanism to support creating more specialized agents. I'd be happy to open up separate bug reports for each of these if that makes sense?

On 1: The conceptual idea of being able to interact with multiple distinct agents in single 'thread' of discussion, using @claude and @gemini and @mySqlAgent and @myOtherAgent in the same thread makes sense, but attempting to do this with ACP -- with separate harnesses -- does not. Mechanically, while appearing in a common window, the execution of each occurs in an isolated harness because that's how BaseAcpPersona is defined, (or just as bad, with no harness if we use @BasePersona), so there is no shared context or shared cache. Further, this interface confuses model selection with harness selection -- you don't change your harness just to change your model.

On 2: to extend an agent into specialized agent, we have to extend a specific harness (i.e. lock our users into claude -- less bad if we choose an open harness like langchain deepagents or opencode, but still not ideal), or worse still, write our own harness.

[mfisher87]

We chatted about this today in the Jupyter AI call. DM'd the notes to Carl :) I'm not sure what the etiquette around sharing the notes in public spaces is :) cc @dlqqq

[dlqqq]

Hey, thanks for starting this thread & for being so engaged with it! Was busy with planning the Jupyter AI roadmap (hope to share details in the next next call on 5/13). Taking a look now.

[dlqqq]

Thanks so much for the thoughtful discussion here, @cboettig and @mfisher87. I want to address each of the key points raised:

"persona = harness" abstraction is confusing

I hear the concern, but I think exposing harnesses as personas by default is the right call for usability. Many users just want to use an agent out of the box with zero configuration. This is what Zed offers - you install Claude and can then chat with "Claude" as an agent, even though it is technically an agent harness. If we removed this mapping, a user would need to manually define a persona, pick a harness, and configure a model before they could do anything. Displaying harnesses as ready-to-use personas is a good first step and I don't think we should revert that.

We're not trying to narrow / change the definition of a persona into being just ACP agent harnesses. ACP integration was the fastest way to make frontier agents available to our users and solve the "I want general AI help in Jupyter" problem as the first step of Jupyter AI v3.0. Our conception of the persona abstraction and the possibilities it unlocks have not changed at all -- we built a very general architecture that also allows you to create your own specialized agents at varying degrees of complexity, and we plan to improve that moving forwards.

Harness commands (/, @) are not fully available

This is true, and it's a limitation of ACP agent compatibility at this stage. We do surface slash commands for ACP agents (type / after mentioning a persona), but we can only show what the agent returns — and most agents currently return a limited set (3–6 commands at most). We expect this to improve as ACP matures and agents expose more of their capabilities.

ACP is the wrong model for multi-agent workflows

I agree — and want to clarify that multi-agent orchestration was never the goal of ACP. The goal of ACP in Jupyter AI was to provide compatibility with the many excellent agent harnesses that already exist, rather than reinventing the wheel. Multi-agent workflows are a new frontier we're actively exploring, and I'll be sharing details on our roadmap during the 5/13 call.

ACP agents not sharing context

This is a real limitation, and we're aware of it. ACP currently expects each chat to be dedicated to a single agent, which Jupyter AI challenges by design. There's no general mechanism in the protocol for sharing context between agents yet. We are actively working on this, but it's not well-supported at the protocol level today.

ACP is not a good way to implement custom personas

To clarify: ACP is not forced on every persona. Our technical definition of a persona hasn't changed since we began Jupyter AI v3 development. Each persona is an instance of BasePersona, whose core interface is the process_message() method. BaseAcpPersona simply inherits from BasePersona and provides a convenient implementation that works out of the box if you define how to start the ACP subprocess. You are still absolutely free to create a custom persona without using our ACP library — just subclass BasePersona directly.

It's not clear what ACP means

We do specify that we're using the Agent Client Protocol (Anthropic/Zed) and not the now-defunct Agent Communication Protocol (IBM). But if you feel additional clarification would help — especially for newcomers encountering both terms — I'm happy to review any PR that improves this.

---

Where we're headed

Overall, I'm in strong agreement that we need to:

1. Make it easier for people to create their own personas — ideally without writing code.
2. Better support multi-agent workflows in Jupyter AI.

There are some deep technical questions to work through, but both of these are firmly on our roadmap. I'll be presenting more details on the 5/13 call.

That said, I do think we'll continue exposing harnesses as personas. In practice, most users just want to use Claude Code or OpenCode — they don't care about the semantic distinction between an "agent" and an "agent harness," and I don't think we should ask them to. The abstraction serves them well as-is, and we can build richer persona capabilities on top of it.

Thanks again for pushing on this — it's making the project better. 🙏