oxicode-sdk

Multi-agent SDK for oxicode — build isolated, secure, observable AI agent systems in Rust.

Overview

oxicode-sdk provides a fluent builder API for constructing single and multi-agent AI systems on top of oxicode-ai and oxicode-agent.

Key Concepts

Quick Start

use oxicode_sdk::prelude::*;

let oxicode = OxicodeBuilder::new()
    .with_builtins()
    .api_key("anthropic", "sk-ant-...")
    .build();

let agent = oxicode.agent(AgentConfig {
    model_id: "anthropic/claude-sonnet-4-20250514".into(),
    max_iterations: 20,
    ..Default::default()
})
.workspace("/my/project")
.coding_tools()
.system_prompt("You are a senior Rust developer.")
.build()?;

let (response, events) = agent.run("Refactor main.rs".into()).await?;
println!("{}", response.content);

Architecture

┌─────────────────────────────────────────────┐
│  OxicodeBuilder → Oxicode                           │  Engine + Registry
├─────────────────────────────────────────────┤
│  AgentBuilder → Agent                       │  Per-agent config
├─────────────────────────────────────────────┤
│  AgentGroup │ MessageBus │ Supervisor       │  Orchestration
├─────────────────────────────────────────────┤
│  Security │ Middleware │ Observability      │  Cross-cutting
├─────────────────────────────────────────────┤
│  Coordination (Queue + Memory + Consensus)  │  Inter-agent
└─────────────────────────────────────────────┘

Design Principles

• No global state — each Oxicode instance has its own isolated provider/model registries
• Streaming-first — every provider streams tokens
• Capability-based security — deny-by-default with fine-grained permissions
• Composable — agents combine into groups with different orchestration strategies
• Observable — tracing, audit, cost tracking, and event sourcing built in

Ownership Contract

See docs/oxicode-sdk-ownership.md for the canonical "who owns what" table. The SDK owns behavior (interfaces + reference impls); consumers own policy (domain thresholds, validation, tiering).

Feature Flags

Features

Security

use oxicode_sdk::prelude::*;

let audit = Arc::new(AuditLog::new(64));
let authorizer = Arc::new(Authorizer::new(Arc::clone(&audit)));

// Define roles
authorizer.define_role("coder", CapabilitySet::coding("/workspace"));
authorizer.define_role("reader", CapabilitySet::read_only("/workspace"));

// Bind to agents
authorizer.bind_role("dev-agent", "coder");

Observability

use oxicode_sdk::prelude::*;

// Distributed tracing
let tracer = Arc::new(Tracer::new());
{
    let mut span = tracer.start("agent-run", SpanKind::Agent);
    span.set_attribute("model", json!("claude-sonnet-4"));
}

// Cost tracking
let registry = Arc::new(ModelRegistry::new());
let cost = Arc::new(CostTracker::new(registry, CostTrackerConfig {
    per_agent_budget: Some(10.0),
    global_budget: Some(100.0),
    ..Default::default()
}));

Multi-Agent Orchestration

use oxicode_sdk::prelude::*;

let group = AgentGroup::new(
    GroupStrategy::Parallel { max_concurrency: 4 }
)
.agent(Arc::new(reviewer))
.agent(Arc::new(tester));

let result = group.run("Review this codebase.".into()).await?;
println!("Success: {}/{}", result.success_count(), result.results.len());

Coordination

use oxicode_sdk::prelude::*;

// Work queue with priority-based claiming
let queue = WorkQueue::new(WorkQueueConfig::default());
queue.enqueue("review", json!({"file": "main.rs"}), 5);
let item = queue.claim("agent-1", None);

// Shared memory with optimistic locking
let memory = SharedMemory::new();
let key = MemoryKey::new("reviews", "main-rs");
let v1 = memory.write(&key, json!("approved"), "agent-1", None)?;
let v2 = memory.write(&key, json!("merged"), "agent-2", Some(v1))?; // succeeds
memory.write(&key, json!("conflict"), "agent-3", Some(v1)); // fails: VersionConflict

// Consensus voting
let consensus = Consensus::new();
consensus.start("deploy-vote", vec!["agent-1".into(), "agent-2".into()], 0.5);

Feature Flags

Module Index

Crate Dependencies

oxicode-ai  ←  oxicode-agent  ←  oxicode-sdk

License

MIT