Skip to main content
Adapters connect agent frameworks to Charm’s runner protocol (invoke, streaming, tools, errors).
Building a third-party plugin without forking Charm? See Custom Adapters (entry points + custom image). This page is for core contributors adding official adapters to the charmos package.

​
When to add an adapter to core

Add to the SDK when the framework is widely used and should ship with official runner images and first-class docs. Niche or experimental integrations should stay as entry-point plugins in separate packages.

​
Community plugin path (preferred for most authors)

  1. Publish a pip package with [project.entry-points."charm.adapters"]
  2. Ship a Docker image with that package installed
  3. Set runtime.custom_image + runtime.adapter.type in charm.yaml
No changes to the Charm GitHub repo required.

​
Core contributor path

  1. Study the closest adapter in src/charm/adapters/
  2. Implement BaseAdapter
  3. Register in pyproject.toml under [project.entry-points."charm.adapters"]
  4. Add/update Dockerfile if a dedicated runner image is needed
  5. Add tests and adapter docs under docs/adapters/
  6. Update charm-community-plugin/templates/registry.json if a new starter template is warranted

​
Testing

charm validate path/to/example
charm run path/to/example --input "Hello"
charm run path/to/example --docker --input "Hello"