Agent Runtime & SDK
Learn how the METAOS Agent Runtime executes your code and provides access to OS capabilities.
Runtime Architecture
The Agent Runtime is a secure execution environment that:
- Isolates agent code - Each agent runs in a sandboxed environment
- Enforces permissions - Only granted capabilities are accessible
- Manages lifecycle - Handles initialization, execution, and cleanup
- Provides tool APIs - Standard interfaces for storage, calendar, messages, etc.
Agent Entry Point
Every agent must export a handleIntent function:
export async function handleIntent(intent, context, tools) {
// Your agent logic here
// Return a response card or perform actions
}
export const intents = ["save_note", "list_notes"];Parameters
intent: string
The user's action request (e.g., "save_note", "schedule_meeting"). Must match one of your declared intents.
context: object
User input and session data:
{
text: "User's natural language input",
params: { /* Extracted parameters */ },
userId: "user-123",
timestamp: 1702994400000
}tools: object
API for calling OS capabilities (only tools you've been granted access to).
Available Tools
The tools object provides these APIs (when granted):
💾 tools.storage
Read, write, and search user's local storage
📅 tools.calendar
List events, create meetings, check availability
💬 tools.messages
Send texts, emails, and notifications
👥 tools.contacts
Search and read contact information
✋ tools.approval
Request explicit user confirmation for sensitive actions
Example Agent
// Note-taking agent
export async function handleIntent(intent, context, tools) {
if (intent === "save_note") {
const timestamp = new Date().toISOString();
const path = `metaos://notes/${timestamp}.md`;
await tools.storage.write({
path,
content: context.text
});
return {
type: "result",
title: "Note saved",
body: `Saved "${context.text.substring(0, 50)}..."`,
actions: [
{ label: "View all notes", intent: "list_notes" }
]
};
}
if (intent === "list_notes") {
const notes = await tools.storage.list({
path: "metaos://notes/*"
});
return {
type: "list",
title: "Your Notes",
items: notes.map(note => ({
title: note.name,
subtitle: new Date(note.created).toLocaleDateString(),
action: { intent: "view_note", params: { id: note.id } }
}))
};
}
return {
type: "error",
title: "Unknown intent",
body: `I don't know how to "${intent}"`
};
}
export const intents = ["save_note", "list_notes", "view_note"];Error Handling
The runtime catches errors and displays them to users. You can also return explicit error cards:
try {
await tools.storage.write({ path, content });
} catch (error) {
return {
type: "error",
title: "Failed to save note",
body: error.message
};
}Current Implementation Status
✅ Production-Ready Features
The platform includes zero-trust security and full agent lifecycle:
- Authentication: JWT tokens required for all API calls
- Zero-Trust Gateway: 4-step validation (installation → capability → policy → audit)
- Agent Marketplace: Browse, install, and manage agents via dashboard
- Capability Grants: Fine-grained permission control per agent
- Policy Engine: ALLOW/DENY/REQUIRE_APPROVAL decisions
- Audit Logs: Full action tracking with metadata and outcomes