# 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](https://komrad.dev/latest/api.md) 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`](https://komrad.dev/latest/config.md#connection.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](https://komrad.dev/latest/guides/remote.md) 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`](https://komrad.dev/latest/cli/token.md) 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:

```sh
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`:

```go
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:

```go
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:

```go
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:

```go
_, err := client.Agents.GetAgent(ctx, &agentv1.GetAgentRequest{Id: agentID})
if connect.CodeOf(err) == connect.CodeNotFound {
	fmt.Println("no agent", agentID)
}
```
