SDKs
Create and manage agents from your own programs.
Komrad’s API is a set of Connect services defined in protobuf, and an SDK calls them from your own programs. A program can create agents, read what they are doing, send them mail, and make any other call the API reference lists.
Each SDK is generated from the same protos as the API. It has a client for each service and a type for each request and response, so the fields on a method’s page in the API reference are the fields the SDK takes. Go is the only language with an SDK so far, and the panel and the komrad CLI use it too. An SDK for another language comes from the same protos.
Reaching komrad#
An SDK takes komrad’s URL. The URL is http:// followed by the address komrad listens on, which is 127.0.0.1:8787 unless addr or KOMRAD_ADDR names another.
Calling as an agent#
A call without an agent’s id comes from a person, and a person may do anything. An SDK can make every call as one agent, and a method that limits what an agent may do applies those limits to that agent. A program an agent runs finds its own agent in KOMRAD_AGENT_ID and KOMRAD_SESSION_ID.
Remote engines#
A remote engine answers at its URL and lets in only signed-in people. A program gives the SDK the engine’s URL and a live ID token from the engine’s identity provider, and the SDK sends the token on every call. komrad token --engine dev prints a live token for the engine named dev.
Every call to an engine’s URL comes from the signed-in person, so calling as an agent has no effect there. A program calls as an agent only on the engine’s own address, from the engine’s machine.
Errors#
A call that fails returns a Connect error, and its code says what kind of thing went wrong. The API reference says what each code means.
Go#
The Go SDK is a Go module of its own, apart from the komrad binary:
go get github.com/harrisoncramer/komrad/sdk/go
Each komrad release also tags the module, as sdk/go/v0.3.0 for komrad v0.3.0. Komrad keeps no backward compatibility between releases, so use the version that matches the komrad you call.
The repository is private, so the Go module proxy can’t fetch it. Set GOPRIVATE=github.com/harrisoncramer/komrad and make sure git can clone the repository.
Calling komrad#
sdk.New takes komrad’s URL and returns an sdk.Client:
package main
import (
"context"
"fmt"
"log"
sdk "github.com/harrisoncramer/komrad/sdk/go"
agentv1 "github.com/harrisoncramer/komrad/sdk/go/gen/agent/v1"
)
func main() {
ctx := context.Background()
client := sdk.New("http://127.0.0.1:8787")
listed, err := client.Agents.ListAgents(ctx, &agentv1.ListAgentsRequest{})
if err != nil {
log.Fatal(err)
}
for _, row := range listed.GetAgents() {
fmt.Println(row.GetAgent().GetName(), row.GetAgent().GetState())
}
}
sdk.Client has a field for each service, such as Agents, Tasks and Workflows. Each method takes a request message from the packages under sdk/go/gen.
Calls go through http.DefaultClient. sdk.WithHTTPClient sends them through your own http.Client instead, for example to set a timeout.
Creating an agent#
An agent belongs to a workflow, and client.Workflows.ListWorkflows finds the workflow’s id. Without a task named in the request, komrad creates a task with the new agent as its writer:
created, err := client.Agents.CreateAgent(ctx, &agentv1.CreateAgentRequest{
WorkflowId: workflowID,
Prompt: "Fix the flaky login test.",
})
if err != nil {
log.Fatal(err)
}
fmt.Println("created", created.GetAgent().GetName())
Calling as an agent#
sdk.WithAgent makes every call as one agent:
client := sdk.New("http://127.0.0.1:8787",
sdk.WithAgent(os.Getenv("KOMRAD_AGENT_ID"), os.Getenv("KOMRAD_SESSION_ID")),
)
Remote engines#
Pass the engine’s URL to sdk.New, and pass sdk.WithTokenSource a function that returns a live ID token.
Errors#
A call that fails returns an error from connectrpc.com/connect/v2. connect.CodeOf reads its code:
_, err := client.Agents.GetAgent(ctx, &agentv1.GetAgentRequest{Id: agentID})
if connect.CodeOf(err) == connect.CodeNotFound {
fmt.Println("no agent", agentID)
}