Agent PackagesNEW

Since v2.2.0, agents are the third Marketplace package type, next to skills and plugins. An agent package carries one agent: its persona files and a manifest. It carries no code, no tool list and no permissions. You install it from the marketplace or from a file, edit it like any other agent, and keep your edits when a new version comes out.

Agent packages need Sophon 2.2.0 or later and a marketplace that serves agents. An older Sophon never sees them: its marketplace search and installed list return skills and plugins only. A self-hosted marketplace older than the agent release shows no agents.

Installing an agentCopy Anchor Link

Every install shows the same preview before anything is created, whether it starts in the Dashboard, the CLI or a chat:

• the persona files, in full
• the result of the prompt-injection scan over those files
• the required skills, with each one's publisher and whether it is installed
• the tools the agent expects, and which are present, disabled or missing
• the settings the agent will get, and what Sophon turned off
• the agent id Sophon proposes

The package is staged for ten minutes while you review it. A High injection finding in Block mode refuses the install. See Prompt Injection.

Installing needs the ManageSkills permission. Whatever the manifest says, Sophon creates the agent with its heartbeat off, auto-approve and planning off, notifications on, no pinned model and no delegation allow-list. Turning the heartbeat's auto-approve or planning on later is your decision, and also needs ManageSkills.

From the DashboardCopy Anchor Link

• Agents → Browse marketplace opens Skills → Marketplace on the Agents chip. Pick a package to open its install dialog.
• Agents → Import package installs a .sophon-agent file. File installs work with the marketplace switched off.

Required skills are offered as a checklist in the install dialog. A skill from a different publisher than the agent's is left unchecked, because a dependency name can be taken by someone else.

From the CLICopy Anchor Link

sophon agents search research                          # marketplace agents (also: sophon skills search --type agent)
sophon agents install acme-research-helper --with-skills
sophon agents install --file ./helper.sophon-agent

--with-skills installs missing skills from the agent's own publisher only. Another publisher's skill installs only when you name it with --with-skill <name>. The command shows the preview and asks before it commits; -y skips the prompt.

sophon skills install <name> with an agent's name refuses with package_is_agent. Agents install from Agents in the Dashboard or with sophon agents install.

From a chatCopy Anchor Link

Sophon's model can find a marketplace agent when it needs a specialist: marketplace.search with type agent returns agents. If it asks to install one, the install raises an approval card that is never auto-approved, whatever your approval settings say:

• The card is High risk (Critical with a High scan finding) and carries the full persona as its preview.
• Approve only works in the Dashboard, and only after the deciding user opened the card's full preview. Approve is refused from chat channels such as Telegram and Slack, from the CLI, and from Mobile, which shows the card reject-only with "Review in Dashboard". Reject works everywhere.
• Each missing required skill gets its own card afterwards, also never auto-approved, marked when its publisher differs from the agent's.
• The install needs ManageSkills and a person as the source of the turn. A workflow, a schedule or an agent installed from the marketplace cannot install agents.

Editing and updatesCopy Anchor Link

An installed agent is yours to edit. Editing SOUL, VOICE, HEARTBEAT, TOOLS, the name or the description marks it customized. Settings such as the heartbeat schedule, the model or delegation are not content; changing them never pauses updates.

The Gateway checks marketplace agents in the same daily sweep as skills. A customized agent's updates pause until you review them in a three-way diff: your version, the published version you started from, and the new one. You take the new version, skip it, or keep yours.

Automatic updates are optional, per agent. With auto-update on, an update applies by itself only when none of these hold:

• it is a major version, or a minor version below 1.0
• the agent is customized
• the version was skipped, or is incompatible
• the scan found something
• the heartbeat is on and SOUL.md, HEARTBEAT.md or TOOLS.md changed
• the TOOLS.md pins or the required skills and tools changed
• a required skill would be missing

