ageri-sdk

Skill contract for the Ageri personal-AI platform.

Ageri is a self-hosted "chief of staff" agent system that runs 24/7, remembers across sessions, and coordinates specialist skills across every domain of your work. This package is the stable boundary every skill imports from — the abstract base classes, dataclasses, and helpers that define what a skill looks like to the Ageri runtime.

If you want to author an Ageri skill, install this package. If you want to run Ageri itself, see docs.ageri.ai/install.

Install

pip install ageri-sdk

Python 3.11+ required. No runtime dependencies — the SDK is pure ABCs + dataclasses. Skills declare their own deps in their bundle's requirements.txt.

Minimal skill

from ageri_sdk import SkillBase, SkillResult, Task, OrchestratorContext


class HelloSkill(SkillBase):
    name = "Hello"
    description = "Greets the user."
    version = "0.1.0"
    intent_domain = "general"

    async def handle(self, task: Task, ctx: OrchestratorContext) -> SkillResult:
        return SkillResult(
            status="done",
            response=f"Hello, {ctx.user.display_name}!",
        )

That's the whole contract. The runtime injects an OrchestratorContext with proxies for memory, agents (LLMs), reply, browser/screen/input automation, and so on. Your handle() does the work and returns a SkillResult.

What's in the package

• SkillBase — abstract base every skill subclasses.
• Task — what the user asked for + routing metadata.
• SkillResult — what the skill produced (response + declared memory writes).
• OrchestratorContext — the only interface skills have to the outside world. Memory, agents, reply, user, agent identity, tools.
• Proxy ABCs — MemoryProxy, AgentProxy, ReplyProxy, BrowserProxy, ScreenProxy, InputProxy, FsProxy, NetworkProxy, ClipboardProxy, ProcessProxy. Skills code against these; the runtime supplies concrete implementations.
• Helpers — SkillCommand (slash-command metadata), ConfigField (declarable config schema), MessagingSkillBase (Slack/Telegram/Zalo-OA adapter base), vision-click + browser-automation primitives, and more.

Full API reference: https://docs.ageri.ai/sdk/.

Versioning

ageri-sdk follows semver. The major version bumps if the contract breaks (adding a required method to SkillBase, changing a dataclass field that already-shipped skills rely on, etc.). Minor versions add new capabilities; patch versions are bugfixes.

Skill bundles declare their compatible SDK range via manifest_compat in skill.json:

{
  "manifest_compat": ">=0.5.0,<1.0.0"
}

The Ageri runtime refuses to load a skill whose manifest_compat doesn't include the running SDK version.

License

MIT. See LICENSE.

The Ageri platform that consumes this SDK has its own license (see the main Ageri repo). The SDK is MIT so skill authors can freely build on it, publish skills under whatever license they choose, and integrate against Ageri without IP friction.