marona 0.6.2

Provider-neutral AI runtime and MCP/Skill gateway for Hub connections, managed responses, and external agents.

Marona Dart SDK

Provider-neutral AI runtime and MCP/Skill gateway for Marona Hub connections, managed responses, and bring-your-own-agent integrations.

dependencies:
  marona: ^0.6.2

1. Marona Hub

Connect Apps and governed Skills as one neutral MCP tool collection.

import 'dart:io';
import 'package:marona/marona.dart';

final marona = Marona(
  apiKey: Platform.environment['MARONA_API_KEY'],
);

final connection = await marona.hub.connect(
  apps: ['sda-books'],
  skills: ['download-book'],
);

final tools = connection.listTools();
final result = await connection.callTool(
  'skill__download_book',
  arguments: {'request': 'Download Steps to Christ'},
);

McpConnection is not tied to OpenAI, LangGraph, CrewAI, or another model vendor. It exposes:

connection.listTools();
await connection.callTool(name, arguments: arguments);
connection.serverUrl;
connection.serverUrls;
connection.warnings;
connection.session;

An unresolved App or Skill name does not discard valid tools. Check connection.warnings for its code, selector_type, slug, and corrective message. Authentication, permission, billing, and configured-server failures remain blocking errors.

Marona Hub owns discovery, identity, permissions, App and Skill resolution, approvals, governed execution, and online, offline, or hybrid availability.

2. Marona Runtime

Use responses.create(...) when Marona should manage model reasoning, tool selection, permission and approval checks, execution, and the final response.

final tools = await marona.hub.connect(
  apps: ['sda-books'],
  skills: ['download-book'],
);

final response = await marona.responses.create(
  model: 'gpt-5.6',
  tools: tools,
  input: 'Download Steps to Christ',
);

print(response.outputText);

The same request supports managed, direct-provider, private, and local models:

model: 'gpt-5.6'                    // Marona-managed model
model: 'openai/gpt-5.6'
model: 'anthropic/claude-sonnet'
model: 'google/gemini'
model: 'ollama/qwen3'
model: 'litellm/local-qwen'
model: 'local/qwen'

Register only custom providers or downloaded in-process models:

await marona.models.register(
  name: 'office/company-assistant',
  provider: 'custom',
  endpoint: 'https://models.office.example/v1',
  model: 'company-assistant-v2',
  apiKey: officeModelApiKey,
  adapter: officeNativeAdapter,
);

await marona.models.register(
  name: 'local/qwen',
  executor: qwenExecutor,
  contextWindow: 8192,
  maxOutputTokens: 512,
);

Images And Documents

final response = await marona.responses.create(
  model: 'openai/gpt-5.6',
  input: [
    {
      'role': 'user',
      'content': [
        {'type': 'input_text', 'text': 'Summarize this document and image.'},
        {'type': 'input_image', 'image_url': 'https://example.com/image.jpg'},
        {
          'type': 'input_file',
          'filename': 'report.pdf',
          'file_data': 'data:application/pdf;base64,...',
          'detail': 'high',
        },
      ],
    },
  ],
);

3. Bring Your Own Agent

The external framework owns its Agent, reasoning, and orchestration. Marona supplies neutral MCP tools and retains authorization, approvals, and execution.

final connection = await marona.hub.connect(
  apps: ['sda-books'],
  skills: ['download-book'],
);

final frameworkTools = yourFrameworkMcpAdapter(connection);
final agent = YourAgent(
  name: 'Book Assistant',
  model: 'gpt-5.6',
  instructions: 'Help users find and download books.',
  tools: frameworkTools,
);

final result = await agent.run('Download Steps to Christ');

An MCP-compatible framework can map its standard list-tools and call-tool hooks directly to connection.listTools() and connection.callTool(...). One Dart object cannot automatically satisfy every framework's proprietary tool interface, so any framework-specific conversion belongs at that boundary.

OpenAI Agents SDK Example

The OpenAI Agents SDK example uses the Python Marona package and keeps the OpenAI-specific adapter at the framework boundary:

from agents import Agent, Runner
from marona import Marona

marona = Marona(api_key="YOUR_MARONA_API_KEY")
connection = marona.hub.connect(
    apps=["sda-books"],
    skills=["download-book"],
)

framework_tools = your_openai_agents_mcp_adapter(connection)

agent = Agent(
    name="Book Assistant",
    model="gpt-5.6",
    instructions="Help users find and download books.",
    tools=framework_tools,
)

result = Runner.run_sync(agent, "Download Steps to Christ")
print(result.final_output)

your_openai_agents_mcp_adapter(...) represents the OpenAI-specific adapter; it is not part of Marona's vendor-neutral core API.

Execution Modes

final marona = Marona(
  apiKey: maronaApiKey,
  mode: 'hybrid',
);

• online: network models and online MCP targets are allowed.
• hybrid: local/private execution may fall back to online execution.
• offline: only installed local Apps, Skills, data, and local models run.

Changing model never changes App, Skill, permission, approval, or MCP rules.