Agents#

Compose multiple tools behind a single agent manifest.

What is an “agent”?#

An agent is a composition layer: it declares which tools it can call. The agent manifest doesn’t execute code itself—it enumerates tools (with versions) so the SDK/CLI can resolve, install, and expose those tools to your agent runtime.

Defines capability surface by listing tools the agent may invoke.
Drives deterministic installs via agent.lock (exact versions + checksums).
Keeps host/runtime lightweight: each tool runs in a managed subprocess with its own dependencies.

Scaffold an agent#

agentpm init --kind agent --name research-assistant --description "Assistant composed of multiple tools"

Generated skeleton (agent.json):

{
  "kind": "agent",
  "name": "research-assistant",
  "version": "0.1.0",
  "description": "Assistant composed of multiple tools",
  "tools": []
}

Note

Add tools to tools[], then run agentpm install to resolve/download artifacts.

Field reference (overview)#

Field	Type	Required	Notes
`$schema`	string	no	URI to this schema (optional but recommended)
`kind`	enum	yes	`"agent"` or `"tool"` (discriminator)
`name`	string	yes	`^[a-z][a-z0-9-]{0,63}$`
`version`	semver	yes	SemVer string (supports pre/metadata)
`description`	string	yes	Free text
`tools`	string	yes	Array of tool refs: string or `{name, version}`
`readme`	string	no	Path to README file. Will automatically look for README.md if not specified.
`license`	object	no	`{ spdx: "license spdx", file: "Path to LICENSE file" }`

Declaring tools#

You can reference tools using either a string spec or an object. Both carry the same information; choose one style per team preference.

String spec (concise)#

{
  "tools": [
    "@zack/summarize@0.1.2"
  ]
}

Object form (explicit)#

{
  "tools": [
    { "name": "@zack/summarize", "version": "0.1.2" }
  ]
}

Installing tools for an agent#

Once tools[] is declared, run:

agentpm install

Resolves versions.
Downloads artifacts and prepares them under: .agentpm/tools/<namespace>/<name>/<version>
Populates/updates the lockfile agent.lock with exact versions + checksums.
Uses the download cache at .agentpm/cache (use --refresh to bypass).

You can also add & install in one step:

agentpm install @zack/summarize@0.1.2
# writes/updates tools[] and installs

How agents and tools work together#

Your app (Node or Python) uses the SDK to load callable tool functions based on the agent’s tools[].
Each tool executes in its own subprocess (correct interpreter/runtime), keeping the host app clean and language-agnostic.
The agent manifest + lockfile make the toolset portable and reproducible across dev/CI/prod.

Best practices#

Pin for prod: Exact versions in tools[], commit agent.lock.
Gate in CI:

agentpm lint --strict
agentpm install --frozen --quiet

Name & describe well: Clear name/description helps discovery and registry docs.
Evolve safely: Bump the agent’s version when you change its tool set or operational contract.