Contributing Agents
Build and share reusable AI agents with the HUMΛN community
What Makes a Good Agent?
Single Responsibility
Does one thing and does it well. An invoice processor processes invoices — not emails, not reports.
Clear Capabilities
Explicitly declares what it can do. This enables automatic routing and discovery.
Well-Documented
Includes clear input/output specs, usage examples, and error handling docs.
Tested & Reliable
Has comprehensive tests. Handles errors gracefully. Works in production.
Portable
Doesn't hardcode credentials or environments. Uses configuration and delegation tokens.
Agent Template
Here's a basic template to get you started:
Key Patterns
1. Use Delegation Tokens
Never hardcode API keys. Accept a delegation token in the constructor and use it to authenticate.
❌ Bad: client = new HumanClient({ apiKey: "hardcoded" })
2. Log to Provenance
Every significant action should be logged. This creates an audit trail and enables debugging.
3. Handle Errors Gracefully
Don't let your agent crash. Catch exceptions, log them, and return meaningful error messages.
4. Support Human-in-the-Loop
For high-stakes decisions, pause and request human approval using HumanOS.
Submitting Your Agent
Create a Package
Package your agent as an npm module, PyPI package, or Go module. Include a clear README, examples, and tests.
Add Metadata
Include a `human.yaml` file declaring capabilities, dependencies, and configuration options.
Submit to Registry
Open a PR to the Agent Registry with your agent. Our team will review it for quality and security.
Share with the Community
Once approved, your agent is live! Share it on social media, write a blog post, and help others discover it.