Every other update waits in the agent's Marketplace tab. Update all in Settings never applies agents; they update one at a time, from the agent's Marketplace tab, sophon agents update <id>, or the updates route with agentIds.

Withdrawn versionsCopy Anchor Link

When the version you installed is revoked or the package is removed from the marketplace, the agent stops: delegation, its heartbeat and the router refuse it, across restarts and while the marketplace is off. Sophon sends one security notification and the Dashboard shows a banner. The agent stays stopped until you choose Keep using or take another version.

The agent's Marketplace tabCopy Anchor Link

An agent installed from a package has a Marketplace tab in the Dashboard, showing the package, publisher, version and status, which files you edited, and:

• Review update, with the three-way diff
• Automatic updates: follow the global setting, on, or off
• Reset to published, which replaces your edits with the published files
• Detach, which stops update tracking
• Keep using, for a withdrawn version

A detached agent stays third-party. Only deleting it clears that status.

How Sophon treats an installed agentCopy Anchor Link

A package agent is third-party for its whole life, so its persona cannot buy itself more trust than you give it:

• Its turns are tainted (agent_persona), so no standing auto-approval covers them.
• Its heartbeat auto-approves up to Low risk, not Medium.
• Sophon's router never picks it on its own. Choosing it yourself and delegation to it still work.
• It cannot install agents.
• Its agent.create and agent.update calls, and any agent.update that gives it heartbeat autonomy, are never auto-approved.
• agent.list shows its source, version and status.

File tools cannot read or write the folders where Sophon keeps agents and marketplace copies (<dataDir>/agents, <dataDir>/marketplace, and also <dataDir>/vault and <dataDir>/security). An agent or workflow that edited SOUL.md through fs.write must use agent.update or the persona routes instead. Shell tools are not covered by this rule; the approval card for a shell command is the control there.

Export and publishCopy Anchor Link

Any agent you built in Sophon can become a package:

• Export. Agent → Export as package, or sophon agents export <id>, downloads a .sophon-agent. The exporter writes the manifest, drops the fields a package cannot set, and takes the required tools from the TOOLS.md and HEARTBEAT.md pins.
• Publish from Sophon. Agent → Publish to Marketplace, or sophon agents publish <id>, uploads it through your linked marketplace account. Publishing needs a link that allows publishing: Settings → Marketplace, allow publishing, with a fresh marketplace login. A publishing link expires after 90 days. A link made before 2.2.0 is review-only, so re-link it.
• Publish with a key. sophon dev publish --key smk_… uploads any package type with a publish-scoped API key.

Publishing someone else's agent needs an acknowledgement that you have the right to, a different name, and keeps the original LICENSE. Text that looks like a credential needs an explicit acknowledgement first. Every new version lands in review; an agent version is approved only when each required skill exists on the marketplace at the required version. See Publishing Packages.

The package formatCopy Anchor Link

A .sophon-agent is a zip with root-level files only, with exactly these names:

Limits: at most 16 entries, 64 KiB per file and 512 KiB in all uncompressed, and a compressed archive of at most 1 MiB. Every file is UTF-8 text. No folders, no __MACOSX/, no .DS_Store, no encryption.

{
  "type": "agent",
  "schemaVersion": 1,
  "name": "acme-research-helper",
  "displayName": "Research Helper",
  "version": "1.2.0",
  "description": "Searches, reads sources and writes a cited summary.",
  "author": "Acme",
  "license": "MIT",
  "category": "data",
  "agent": { "whenToUse": "Pick this agent for multi-step research that needs cited sources." },
  "requires": {
    "skills": [{ "name": "web-search-pro", "minVersion": "1.0.0" }],
    "tools": ["web.search", "memory.write"]
  },
  "defaults": {
    "heartbeat": { "intervalMinutes": 1440, "activeFromLocalTime": "08:00", "activeToLocalTime": "18:00" },
    "subAgents": { "enabled": true, "maxDepth": 3 },
    "modelRouting": { "mode": "auto", "profile": "quality" }
  },
  "sophon": { "minVersion": "2.2.0" }
}

