Skip to content

Agent SDKs ​

Alga ships four standalone Agent SDKs for building custom AI agents that connect to the Alga agent API. Each SDK implements the same client shape: connect over SSE, handle events, call REST methods, and send investigation commands via factory helpers. All four are MIT licensed and share a unified feature set:

  • SSE client with exponential backoff reconnect (2s → 60s, jitter), Retry-After honoring, and terminal auth-error detection (401/403 stops the loop)
  • REST client with configurable retries on transient errors (429, 5xx, network), Retry-After parsing, and Idempotency-Key auto-injection on POST /messages
  • Command builders for all backend ops: alert lifecycle, incident lifecycle, handoffs, status updates, and resolution docs
  • Message deduplication (bounded, TTL-based, no-evict-on-insert)
  • Typed models for all SSE events and REST responses
  • onUnknownEvent escape hatch for forward compatibility with new backend event types
SDKLanguagePackageInstall
GoGo (stdlib only)github.com/alga/agent-sdk-gogo get github.com/alga/agent-sdk-go
JavaScriptTypeScript / Node.js 18+@alga/agent-sdknpm install @alga/agent-sdk
PythonPython 3.10+ (async)alga-agent-sdkpip install alga-agent-sdk
RustRust (Tokio)alga-agent-sdkcargo add alga-agent-sdk

Source Layout ​

SDKPathKey Files
Gointegrations/alga-agent-sdk-goclient.go, commands.go, dedup.go, errors.go, log.go, models.go, options.go, sse.go, util.go + examples
JavaScriptintegrations/alga-agent-sdk-jsnpm package with src/ + dist/
Pythonintegrations/alga-agent-sdk-pyalga_agent_sdk/ package, pyproject.toml
Rustintegrations/alga-agent-sdk-rssrc/ + tests/, Cargo.toml

Prerequisites

You need an agent token (alga_agent_...) created from Agents in the Alga UI. See AI Investigation for how agents are dispatched.

How Agents Work ​

  1. The agent connects to GET /api/v1/agent/events (SSE) with its bearer token.
  2. Alga's scheduler dispatches investigations to connected agents based on capabilities, scope, and label selectors.
  3. The agent receives events (message, typing, peer_ask, peer_finding, etc.), calls REST methods to fetch context, and sends updates/commands back.
  4. A heartbeat (POST /api/v1/agent/heartbeat ~every 30s) keeps the agent's presence lease alive.

See the Agent REST API and Agent SSE reference for the full endpoint surface.

Unified SSE Events ​

All four SDKs handle the same event set:

EventDescription
connectedInitial connection handshake
messageChat message from operator or peer
typingTyping indicator
investigation_resumeInvestigation resumed
peer_findingNotable finding from a peer agent
peer_askAnother agent is asking a question
peer_replyReply to your peer ask
summarize_incidentBackend requests an incident summary
alert_auto_resolvedAn investigated alert auto-resolved
incident_comms_staleIncident comms went quiet past SLA threshold
(any other)Routed to onUnknownEvent escape hatch

Unified Command Builders ​

All four SDKs provide factory functions for every backend inv_tool op. Incident-scoped commands take incident_number (integer), matching the backend contract.

  • Alert lifecycle — resolve_alert, reopen_alert, set_outcome, cancel_investigation, pause_investigation, triage_feedback, assign_investigation, promote_to_incident
  • Incident lifecycle — set_incident_priority, set_incident_severity, trigger_escalation, mitigate_incident, resolve_incident, begin_triage, promote_incident, assign_incident_role
  • Coordination — post_handoff, publish_status_update, set_incident_resolution_docs

Go ​

go
package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"

    alga "github.com/alga/agent-sdk-go"
)

