NNextsAI Docs

Agents and Assistants

Connect local or SSH agents, create reusable assistant roles, and distinguish them from models and Bots.

Open: Settings → Agents or Assistants.

Configure an agent to change how tasks run. Create an assistant to give recurring work consistent instructions. Start with the built-in Nexts AI agent if you do not need an external executor.

Understand the four concepts

NameResponsibilityExample
ModelUnderstanding and generationChoose a model that accepts images
AgentExecution, model connection, and toolsNexts AI or an external CLI connected through ACP
AssistantReusable instructions and default capabilitiesReview documents against a fixed checklist
BotA persistent assistant spaceMaintain separate material, memory, and routines

External agents use their own supported authentication, models, and tools. Configuring a Nexts model does not sign an external CLI in. See Bots for persistent workspaces.

Use a local agent

  1. Open Agents → Local, find the agent, and inspect its installation and connection status.
  2. If needed, open its menu and use Install CLI or Install adapter when available. Check the target host and command in the confirmation. Follow the instructions for manually installed entries.
  3. Complete authentication or model configuration in that CLI, then return to Nexts.
  4. Select Test connection. Resolve authentication or connection errors shown in the details and retry.
  5. Select the agent and start a new conversation with a small read-only task, such as listing the project's top-level files and explaining their purpose.

Success: the selected agent returns a result in chat. A connection test checks the protocol handshake without creating a session or calling a model. A real conversation verifies authentication and model availability.

Add a custom or SSH agent

A custom configuration needs a unique ID, name, executable, arguments, and any required environment variables. Arguments are a JSON array of strings; environment variables are a JSON object of string values. Save and test the connection.

For SSH, first connect from a terminal using system OpenSSH and key authentication, and verify the host fingerprint. Enter the host, port, user, and an existing absolute remote working directory. Specify a private key path if required. Detection, installation, and agent execution then target that host.

Commands and paths belong to the remote host. This is separate from remote access, which lets a phone access your desktop Nexts.

Advanced JSON edits the full configuration and validates it before saving. Environment variables may contain credentials; do not share the whole file. Deleting a configuration removes the connection definition without uninstalling the CLI or deleting conversations.

Create a document review assistant

  1. Open Settings → Assistants, create a custom assistant, and enter a name and purpose.

  2. Describe its input, review scope, and output format:

    Review product documentation.
    Check that entry points, prerequisites, steps, and success criteria are clear.
    Report the location, problem, and suggested correction. Mark unverified features.
  3. Choose its agent, default tools, skills, memory scope, and approval mode as needed.

  4. Save, select the assistant in chat, and test it on a short document.

  5. Review the output, adjust its instructions, and verify them with a new task.

Copy a built-in assistant into a custom one to change read-only details. Role instructions do not install tools, authorize accounts, or activate a model service.

Collaborate with several assistants

In a custom assistant, choose the built-in Nexts AI backend and enable Multi-member collaboration. Select existing assistants or agents and assign responsibilities. Up to 12 members are supported, without nested groups. Address a member with @member, or let the current assistant coordinate assignments.

Test a small sequence such as research, review, and synthesis. Members retain task context within the current conversation, with separate contexts across conversations. This does not merge independent Bot memories.

Troubleshoot

SymptomNext step
Installed CLI cannot connectCheck authentication, executable, arguments, and adapter; test again
Handshake works but chat failsCheck the agent's own model, account, and quota
An expected tool is missingCheck assistant defaults, agent support, and the tool connection
Built-in role cannot be editedCopy it into a custom assistant
Approvals behave differentlyReview the current agent and chat permission mode

On this page