Go SDK
Install and use the public Go client for the registry API in Orca Agent Engine.
The github.com/orca-ae/orca-sdk-go module is the Go client for Orca Agent Engine. The public v0.4.0 release supports core registry resources, session event streaming, policy guardrails, model prices, and deployment-specific Cloud extensions. It requires Go 1.25 or later.
Install
Add the released module to your Go project:
go get github.com/orca-ae/orca-sdk-go@v0.4.0The repository's API surface lists the exported methods and types. The SDK also includes runnable examples.
Configure the client
Set ORCA_BASE_URL to the registry host root, without /v1. Supply exactly one credential:
| Credential | Go option | Request header |
|---|---|---|
| Workspace API key | option.WithAPIKey(key) | x-api-key |
| OIDC access token | option.WithAuthToken(token) | Authorization: Bearer |
orca.New() reads ORCA_BASE_URL and either ORCA_API_KEY or ORCA_ACCESS_TOKEN from the environment when the matching option is absent. An explicit option wins. For an ork local deployment, use its generated Workspace API key:
export ORCA_BASE_URL="http://127.0.0.1:8080"
export ORCA_API_KEY="$(cat "$LOCAL_DIR/secrets/workspace-api-key")"LOCAL_DIR is the data directory you supplied to ork local --data-dir; the local tutorial defines it. Keep the key file private.
Create an environment and agent
This example uses the same Workspace key as the CLI. It creates registry resources but does not call a model, so no provider key is needed to check the SDK connection:
package main
import (
"context"
"fmt"
"log"
orca "github.com/orca-ae/orca-sdk-go"
)
func main() {
client, err := orca.New()
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
environment, err := client.Environments.Create(ctx, orca.EnvironmentNewParams{
Name: "go-sdk-example",
})
if err != nil {
log.Fatal(err)
}
agent, err := client.Agents.Create(ctx, orca.AgentNewParams{
Name: "go-sdk-example",
Model: orca.Model("claude-sonnet-4-6"),
Metadata: map[string]string{"harness": "claude_agent_sdk"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println("environment:", environment.ID)
fmt.Println("agent:", agent.ID)
}Run it with go run . in a module containing main.go. For a provider-backed session, set ANTHROPIC_API_KEY before starting the local harness, then follow the session flow. The SDK's quickstart example also shows session creation, event sending, and streaming; it needs an existing environment and a configured provider key.
Check a deployed registry
Use an existing Workspace API key from your deployment's admin flow. For a Kubernetes deployment, you can port-forward its public registry service and set ORCA_BASE_URL to the forwarded host root. The service name and namespace depend on your Helm release.
These read-only calls check core agents and the policy extension. Add them inside main after creating client and ctx in the example above:
groups, err := client.GetAPIGroups(ctx)
if err != nil {
log.Fatal(err)
}
agents, err := client.Agents.List(ctx, orca.AgentListParams{})
if err != nil {
log.Fatal(err)
}
types, err := client.Guardrails.ListTypes(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("API groups:", len(groups.Groups))
fmt.Println("agents on first page:", len(agents.Items()))
fmt.Println("guardrail types:", len(types.Data))If policy.runorca.ai/v1 is absent from discovery, ListTypes returns ExtensionNotAvailableError. The counts depend on the deployment; they are not fixed expected values.
Create and attach a guardrail
The policy extension must appear in the deployment's authenticated GET /apis response. Create an explicit request rule, then attach it to a new agent. Add this code inside main after creating client and ctx above:
guardrail, err := client.Guardrails.Create(ctx, orca.GuardrailNewParams{
Name: "deny-test-requests",
Scope: param.New(orca.GuardrailScopeExplicit),
Phases: []orca.GuardrailPhase{orca.GuardrailPhaseRequest},
Rule: orca.GuardrailRule{
Kind: orca.GuardrailRuleExpression,
Expression: "false",
OnFalse: orca.GuardrailVerdictDeny,
},
})
if err != nil {
log.Fatal(err)
}
guardedAgent, err := client.Agents.Create(ctx, orca.AgentNewParams{
Name: "go-sdk-guarded-agent",
Model: orca.Model("claude-sonnet-4-6"),
Metadata: map[string]string{"harness": "claude_agent_sdk"},
GuardrailIDs: []string{guardrail.ID},
}, option.WithHeader("orca-beta", "guardrails"))
if err != nil {
log.Fatal(err)
}
fmt.Println("guarded agent:", guardedAgent.ID)Add "github.com/orca-ae/orca-sdk-go/option" and "github.com/orca-ae/orca-sdk-go/packages/param" to the imports in the first example. The Go SDK does not add orca-beta automatically when you set GuardrailIDs. The request rule denies a session's first message before any model call; see the local guardrail walkthrough for the event check and Guardrails for other rules and enforcement limits.
Pagination and streaming
List returns one cursor page. Iterate its All(ctx) sequence to follow later pages, checking each iteration error. After creating an agent and environment above, add this code inside main to start a session and read its events. A provider-backed reply needs a configured model credential:
session, err := client.Sessions.Create(ctx, orca.SessionNewParams{
Agent: orca.AgentRef(agent.ID),
EnvironmentID: environment.ID,
})
if err != nil {
log.Fatal(err)
}
_, err = client.Sessions.Events.Send(ctx, session.ID, []orca.SessionEventParam{
orca.UserMessage("Say hello."),
})
if err != nil {
log.Fatal(err)
}
stream := client.Sessions.Events.Stream(ctx, session.ID, orca.SessionEventStreamParams{})
defer stream.Close()
for stream.Next() {
event := stream.Current()
fmt.Println(event.Type)
if event.Type == "session.status_idle" {
break
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}See the released quickstart for a standalone program with the same session flow.