Agent plugins

Add an Agent Plugins 1.0 package to plugins/ to share skills and MCP servers across managed ADK and LangGraph agents. Harnest discovers its declarations automatically. Advanced applications must wire these capabilities themselves.

Need Python APIs, SDK dependencies, typed context, or lifecycle behavior? Build a Harnest Extension in extensions/. Application hooks and resource factories belong in lifecycle/.

Add a plugin

From the agent folder, install a reviewed local package into the project:

harnest plugins install ../downloads/warehouse

Harnest validates the manifest without running package code and copies it into plugins/<manifest-name>. Links and special files are rejected. Use --force to replace an installed package; a failed replacement restores the previous version. The installer accepts local directories. Use harnest extensions search to discover executable Harnest Extensions. Place each package in its own directory. Keep the package’s root plugin.json intact:

plugins/
└── warehouse/
    ├── plugin.json
    ├── mcp.json                 # optional
    └── skills/                  # optional
        └── query-warehouse/
            ├── SKILL.md
            └── references/     # optional

plugins/warehouse/plugin.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "warehouse",
  "version": "1.0.0",
  "description": "Query the shared warehouse"
}

The manifest requires the canonical $schema shown above and a name. That name identifies the plugin, even when its enclosing directory has a different name. Both component locations are optional: a skills-only, MCP-only, or manifest-only package is valid. Plugin skills join the agent’s skill registry and load on demand through list_skills, load_skill, and load_skill_resource. Plugin MCP servers join direct connections from mcp/. Use a skill to explain when to call its tools, which inputs they need, and how to interpret their output. Rebuild after adding a package, or use development reload while serving locally.

Attach a plugin after compilation

Agent Desktop can attach plugins when creating a session. The desktop downloads the package and sends Harnest a ZIP with plugin.json at its root.

POST /sessions

{
  "id": "desktop-session",
  "plugins": [
    {
      "type": "inline",
      "name": "warehouse",
      "sha256": "<64 lowercase hexadecimal characters>",
      "source": {
        "type": "base64",
        "media_type": "application/zip",
        "data": "<base64 ZIP>"
      }
    }
  ]
}

An optional sha256 must match the decoded ZIP. Harnest returns each plugin’s name and computed digest in metadata.plugins, and stores the archive privately with the session for restart recovery. The plugin set is fixed when the session is created. Create another session to add, remove, or update a plugin. Dynamic attachment currently requires a managed root Agent; managed Graph and advanced applications retain their compiled capability wiring.

Dynamic package content	Runtime behavior
Agent Skills	Added to the session’s progressive skill tools
`streamable-http` or `sse` MCP	Added to that session’s ADK or LangGraph target
`stdio` MCP	Session creation fails because the package could execute code in the Harnest process

Harnest accepts at most 16 plugins per session and regular files only. It rejects encrypted members, links, absolute or parent paths, case-insensitive path collisions, more than 256 files, files larger than 4 MiB, archives larger than 8 MiB, and expanded content larger than 32 MiB. The server’s configured limits.max_request_bytes also applies to the base64 JSON request and may impose a lower effective limit.

Treat the URL as untrusted input in Agent Desktop. Apply download timeouts, redirect and credential policy, and archive size limits before sending the snapshot. Do not forward a URL for Harnest to fetch.

Configure MCP servers

Portable MCP declarations live in root mcp.json, not Python factories. Each server declares its transport explicitly:

plugins/warehouse/mcp.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "warehouse": {
      "type": "streamable-http",
      "url": "https://warehouse.example.com/mcp",
      "headers": {"X-Tenant": "public-demo"}
    }
  }
}

Transport	Configuration
`stdio`	`command`, optional `args`, `env`, and `cwd`
`streamable-http`	`url` and optional `headers`
`sse`	`url` and optional `headers`; for legacy HTTP+SSE servers

MCP connections open at runtime; compilation does not start servers.

Local processes and persistent data

For a package that includes server.py, a stdio declaration can use:

plugins/warehouse/mcp.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "warehouse": {
      "type": "stdio",
      "command": "python",
      "args": ["${PLUGIN_ROOT}/server.py"],
      "env": {"CACHE_DIR": "${PLUGIN_DATA}"},
      "cwd": "${PLUGIN_DATA}"
    }
  }
}

Install the server and its dependencies separately. command must be an executable name or a bundled path beginning with ./, not a shell command.

Variable	Harnest value
`PLUGIN_ROOT`	Absolute package directory; use it for bundled files
`PLUGIN_DATA`	Writable persistent directory dedicated to this installed plugin; use it for caches and state

Harnest supplies both variables to each stdio subprocess. Persistent data lives below $XDG_DATA_HOME/harnest/agent-plugins, or ~/.local/share/harnest/agent-plugins when XDG_DATA_HOME is unset. Set HARNEST_PLUGIN_DATA_DIR to override that base directory. Harnest separates data by installation and plugin; package updates do not erase it. Only ${PLUGIN_ROOT} and ${PLUGIN_DATA} expand, and only in stdio args, env values, and cwd. Other placeholders stay literal. Do not override the reserved variables in env. An omitted cwd uses the package directory. An explicit cwd must start with ./, ${PLUGIN_ROOT}, or ${PLUGIN_DATA} and remain inside the corresponding directory after resolution.

A plugin subprocess runs executable code with the server process’s permissions. Package-path validation does not sandbox that process. Review packages before adding them.

Remote connections and credentials

Remote URLs require HTTPS except for loopback hosts. URL and header values are literal: ${TOKEN} does not read an environment variable. Do not embed secrets in plugin headers or stdio environment declarations. MCP HTTP clients use the process’s HTTP(S) and ALL_PROXY variables, including SOCKS proxies. Remove those variables to bypass proxy discovery. Diagnostics omit proxy URLs and credentials. Authentication is client-managed; Agent Plugins 1.0 does not define portable credential references or OAuth configuration. When your application needs custom credential resolution, configure a direct MCP client with Harnest’s credential providers.

Validation and diagnostics

Harnest validates the manifest before discovering components. An invalid manifest rejects that plugin. Invalid skill entries or MCP server entries are skipped with diagnostics while valid siblings continue loading. An invalid mcp.json disables that plugin’s MCP component without disabling its skills. Unknown client namespaces and their directories are ignored. Standard plugins cannot contribute Harnest lifecycle hooks or arbitrary Python modules.

Author Agent Skills

Write focused instructions and load supporting resources on demand.

Build a Harnest Extension

Package Python functionality, lifecycle behavior, and typed context.

Overview

Get started

Harnest Studio

Guides

API reference

Agent plugins

Add a plugin

Attach a plugin after compilation

Configure MCP servers

Local processes and persistent data

Remote connections and credentials

Validation and diagnostics

Author Agent Skills

Build a Harnest Extension

​Add a plugin

​Attach a plugin after compilation

​Configure MCP servers

​Local processes and persistent data

​Remote connections and credentials

​Validation and diagnostics

Author Agent Skills

Build a Harnest Extension

Add a plugin

Attach a plugin after compilation

Configure MCP servers

Local processes and persistent data

Remote connections and credentials

Validation and diagnostics