SDKs

Official client libraries for Python, TypeScript, and Java. Submit intents, retrieve decisions, handle errors — with full type safety.

At a Glance

Python

Install

pip install gaas-sdk

Submit an Intent

from gaas_sdk import GaaSClient, build_intent

async with GaaSClient(
    "https://api.gaas.to",
    headers={"X-API-Key": "your_key"},
) as client:
    intent = build_intent(
        agent_id="billing_bot",
        action_type="communicate",
        verb="send_email",
        target_type="person",
        target_identifier="patient@example.com",
        summary="Send billing statement to patient",
        content={"recipient": "patient@example.com", "channel": "email"},
    )
    response = await client.submit_intent(intent)

    if response.data.verdict == "approve":
        send_email(response.data)
    elif response.data.verdict == "block":
        log(response.data.reasoning)

Sync Client

A synchronous client is available for non-async codebases:

from gaas_sdk import GaaSClientSync

with GaaSClientSync(
    "https://api.gaas.to",
    headers={"X-API-Key": "your_key"},
) as client:
    response = client.submit_intent(intent)

Error Handling

from gaas_sdk import GaaSValidationError, GaaSConnectionError

try:
    response = await client.submit_intent(intent)
except GaaSValidationError as e:
    print(f"Validation failed: {e.message}")
except GaaSConnectionError:
    print("Could not reach GaaS server")

Exception classes: GaaSValidationError (400), GaaSSemanticError (422), GaaSNotFoundError (404), GaaSConflictError (409), GaaSServerError (500), GaaSConnectionError (network).

TypeScript

Install

npm install @gaas/sdk

Submit an Intent

import { GaaSClient, buildIntent } from '@gaas/sdk';

const client = new GaaSClient({
  baseUrl: 'https://api.gaas.to',
  headers: { 'X-API-Key': 'your_key' },
});

const intent = buildIntent({
  agentId: 'billing_bot',
  actionType: 'communicate',
  verb: 'send_email',
  targetType: 'person',
  targetIdentifier: 'patient@example.com',
  summary: 'Send billing statement to patient',
  content: { recipient: 'patient@example.com', channel: 'email' },
});

const response = await client.submitIntent(intent);

if (response.data.verdict === 'approve') {
  sendEmail(response.data);
} else if (response.data.verdict === 'block') {
  console.log(response.data.verdictReason);
}

Error Handling

import { GaaSValidationError, GaaSConnectionError } from '@gaas/sdk';

try {
  const response = await client.submitIntent(intent);
} catch (error) {
  if (error instanceof GaaSValidationError) {
    console.error(`Validation failed: ${error.message}`);
  } else if (error instanceof GaaSConnectionError) {
    console.error('Could not reach GaaS server');
  }
}

Java

Install

Maven:

<dependency>
    <groupId>com.gaas</groupId>
    <artifactId>gaas-sdk</artifactId>
    <version>0.2.0</version>
</dependency>

Gradle:

implementation 'com.gaas:gaas-sdk:0.2.0'

Submit an Intent

import com.gaas.sdk.*;

try (GaaSClient client = new GaaSClient("https://api.gaas.to", "your_key")) {
    IntentDeclaration intent = IntentBuilder.create()
        .agentId("billing_bot")
        .actionType(ActionType.COMMUNICATE)
        .verb("send_email")
        .targetType(TargetType.PERSON)
        .targetIdentifier("patient@example.com")
        .summary("Send billing statement to patient")
        .content(Map.of("recipient", "patient@example.com", "channel", "email"))
        .build();

    GaaSResponse<GovernanceDecision> response = client.submitIntent(intent);

    if (response.getData().getVerdict() == Verdict.APPROVE) {
        sendEmail(response.getData());
    } else if (response.getData().getVerdict() == Verdict.BLOCK) {
        System.out.println(response.getData().getReasoning());
    }
}

Async API

CompletableFuture<GaaSResponse<GovernanceDecision>> future =
    client.submitIntentAsync(intent);

Error Handling

try {
    GaaSResponse<GovernanceDecision> response = client.submitIntent(intent);
} catch (GaaSValidationException e) {
    System.out.println("Validation failed: " + e.getMessage());
} catch (GaaSConnectionException e) {
    System.out.println("Could not reach GaaS server");
}

Common Patterns

Builder Pattern

All three SDKs provide a builder function (build_intent in Python, buildIntent in TypeScript, IntentBuilder in Java) that flattens the nested intent model into a flat argument list. This handles the agent.id, action.type, action.target.identifier nesting so you don't have to construct nested objects manually.

Response Structure

Every SDK method returns a typed response with two fields:

• data — the response payload (e.g., GovernanceDecision, AuditRecord, HealthStatus)
• meta — request metadata: request ID, decision ID, pipeline latency, status code

Retrieving Decisions

Python:

decision = await client.get_decision("intent-id")

TypeScript:

const decision = await client.getDecision('intent-id');

Java:

GaaSResponse<GovernanceDecision> decision = client.getDecision("intent-id");

Related Pages

• Getting Started — full quickstart walkthrough
• Intent Declaration API — endpoint reference and schema details
• Shadow Mode — test governance without enforcement