Kyra Java SDK

Runtime governance for AI agent actions in Java. Evaluate tool calls with Kyra before execution; blocked actions are reported via EvaluateResult or by throwing KyraBlockedException / KyraEscalationRequiredException.

Package: com.kyra.sdk

Install

Maven:

<dependency>
    <groupId>com.kyra</groupId>
    <artifactId>kyra-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle:

dependencies {
    implementation("com.kyra:kyra-sdk:1.0.0")
}

Getting started

import com.kyra.sdk.*;

// 1. Create governor (once per process or per agent)
KyraGovernorConfig config = KyraGovernorConfig.builder("kyra_sk_...")
    .agentId("my-agent-v1")
    .failOpen(false)
    .mode("enforce")
    .build();
KyraGovernor governor = new KyraGovernor(config);

// 2. Create governance context from the user message (per run)
GovernanceContext ctx = GovernanceContext.fromUserMessage(
    "Refund order 123 if policy allows",
    "my-agent-v1"
);
GovernanceContextHolder.set(ctx);

// 3. Before executing a tool, evaluate
Map<String, Object> params = Map.of("order_id", "123", "amount", 50.0);
KyraGovernor.EvaluateResult result = governor.evaluate(
    "issue_refund",
    "Issues a refund for the given order and amount",
    params
);

if (!result.isOk()) {
    System.out.println("Blocked: " + result.getBlockReason());
    return;
}
// Proceed with tool execution

Configuration

Option	Required	Default	Description
`apiKey`	Yes	—	Your Kyra API key (`kyra_sk_...`)
`timeoutMs`	No	5000	Request timeout in milliseconds
`failOpen`	No	`true`	If true, allow when Kyra is unreachable; if false, treat as block
`mode`	No	`""`	`"enforce"` or `"shadow"` — sent to server as ENFORCE / SHADOW
`agentId`	No	`""`	Agent identifier for evaluate requests
`sessionIntent`	No	`""`	Optional session-level intent hint
`framework`	No	`"JAVA"`	Reported in wire format

Example (fail-closed, enforce mode):

KyraGovernorConfig config = KyraGovernorConfig.builder(System.getenv("KYRA_API_KEY"))
    .agentId("refund-agent-v1")
    .failOpen(false)
    .mode("enforce")
    .timeoutMs(15_000)
    .build();
KyraGovernor governor = new KyraGovernor(config);

Governance context (per run)

Create a governance context at the start of each run so all evaluations share the same trace and session.

From user message: GovernanceContext.fromUserMessage(message, rootAgentId)
Child context (multi-agent): GovernanceContext.newChildContext(parent, childAgentId)

Set the current context on the thread so evaluate() can use it when not passed explicitly:

GovernanceContextHolder.set(ctx);
// ... later ...
KyraGovernor.EvaluateResult result = governor.evaluate("my_tool", "Description", params);
GovernanceContextHolder.clear(); // when done

Trace ID can be user-provided (e.g. from your context) or omitted so Kyra generates one. The decision returned from each evaluate always includes the trace ID used.

Evaluate

Full call: evaluate(toolName, toolDescription, parameters, context, traceId, agentContext, requestedTier)
Use null for optional args; context defaults to GovernanceContextHolder.get().
Simple call: evaluate(toolName, toolDescription, parameters)
Uses context from holder, no traceId override.

Returns EvaluateResult: isOk(), getBlockReason(), getDecision(). Call result.throwIfDenied() to throw KyraBlockedException, KyraEscalationRequiredException, or KyraReturnToUserException when not allowed.

Optional: register agent

ToolDef refund = new ToolDef();
refund.setName("issue_refund");
refund.setDescription("Issues a refund for the given order and amount");
ToolDef search = new ToolDef();
search.setName("search_orders");
search.setDescription("Searches orders by customer id");
String agentId = governor.registerAgent(
    "refund-agent",
    "You are a refund assistant.",
    List.of(refund, search)
);
// agentId is stored on the governor and used for subsequent evaluate calls

Exceptions

Exception	When
`KyraBlockedException`	Outcome BLOCK
`KyraEscalationRequiredException`	Outcome ESCALATE
`KyraReturnToUserException`	Outcome RETURN_TO_USER (missing parameters); use `getMissingParameters()`
`KyraServerUnavailableException`	Server unreachable and `failOpen` is false

All carry an optional EvaluationDecision via getDecision().

Build

mvn clean install

Tests:

mvn test

Java SDK

On this page