Skip to content

Latest commit

 

History

History
140 lines (98 loc) · 3.99 KB

AGENT-GUIDE.md

File metadata and controls

140 lines (98 loc) · 3.99 KB

Agent Guide: Setting Up a Symposium Extension

This guide walks you through setting up automated builds and releases for a Symposium agent extension.

Prerequisites

  • A Rust crate that builds an Agent Client Protocol (ACP) agent or agent extension
  • A GitHub repository for the extension

Step 1: Add Symposium Metadata to Cargo.toml

Add a [package.metadata.symposium] section to configure how your extension is spawned:

[package.metadata.symposium]
binary = "my-extension"           # Optional: defaults to package name
args = ["--acp"]                  # Optional: arguments passed when spawning
env = { SOME_VAR = "value" }      # Optional: environment variables

All fields are optional. The binary field defaults to the package name.

Step 2: Create the Release Workflow

Create .github/workflows/release.yml:

name: Release

on:
  release:
    types: [published]

jobs:
  build:
    permissions:
      contents: write
    uses: symposium-dev/package-agent-extension/.github/workflows/build.yml@v1
    with:
      musl: true
    secrets: inherit

Set musl: true for static Linux binaries (recommended), or musl: false for dynamically linked binaries.

Passing Secrets

If your extension needs secrets at runtime, use extra_env:

jobs:
  build:
    permissions:
      contents: write
    uses: symposium-dev/package-agent-extension/.github/workflows/build.yml@v1
    with:
      musl: true
      extra_env: '{"API_KEY": "${{ secrets.API_KEY }}"}'
    secrets: inherit

Values in extra_env are merged with values from Cargo.toml.

Step 3: Set Up Automated Releases with release-plz

release-plz automates version bumping and release creation based on conventional commits.

Initialize release-plz

IMPORTANT: This is an interactive command. Do NOT run it yourself. Instead, ask the human user to run it in their own terminal.

Setup release-plz by having the human user execute:

release-plz init

This command requires user interaction (GitHub authentication, selecting options) and cannot be run by an agent. The user must run it themselves.

If they don't have release-plz installed, ask them to install it first:

cargo binstall release-plz
# or: cargo install release-plz

Configure Conventional Commits

release-plz uses conventional commits to determine version bumps. Add this to the project's AGENTS.md file so agents follow the convention:

## Commit Convention

This project uses conventional commits for automated releases:

- `fix: ...` → patch version bump (0.1.0 → 0.1.1)
- `feat: ...` → minor version bump (0.1.0 → 0.2.0)
- `feat!: ...` or `BREAKING CHANGE:` → major version bump (0.1.0 → 1.0.0)

Always use conventional commit prefixes.

How It Works

  1. Push commits to main using conventional commit messages
  2. release-plz creates a PR with version bumps and changelog updates
  3. Merge the PR to trigger a release
  4. release-plz creates a GitHub release
  5. The release triggers the build workflow
  6. Build workflow compiles binaries for all platforms and uploads them with extension.json

Build Targets

The workflow builds for these platforms:

Platform Target
macOS ARM aarch64-apple-darwin
macOS x64 x86_64-apple-darwin
Linux ARM aarch64-unknown-linux-musl (or gnu)
Linux x64 x86_64-unknown-linux-musl (or gnu)
Windows x64 x86_64-pc-windows-msvc

Release Artifacts

Each release includes:

  • {binary}-macos-aarch64-v{version}.tar.gz
  • {binary}-macos-x86_64-v{version}.tar.gz
  • {binary}-linux-aarch64-v{version}.tar.gz
  • {binary}-linux-x86_64-v{version}.tar.gz
  • {binary}-windows-x86_64-v{version}.zip
  • extension.json - manifest for the ACP registry

Checklist

  • Added [package.metadata.symposium] to Cargo.toml (if needed)
  • Created .github/workflows/release.yml
  • User ran release-plz init
  • Using conventional commits for changes