marona 0.6.4

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

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.3

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: ['group-fund'],
  skills: ['create-group-fund'],
);

final tools = connection.listTools();
final result = await connection.callTool(
  'skill__create_group_fund',
  arguments: {'request': 'Create a family savings group fund'},
);

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, 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: ['group-fund'],
  skills: ['create-group-fund'],
);

final response = await marona.responses.create(
  model: 'gpt-5.6',
  tools: tools,
  input: 'Create a family savings group fund',
);

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: ['group-fund'],
  skills: ['create-group-fund'],
);

final frameworkTools = yourFrameworkMcpAdapter(connection);
final agent = YourAgent(
  name: 'Group Fund Assistant',
  model: 'gpt-5.6',
  instructions: 'Help users create and manage group funds.',
  tools: frameworkTools,
);

final result = await agent.run('Create a family savings group fund');

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=["group-fund"],
    skills=["create-group-fund"],
)

framework_tools = your_openai_agents_mcp_adapter(connection)

agent = Agent(
    name="Group Fund Assistant",
    model="gpt-5.6",
    instructions="Help users create and manage group funds.",
    tools=framework_tools,
)

result = Runner.run_sync(agent, "Create a family savings group fund")
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.