SDKs

SDKs for Python, TypeScript, and Go

Embed action reduction in your own applications, harnesses, and CI.

Official open-source clients for Python, TypeScript, and Go. They speak the same action API as the CLI and exist for applications, harnesses, CI systems, and vendor backends that embed reduction in their own pipelines. To use Codag with Claude Code or Codex you do not need an SDK; run codag setup instead.

1. Create an API key

SDKs authenticate with a workspace API key. Create one in the Codag console, store it in your secret manager, and expose it as CODAG_API_KEY.

2. Install one SDK

Python

codag

$pip install codag

TypeScript

@codag/sdk

$npm install @codag/sdk

codag-sdk/go

$go get github.com/codag-megalith/codag-sdk/go

3. Reduce an action

Pass the tool call, its raw result, and the action kind. Branch on the decision: reduced gives you the evidence to hand your agent, passthrough means use the original. Each client reads its API key from the constructor or CODAG_API_KEY.

The envelope also takes optional context that improves reduction quality: session metadata (session_id, harness, provider, model), the agent's task and intent, and a retrieval_handle that ties the reduction to an original you keep locally. A reduced response carries selectors describing the omitted sections by line range, JSON path, or group, so a client that kept the original can retrieve exact slices without another network call. See the action API reference for field details.

from codag import ActionEnvelope, Codag, ToolCall

client = Codag()  # reads CODAG_API_KEY

response = client.reduce_action(ActionEnvelope(
    id="act_01",
    kind="test_build_lint",
    tool=ToolCall(name="bash"),
    result=raw_output,
    task="Fix the failing checkout tests",
))

evidence = response.content if response.decision == "reduced" else raw_output
                        

import { Codag } from "@codag/sdk";

const client = new Codag();  // reads CODAG_API_KEY

const response = await client.reduceAction({
  id: "act_01",
  kind: "test_build_lint",
  tool: { name: "bash" },
  result: rawOutput,
  task: "Fix the failing checkout tests",
});

const evidence = response.decision === "reduced" ? response.content : rawOutput;
                        

package main

import (
    "context"
    "log"

    codag "github.com/codag-megalith/codag-sdk/go"
)

func main() {
    client := codag.New()  // reads CODAG_API_KEY

    response, err := client.ReduceAction(context.Background(), codag.ActionEnvelope{
        ID:     "act_01",
        Kind:   "test_build_lint",
        Tool:   codag.ToolCall{Name: "bash"},
        Result: rawOutput,
        Task:   "Fix the failing checkout tests",
    })
    if err != nil {
        log.Fatal(err)
    }

    evidence := rawOutput
    if response.Decision == "reduced" {
        evidence = response.Content
    }
    _ = evidence
}
                        

Usage, savings, and policy

The same clients expose the workspace surface: usage_summary, usage_timeseries, usage_breakdown, and usage_reliability for usage and savings, trial_report for trial results, model_prices for the public price catalog behind dollar estimates, get_workspace_policy and set_workspace_policy for workspace policy, and service_status for health. TypeScript and Go use the camel-case and exported equivalents. Dollar figures everywhere are estimates computed from public model prices.

Contentless metrics

send_metrics submits the required accounting events. The clients validate that events are contentless before anything is sent: bounded identifiers and counters only, never prompts, paths, or output.

Configuration

Credentials resolve from the constructor first, then CODAG_API_KEY. The default host is https://api.codag.ai; override it with a constructor option or CODAG_SERVER.

Errors

Non-2xx responses raise typed errors. Python and TypeScript raise exception classes (AuthenticationError, BillingError, RateLimitError, ValidationError). Go returns an *APIError with a StatusCode and sentinel values (ErrAuthentication, ErrBilling, ErrRateLimited) you match with errors.Is. Note that /v1/actions/reduce itself prefers failing open: a request the service cannot improve comes back as a passthrough decision, not an error.