marona 0.8.4

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

Marona Dart SDK

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

dependencies:
  marona: ^0.8.4

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'],
);

// Connect every App and Skill available to this developer key.
final connection = await marona.hub.connect();

Select a smaller capability set when needed:

final connection = await marona.hub.connect(
  apps: ['group-fund'],
  skills: ['create-group-fund'],
);

Use the connection directly:

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. With no selectors, online and hybrid connections include every capability available to the developer key; offline connections include every capability installed on the device.

Connected Apps execute through Marona governance. When an App such as Google Contacts or Calendar needs sign-in, the tool result includes structuredContent.authorization_url and a link artifact. Pass userId when calling a tool directly so the resulting service connection belongs to the correct end user:

final result = await connection.callTool(
  'contacts__search_contacts',
  arguments: {'query': 'John'},
  userId: 'customer_482',
  conversationId: 'chat_91a7',
);

2. Marona Agent

Use Marona's Agent and Runner when you want one simple managed agent API.

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

final agent = Agent(
  name: 'Customer Assistant',
  model: 'marona/gpt-5.6',
  instructions: 'Help the customer.',
  tools: tools,
);

final result = await Runner.run(
  agent,
  'Download Steps to Christ',
  userId: 'customer_482',
  sessionId: 'chat_91a7',
);

print(result.finalOutput);

userId is optional. sessionId is also optional and defaults to default. Marona derives the developer scope from the authenticated API key and keeps conversation history isolated by developer, user, and session.

3. 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: 'marona/gpt-5.6',
  tools: tools,
  input: 'Create a family savings group fund',
);

print(response.output);

Every request requires the Marona developer key. Managed models use only that key and consume the developer's Marona balance at the underlying provider price. Direct-provider models also require the provider key and are billed by that provider.

model: 'marona/gpt-5.6'
model: 'marona/gpt-5-mini'
model: 'marona/gpt-5-nano'
model: 'marona/claude-sonnet'
model: 'marona/gemini-2.5-pro'
model: 'marona/deepseek-chat'

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

model: 'openai/gpt-5.6'                       // Marona key + OpenAI key
model: 'openrouter/anthropic/claude-sonnet'   // OpenRouter
model: 'anthropic/claude-sonnet'              // Anthropic directly
model: 'google/gemini'                        // Google directly
model: 'ollama/qwen3'                         // Ollama
model: 'litellm/local-qwen'                   // LiteLLM gateway
model: 'local/qwen'                           // Downloaded/in-process model

Pass direct-provider credentials when creating the Dart client. OpenRouter uses its standard endpoint automatically and preserves the remaining model slug:

final marona = Marona(
  apiKey: 'YOUR_MARONA_API_KEY',
  providerCredentials: {
    'openrouter': 'YOUR_OPENROUTER_API_KEY',
  },
);

final response = await marona.responses.create(
  model: 'openrouter/anthropic/claude-sonnet',
  input: 'Help me with this request',
);

print(response.output);

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

import 'package:marona/marona.dart';

final marona = Marona(apiKey: 'YOUR_MARONA_API_KEY');

final response = await marona.responses.create(
  model: 'openai/gpt-5.6',
  input: [
    {
      'role': 'user',
      'content': [
        {'type': 'input_text', 'text': 'Summarize this image.'},
        {'type': 'input_image', 'image_url': 'https://example.com/image.jpg'},
      ],
    },
  ],
);

print(response.output);

Files

import 'package:marona/marona.dart';

final marona = Marona(apiKey: 'YOUR_MARONA_API_KEY');

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

print(response.output);

4. 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: 'marona/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="marona/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.

8. Publish A Skill

Every workflow entry uses step(); type selects reasoning, approval, or App execution. New Skills default to private.

final request = step(
  id: 'understand-request',
  type: 'reasoning',
  instruction: 'Extract the group name and currency.',
  inputs: {'message': '{{ context.user_message }}'},
  outputs: {'name': 'string', 'currency': 'string'},
);
final permission = step(
  id: 'confirm-create',
  type: 'approval',
  message: 'Create the requested group fund?',
  outputs: {'approved': 'boolean'},
);
final definition = SkillDefinition(
  name: 'create-group-fund',
  description: 'Create a group fund after explicit user approval.',
  visibility: 'public',
  governs: ['group-fund.create_group'],
  steps: [
    request,
    permission,
    step(
      id: 'create-group',
      type: 'app',
      app: 'group-fund',
      capability: 'group-fund.create_group',
      instruction: 'Create the approved group.',
      condition: permission.output('approved'),
      inputs: {
        'name': request.output('name'),
        'currency': request.output('currency'),
      },
      outputs: {'group_id': 'string', 'name': 'string'},
    ),
  ],
);

await marona.skills.publish(definition, version: '1.0.0');

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.