Agent Development Kit (ADK)

The MIOSA ADK lets you build production-ready LLM agents that natively use MIOSA primitives — Firecracker sandboxes, full Linux desktops, and one-click deploys — with the tool-call loop already wired.

If @miosa/sdk is “call MIOSA APIs from code”, @miosa/adk is “build an AGENT that uses MIOSA”.

npm install @miosa/adk @anthropic-ai/sdk

30-second example

import { Agent, anthropicProvider } from "@miosa/adk";

const agent = new Agent({
  provider: anthropicProvider({
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: "claude-opus-4-7",
  }),
  miosaApiKey: process.env.MIOSA_API_KEY!,
});

const result = await agent.run({
  prompt:
    "Create a MIOSA sandbox, write a Python hello-world, run it, then destroy the sandbox.",
  maxIterations: 10,
});

console.log(result.finalText);

That’s it. The agent boots a sandbox, writes the file, runs it, prints output, destroys the sandbox, returns the final response. No tool-loop boilerplate.

ADK vs SDK

const computer = await client.computers.create({ name: "x" });
await computer.exec.bash("echo hello");

const agent = new Agent({ provider, miosaApiKey });
await agent.run({ prompt: "build a flask app and run it" });

Built-in MIOSA tools

When you pass miosaApiKey, the agent gets these tools out of the box:

Get an API key at https://miosa.ai/dashboard/api-keys, or run npx -y @miosa/cli mcp install to wire one via browser-based auth.

Custom tools

Compose your own tool catalogue alongside (or instead of) the MIOSA tools:

import {
  Agent,
  anthropicProvider,
  miosaTools,
  type Tool,
} from "@miosa/adk";
import { Miosa } from "@miosa/sdk";

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

const sendSlack: Tool = {
  name: "send_slack",
  description: "Post a message to the #builds Slack channel.",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"],
  },
  async execute(args) {
    const text = String(args["text"] ?? "");
    // your Slack call here
    return `Sent: ${text}`;
  },
};

const agent = new Agent({
  provider: anthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }),
  tools: [...miosaTools({ client: miosa }), sendSlack],
});

Streaming step events

Drive a live UI as the agent runs:

const result = await agent.run({
  prompt: "...",
  onStep: (step) => {
    console.log(`[turn ${step.index}] ${step.text}`);
    for (const call of step.toolCalls) {
      console.log(
        `  → ${call.name}(${JSON.stringify(call.input)}) → ${call.output.slice(0, 80)}`,
      );
    }
  },
});

The AgentStep shape:

interface AgentStep {
  index: number;
  text: string;
  toolCalls: Array<{
    id: string;
    name: string;
    input: Record<string, unknown>;
    output: string;
    isError: boolean;
  }>;
  usage?: { inputTokens: number; outputTokens: number };
}

Providers

@miosa/adk ships with one provider today; the Provider interface is small enough that adding more is straightforward.

Termination

agent.run() returns when:

• The model emits an end_turn with no further tool calls (normal completion)
• A stop_sequence is hit
• maxIterations is reached (default 10) — safety guard against runaway loops
• The provider throws (returned as stopReason: "error")

const result = await agent.run({ prompt: "...", maxIterations: 20 });
if (result.stopReason === "max_iterations") {
  console.warn("Agent didn't finish in 20 turns");
}

Quick comparison

The ADK is intentionally small. If you want MIOSA-as-execution-substrate with a clean agent loop, you’re in the right place.

What’s coming next

• Python ADK (pip install miosa-adk) — same surface, Python ergonomics.
• More providers — first-party OpenAI, Gemini, Ollama.
• Sub-agents — spawn child agents with scoped tool subsets.
• Memory — built-in conversation memory with TTL + summarization.
• Streaming output — token-by-token via provider.streamStep.

Open an issue at https://github.com/Miosa-osa/miosa/issues if there’s something you need sooner.