Agency GithubAction and NPM

[el-j]

What does this PR do?

This pull request introduces comprehensive improvements to agent loading and orchestration for the Agency Agents project, including a new TypeScript/Node.js npm package, a GitHub Action for workflow integration, and robust test coverage for core functionality. The most important changes are grouped below by theme.

New Integration Options and Documentation

• Added instructions in README.md for using the new agency-agents npm package, including example code for loading agents, listing agents, and building swarms programmatically, as well as CLI usage examples. Also documented the GitHub Action usage and its inputs/outputs.
• Introduced a new GitHub Action via action.yml for loading agents or swarms in workflows, exposing system prompts and agent metadata as outputs. The action is implemented as an inline Node.js script with no dependencies, supporting single-agent and swarm modes, and providing detailed input/output descriptions.

Testing and Reliability

• Added vitest test suites for agent loading (loader.test.ts), registry functions (registry.test.ts), and swarm orchestration (swarm.test.ts), covering slugification, file collection, agent parsing, caching, filtering, and prompt generation. These tests ensure correctness and reliability of all core features. [1] [2] [3]

Agent Loading and Swarm Orchestration

• Implemented agent loading, filtering, and swarm prompt generation logic in the GitHub Action, including slugification, frontmatter parsing, and orchestration rules for multi-agent coordination. The action outputs are compatible with LLM workflows and enable seamless integration.

Summary

These changes make it much easier to integrate Agency Agents into Node.js, TypeScript, and GitHub Actions workflows, while ensuring correctness through extensive tests and clear documentation.

checkout:
#118

[msitarzewski]

Hey @el-j — appreciate the effort here, the code quality is genuinely solid.

Before I can evaluate this properly, I'd love to understand the use case better. Is this related to your work on magic-agent-helix or nexus-orchestrator? What's the workflow where you'd reach for npm install agency-agents vs. just grabbing the markdown files?

A few things on my mind:

1. Contributor simplicity is sacred. Right now someone can add an agent by opening a PR with a single markdown file. I don't want anything in the repo that makes a new contributor think they need to understand TypeScript, npm, or a build system to participate.

2. Package namespace — I've already claimed agency-agents on npm and PyPI, so the packaging story will ultimately come from upstream when the time is right.

3. Repo/fork references — the package.json repository URL and README Action examples currently point to el-j/agency-agents rather than this repo.

4. A few technical notes — the CJS wrapper (require() on an ESM module) would fail at runtime, and the AgentFrontmatter type is missing emoji, vibe, and services from the current spec.

I'm not opposed to eventually having a programmatic API for loading agents — but I want to understand who needs it and why before committing to that direction. What does your usage look like?

[el-j]

Hi @msitarzewski thank you for responding. so for me personally i tinker around with some agents here and there.
the use is very nice - i would call them: identities for agent's - so now i realized my self copying files from a to b all the time to give every project the agent identities it needs for it's workflow is very unhandy.

on the other side i started myself a kind of "VA" virtual agency a while ago: means concierge chat to full workflow via productowner to create detailed planning to pass to full filling correct agent's. the aim was to specialize on selfhosted ollama so all is possible, but nowadays i extracted the orchestrator into the nexus orchestrator and let the VA use it.

... i raised the question on another day where you want to go (as the outlined steps seemed very in what i do currently).

so to make it short:
having the source of the indenities handy as npm or github action would allow to easily pull in the needed agent-profiles much more easy then doing the "c+p" business all the time. 🚀

edit: sure all the links and items will be updated! u claim the name etc. me beeing contributor ... (see where all leads when we talk more ?)

edit2: and a nice gh-page lading would help that easy contributing is to refine the md. the rest must not be this "present" in first place

edit3: and sure i thought of "why not integrating in the nexus" as pull or maybe also into the planned agency the roadmap drafted...

edit4: lastest merge should restore all links and nameings back to u