• name is the package slug and the agent id Sophon proposes on install. Some names are reserved.
• version is SemVer and must grow with every publish.
• agent.whenToUse is what Sophon's model reads when it looks for an agent to delegate to, and what marketplace search weighs.
• requires.skills names marketplace skills the agent needs, at most 16. Nothing installs without the person's consent.
• defaults are applied once, at install. After that the settings belong to the user, and updates never change them.

What a package cannot set. Autonomy and credentials are the user's decision, never the author's. The marketplace refuses, and Sophon strips on install, the heartbeat's enabled, autoApprove, allowPlanning, model and notifyOnAction, a delegation allow-list, and a pinned model. Skill manifest keys (runtime, entrypoint, tools, permissions, pluginInterface) are refused too.

Authoring a package projectCopy Anchor Link

sophon dev new agent acme-research-helper --author "Acme"   # writes the package files
cd acme-research-helper
sophon dev validate                                         # errors, then publish issues and warnings
sophon dev build                                            # dist/acme-research-helper.sophon-agent
sophon dev install                                          # installs it through the running Gateway
sophon dev publish --key smk_…                              # uploads it to the marketplace

sophon dev new agent <name> --from-template research-analyst starts from one of the bundled agent templates. sophon dev install imports the package through the running Gateway, so the agent gets the same review as a Dashboard import; start the Gateway with sophon start or set SOPHON_GATEWAY_URL.

DevStudio 1.1.0 and later open the same project. DevStudio before 1.1.0 opens an agent package project as a skill and builds the wrong package, so update DevStudio together with the CLI.

Tenancy and permissionsCopy Anchor Link

Since v2.2.0:

• Every /api/agents/{id} route checks the caller's tenant and answers a bodiless 404 for another tenant's agent. Changes need ManageSkills.
• Cross-tenant delegation is blocked on Pro and Enterprise. Delegation, the agent tools, graph agent steps, session binding and the router resolve agents in the caller's tenant only. A workflow that named another tenant's agent id stops working; recreate the agent in the tenant that uses it.
• Turning a heartbeat's autoApprove or allowPlanning on needs ManageSkills, at create time too. Turning them off, and editing persona files, stay open to tenant members.
• Saving a persona file over someone else's edit is refused (agent_content_changed).

Upgrading to 2.2.0Copy Anchor Link

• DevStudio 1.1.0 or later for agent projects.
• Migrate legacy agent.json projects before you build or publish them.
• Approve agent installs in the Dashboard. Mobile, the CLI and chat channels can only reject them.
• Re-link the marketplace account in Settings → Marketplace to publish from Sophon.
• "Update all" skips agents. Update them one at a time.
• One-time prompt-cache miss. With the marketplace enabled, the descriptions of agent.delegate and tools.search gain one sentence each that points the model at agent search, so every chat's prompt cache misses once after the upgrade. A host with the marketplace off is unchanged.
• File tools cannot touch Sophon's data folders. Move any fs.write of SOUL.md to agent.update.

LimitsCopy Anchor Link

• An installed agent cannot become a local agent again; only deleting it clears its third-party status.
• A chat with a marketplace agent is tainted, so accept-edits, command rules and network rules do not cover its calls, even in a trusted workspace.
• A shell command a person approves can still write the protected data folders; the approval card is the control.
• A Gateway before 2.2.0 runs installed package agents as ordinary local agents, without these trust rules. Delete package agents you do not trust before you downgrade.
• No update telemetry is sent. Marketplace installs report only installed and uninstalled.

Where to go nextCopy Anchor Link

• Installing Packages — the install pipeline for every package type
• Publishing Packages — names, versions and review
• Agents & SOUL — what an agent is, and its persona files
• Heartbeat — what an agent does on its own schedule