func main() {
    serverURL := os.Getenv("ALGA_SERVER_URL")
    token := os.Getenv("ALGA_AGENT_TOKEN")

    client := alga.NewAlgaClient(serverURL, token)

    client.OnMessage = func(evt alga.MessageEvent) {
        fmt.Printf("Message: %s\n", evt.Text)
        client.SendMessage(context.Background(), evt.ChatID, "Got it!", nil)
    }

    client.OnSummarizeIncident = func(evt alga.SummarizeIncidentEvent) {
        fmt.Printf("Summary requested: incident %d\n", evt.IncidentNumber)
    }

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    client.Connect(ctx)

    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
    <-sigCh

    client.Disconnect()
}

Key features: SSE callbacks as struct fields (OnMessage, OnSummarizeIncident, OnUnknownEvent, …), REST methods with retry + idempotency, command factory functions (ResolveAlert(fp), SetIncidentPriority(n, level)), terminal auth errors via Err() <-chan error. Stdlib-only, zero dependencies.

JavaScript / TypeScript ​

typescript
import { AlgaClient, resolveAlert } from "@alga/agent-sdk";

const client = new AlgaClient("https://alga.example.com", process.env.ALGA_AGENT_TOKEN!);

client.onMessage = (msg) => {
  console.log("received message:", msg.text);
};

client.onSummarizeIncident = (evt) => {
  console.log("summary requested:", evt.incident_number);
};

client.onErr((err) => console.error("terminal:", err.message));

client.connect();

Key features: automatic SSE reconnect with exponential backoff (2s–60s, jitter), Retry-After honoring, Idempotency-Key auto-injection, callbacks as properties (client.onMessage = …), onUnknownEvent escape hatch, zero runtime dependencies (native fetch).

Python ​

python
import asyncio
from alga_agent_sdk import AlgaClient, resolve_alert

client = AlgaClient(
    server_url="http://localhost:8080",
    token="your-agent-bearer-token",
)

async def on_message(evt):
    print(f"[{evt.sender_name}] {evt.text}")

async def main():
    client.on_message = on_message
    await client.connect()
    try:
        alerts = await client.list_alerts({"status": "firing", "limit": "10"})
        await client.wait()
    finally:
        await client.disconnect()

asyncio.run(main())

Key features: fully async (asyncio + httpx), async callbacks, Idempotency-Key auto-injection, REST retries with Retry-After, terminal auth errors via on_err(). Dependencies: httpx>=0.27, pydantic>=2.0.

Rust ​

rust
use alga_agent_sdk::{AlgaClient, AlgaError, EventHandler};
use alga_agent_sdk::models::*;
use async_trait::async_trait;
use std::sync::Arc;

struct MyAgent;

#[async_trait]
impl EventHandler for MyAgent {
    async fn on_connected(&self, event: ConnectedEvent) {
        println!("Connected as agent {:?}", event.agent_id);
    }
    async fn on_message(&self, event: MessageEvent) {
        println!("[{:?}] {:?}", event.chat_id, event.text);
    }
}

#[tokio::main]
async fn main() -> Result<(), AlgaError> {
    let mut client = AlgaClient::new("http://localhost:8080", "your-agent-token")?;
    client.connect(Arc::new(MyAgent))?;

    client.send_command("alert_42", alga_agent_sdk::commands::resolve_alert("fp-abc")).await?;

    tokio::signal::ctrl_c().await.ok();
    client.disconnect();
    Ok(())
}

Key features: events received by implementing the EventHandler trait (all methods have default no-ops), commands as builder functions (resolve_alert(fp), set_incident_priority(n, level)), Idempotency-Key auto-injection, REST retries, fatal error retrieval via take_fatal_error().

Built-in Adapters ​

In addition to these SDKs, Alga ships ready-made agents and adapters:

  • Alga Agent — the native first-party Go agent, built on the Go SDK.
  • OpenClaw plugin — 30-odd agent tools for the OpenClaw channel.
  • Hermes agent plugin (integrations/alga-hermes-agent-plugin) — 30-odd agent tools for the Nous Research Hermes platform.

For details on the investigation pipeline, scheduling, and agent capabilities, see AI Investigation.

Released under the MIT License.