Agent SDKs

Active Development

The Agent Runtime Protocol and these SDKs are under active development. Pin to a specific release when building production agents.

Aether provides first-party SDKs for building external agents — independent processes that connect to the Hub via gRPC and process tasks alongside built-in agents.

What Is an External Agent?

Built-in agents (pm_sarah, ta_leo, etc.) run inside the Aether process. External agents run anywhere — as Docker containers, standalone binaries, serverless functions, or cloud workloads — and communicate with the Hub over the Agent Runtime Protocol (ARP).

┌─────────────────────────────────────────────────────┐
│                    Aether Hub                        │
│   gRPC Gateway · LLM Proxy · Tools · Memory · NATS  │
└────────────────────┬────────────────────────────────┘
                     │ gRPC (:9090)
         ┌───────────┼───────────┐
         ▼           ▼           ▼
    ┌─────────┐ ┌─────────┐ ┌──────────┐
    │ Python  │ │   Go    │ │TypeScript│
    │  Agent  │ │  Agent  │ │  Agent   │
    └─────────┘ └─────────┘ └──────────┘

Choosing an SDK

	Python	Go	TypeScript
Package	aether-agent-sdk	github.com/amansrivastava/hacky-automation/sdks/go	@aether/agent-sdk
Runtime	Python 3.8+	Go 1.21+	Node.js 16+
API style	async/await	interfaces + goroutines	async/await
Best for	ML/data pipelines, scripting, rapid prototyping	High-performance agents, CLI tools, existing Go services	Frontend-adjacent agents, Node.js microservices

All three SDKs expose the same conceptual API:

• Connect to the Hub via gRPC
• Register with an agent ID and capabilities
• Receive tasks over a bidirectional stream
• Call Hub services — LLM, Tools, Memory, Messaging
• Return results back to the Hub
• Reconnect automatically on connection loss

Quickstart Links

• Python SDK Guide →
• Go SDK Guide →
• TypeScript SDK Guide →

Agent Lifecycle

Regardless of SDK, every agent follows the same lifecycle:

1. Connect   ─── gRPC connection to Hub :9090
2. Register  ─── agent_id + secret → session_id
3. Stream    ─── bidirectional task stream opens
4. Process   ─── receive TaskAssignment, call Hub services, return TaskResult
5. Heartbeat ─── periodic pings to keep connection alive (automatic)
6. Reconnect ─── exponential backoff on disconnect (automatic)
7. Shutdown  ─── unregister, close stream, disconnect

Hub Services

Once registered, agents can call Hub-proxied services without managing credentials or routing themselves:

Service	Purpose
LLM	Chat completions via LiteLLM — model governance enforced by Hub
Tools	Execute registered tool actions (built-in or MCP plugins)
Memory	Key-value store with scope (short-term / long-term / agent)
Messaging	NATS publish/subscribe and request-reply

Migration Guide

Converting a Built-in Agent to an External SDK Agent

If you have an agent currently implemented inside goway/internal/, you can move it to an external process using any SDK:

1. Copy the soul/config — keep the same agent_id (e.g. pm_sarah) so existing task mappings work unchanged.
2. Implement handle_task / HandleTask — replicate the logic currently in the Go handler.
3. Replace direct DB/LLM calls with Hub service proxies (hub.llm.chat(...), hub.tools.execute(...), etc.).
4. Remove the built-in agent registration in goway/ once the external agent is stable.
5. Update the agent record in the database to point to the external agent.

See the Agent Runtime Protocol for full protocol details.