Developer Quickstart

This guide gets you from zero to governed agent actions. Estimated time: 30 minutes.

Prerequisites

• Node.js 18+ or Python 3.9+
• An AI agent that takes actions
• ΔOS API credentials (get them at console.deltaos.ai)

Step 1: Install the SDK

Node.js / TypeScript

npm install @deltaos/sdk
# or
pnpm add @deltaos/sdk

Python

pip install deltaos

Step 2: Initialize the Client

TypeScript

import { DeltaOS } from '@deltaos/sdk';

const deltaos = new DeltaOS({
  apiKey: process.env.DELTAOS_API_KEY,
  environment: 'production'  // or 'sandbox' for testing
});

Python

from deltaos import DeltaOS

deltaos = DeltaOS(
    api_key=os.environ["DELTAOS_API_KEY"],
    environment="production"  # or "sandbox" for testing
)

Step 3: Submit Your First Intent

Before your agent takes an action, submit an Intent:

TypeScript

async function sendEmail(to: string, subject: string, body: string) {
  // Submit Intent before action
  const intent = await deltaos.intents.create({
    action: 'email.send',
    resource: `recipients/${to}`,
    parameters: { to, subject, body }
  });

  // Check judgment
  if (intent.judgment === 'allow') {
    // Proceed with action
    await emailService.send(to, subject, body);
    return { success: true, intentId: intent.id };
  } else if (intent.judgment === 'escalate') {
    // Wait for human decision
    return { pending: true, escalationId: intent.escalation.id };
  } else {
    // Action blocked
    return { blocked: true, reason: intent.blockReason };
  }
}

Python

async def send_email(to: str, subject: str, body: str):
    # Submit Intent before action
    intent = await deltaos.intents.create(
        action="email.send",
        resource=f"recipients/{to}",
        parameters={"to": to, "subject": subject, "body": body}
    )

    # Check judgment
    if intent.judgment == "allow":
        await email_service.send(to, subject, body)
        return {"success": True, "intent_id": intent.id}
    elif intent.judgment == "escalate":
        return {"pending": True, "escalation_id": intent.escalation.id}
    else:
        return {"blocked": True, "reason": intent.block_reason}

Step 4: Configure Basic Policies

Policies define what's allowed, blocked, or escalated. Configure them in the console or via API:

Via Console

1. Go to console.deltaos.ai/policies
2. Click "New Policy"
3. Define conditions and judgments

Via API

await deltaos.policies.create({
  name: 'email-rate-limit',
  description: 'Limit email sending rate',
  conditions: {
    action: 'email.send',
    rate: { limit: 100, window: '1h', per: 'agent' }
  },
  judgment: 'block',
  message: 'Rate limit exceeded'
});

Step 5: Test in Sandbox

Use sandbox mode to test without affecting production:

const sandboxClient = new DeltaOS({
  apiKey: process.env.DELTAOS_API_KEY,
  environment: 'sandbox'
});

// Submit test Intents
const intent = await sandboxClient.intents.create({
  action: 'payment.initiate',
  resource: 'accounts/test-123',
  parameters: { amount: 50000, currency: 'USD' }
});

console.log(intent.judgment);  // 'escalate' - exceeds threshold
console.log(intent.evaluations);  // See which policies applied

Common Integration Patterns

Pattern 1: Wrapper Function

Wrap existing functions with Intent submission:

function withGovernance<T extends (...args: any[]) => Promise<any>>(
  action: string,
  fn: T
): T {
  return (async (...args: Parameters<T>) => {
    const intent = await deltaos.intents.create({
      action,
      resource: 'default',
      parameters: { args }
    });

    if (intent.judgment !== 'allow') {
      throw new GovernanceError(intent);
    }

    return fn(...args);
  }) as T;
}

// Usage
const governedDelete = withGovernance('database.delete', deleteRecord);
await governedDelete(recordId);

Pattern 2: Middleware

Add governance as middleware:

// Express middleware
app.use('/api/actions', async (req, res, next) => {
  const intent = await deltaos.intents.create({
    action: req.body.action,
    resource: req.body.resource,
    parameters: req.body.parameters,
    context: {
      userId: req.user.id,
      requestId: req.id
    }
  });

  if (intent.judgment === 'allow') {
    req.intentId = intent.id;
    next();
  } else if (intent.judgment === 'escalate') {
    res.status(202).json({ pending: true, escalationId: intent.escalation.id });
  } else {
    res.status(403).json({ blocked: true, reason: intent.blockReason });
  }
});

Pattern 3: LangChain Integration

import { DeltaOSToolGuard } from '@deltaos/langchain';

const guardedTools = tools.map(tool =>
  new DeltaOSToolGuard(deltaos, tool, {
    action: `langchain.${tool.name}`,
    onBlock: (reason) => `Action blocked: ${reason}`,
    onEscalate: (escalation) => `Awaiting approval: ${escalation.id}`
  })
);

const agent = new Agent({ tools: guardedTools });

Handling Escalations

When an Intent is escalated, wait for human decision:

// Poll for decision
async function waitForEscalation(escalationId: string): Promise<Judgment> {
  const escalation = await deltaos.escalations.get(escalationId);

  if (escalation.status === 'pending') {
    await sleep(5000);  // Wait and retry
    return waitForEscalation(escalationId);
  }

  return escalation.decision;
}

// Or use webhooks
deltaos.webhooks.on('escalation.resolved', async (event) => {
  const { escalationId, decision, decidedBy } = event;
  // Resume workflow based on decision
});

Monitoring Integration

Check integration health:

const health = await deltaos.health.check();
console.log(health);
// {
//   status: 'healthy',
//   latency: { p50: '12ms', p99: '45ms' },
//   evaluationRate: 1250,  // intents/second
//   errorRate: 0.001
// }

Debugging

Explain Evaluation

const explanation = await deltaos.intents.explain(intentId);
console.log(explanation);
// {
//   intent: { ... },
//   policiesEvaluated: ['rate-limit', 'threshold-gate'],
//   evaluations: [
//     { policy: 'rate-limit', result: 'allow', reason: 'Within limits' },
//     { policy: 'threshold-gate', result: 'block', reason: 'Exceeds $10k' }
//   ],
//   finalJudgment: 'block'
// }

Dry Run

Test policies without recording:

const result = await deltaos.intents.dryRun({
  action: 'payment.initiate',
  resource: 'accounts/test',
  parameters: { amount: 25000 }
});

console.log(result.wouldBe);  // 'escalate'

Next Steps

• SDK Reference — Full API documentation
• Intent — Understand the data model
• LIMs — Policy evaluation modules
• Custom LIM Development — Build custom policies

Troubleshooting

"Intent submission timed out"

Check network connectivity and API status at status.deltaos.ai.

"Unknown action type"

Register custom actions:

await deltaos.actions.register({
  name: 'custom.action',
  description: 'My custom action',
  parameters: { schema: { ... } }
});

"Policy evaluation failed"

Check policy syntax and ensure all required evidence is available. Use explain to debug.