Skip to content
jnguyen1294Public

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

openroe

openroe

A framework-agnostic Go SDK for defining and enforcing agent communication policies via a YAML Rules of Engagement (ROE) document. Use it to gate agent-to-agent message delivery without depending on any specific database, HTTP framework, or messaging system.

Quick start

package main

import (
    "context"
    "fmt"

    "github.com/jnguyen1294/openroe"
)

// ContactChecker implementation — plug in your own data source.
type myContactStore struct{}

func (s *myContactStore) AreContacts(ctx context.Context, senderID, recipientID string) (bool, error) {
    // query your contacts table or graph
    return myDB.HasActiveContact(ctx, senderID, recipientID)
}

func postToInbox(ctx context.Context, recipientROEYAML []byte, senderID, recipientID string,
    actionID string, params map[string]any) error {

    // Parse and validate the recipient's ROE document.
    doc, err := openroe.Parse(recipientROEYAML)
    if err != nil {
        return fmt.Errorf("invalid ROE: %w", err)
    }

    // Check the request against the ROE.
    // Pass nil checker if you know access != "contacts".
    violations, err := openroe.Validate(ctx, doc, senderID, recipientID,
        actionID, params, &myContactStore{})
    if err != nil {
        return fmt.Errorf("validation error: %w", err)
    }
    if len(violations) > 0 {
        return fmt.Errorf("blocked by ROE: %v", violations)
    }

    // ROE check passed — proceed to write the message to the inbox.
    return inbox.Write(ctx, senderID, recipientID, params)
}

ROE YAML reference

version: "1.0"                     # required

metadata:
  name: "My Agent ROE"
  description: "Controls who can message this agent and how"
  updated_at: "2024-01-01"

engagement_rules:
  access: contacts                  # open | contacts | closed (default: open)

engagement_actions:
  - id: request_quote               # required, must be unique
    description: "Request a price quote"
    required_params:
      - name: item_id
        type: string
        description: "The item to quote"
      - name: quantity
        type: integer
        description: "How many units"
    optional_params:
      - name: currency
        type: string
        description: "ISO 4217 currency code"
        format: "ISO-4217"

Access levels

Level Who can send
open Anyone (default when no ROE is set)
contacts Only established contacts (requires ContactChecker)
closed No one — all messages are blocked

Actions

When engagement_actions are defined, every inbound message must include an action_id matching one of the defined action IDs. All required_params for the chosen action must be present and non-empty in the request's params map.

violations, err := openroe.Validate(ctx, doc,
    "sender-uuid",
    "recipient-uuid",
    "request_quote",                          // action_id
    map[string]any{
        "item_id":  "widget-42",
        "quantity": 10,
    },
    nil,                                      // checker not needed for open/closed access
)

API

// Parse parses and validates a ROE YAML document.
func Parse(data []byte) (*Document, error)

// Validate checks a request against a parsed Document.
func Validate(ctx context.Context, doc *Document, senderID, recipientID string,
    actionID string, params map[string]any, checker ContactChecker) ([]string, error)

// ContactChecker is implemented by the caller to resolve contact relationships.
type ContactChecker interface {
    AreContacts(ctx context.Context, senderID, recipientID string) (bool, error)
}

Installation

go get github.com/jnguyen1294/openroe

Only dependency: gopkg.in/yaml.v3.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages