Advanced usage

This is the official documentation of the agent_ruby Ruby agent.

When an RPC agent needs to reference collections from another RPC agent, you can import the collection by defining an RPC datasource that references the RPC agent. The collections are now available for any type of customization.

Then use mark_collections_as_rpc: true to indicate that the imported collections are provisioned by another agent.

Example architecture overview

RPC Architecture

module ForestAdminRpcAgent
  class CreateRpcAgent
    def self.setup!
      # 1. Add local datasource
      datasource = ForestAdminDatasourceActiveRecord::Datasource.new(Rails.env.to_sym)
      @agent = ForestAdminRpcAgent::Agent.instance.add_datasource(datasource)

      # 2. Add remote RPC datasource with mark_collections_as_rpc option
      @agent.add_datasource(
        ForestAdminDatasourceRpc.build(uri: 'http://customers-app:3002'),
        mark_collections_as_rpc: true
      )

      # 3. Define cross-RPC relations 🍝
      # In this example, we are in the Billing RPC Agent:
      # - 'Invoice' is a local collection (from Billing datasource)
      # - 'User' is a remote collection (imported from Customers RPC Agent)
      @agent.customize_collection('Invoice') do |collection|
        collection.add_many_to_one_relation(
          'user',
          'User',
          { foreign_key: 'user_id', foreign_key_target: 'id' }
        )
      end

      @agent.customize_collection('User') do |collection|
        collection.add_one_to_many_relation(
          'invoices',
          'Invoice',
          { origin_key: 'user_id', origin_key_target: 'id' }
        )

        # You can also add computed fields on remote collections
        collection.add_field('full_name', {
          column_type: 'String',
          dependencies: ['first_name', 'last_name'],
          get_values: proc { |records| records.map { |r| "#{r['first_name']} #{r['last_name']}" } }
        })
      end

      @agent.build
    end
  end
end

Fine-grained control with mark_collections_as_rpc

For more control over which collections to mark, use mark_collections_as_rpc manually:

# Mark specific collections
@agent.mark_collections_as_rpc('User', 'Address')

# Or use regex to mark a pattern of collections
@agent.mark_collections_as_rpc(/^admin_/)

After adding a remote RPC datasource, you can use all standard customization methods (import_field, add_field, add_action, etc.) on its collections before marking them as RPC.

Supported relation types

Relation type	Use case
add_many_to_one_relation	Local record belongs to one remote record
add_one_to_many_relation	Remote record has many local records
add_one_to_one_relation	One-to-one mapping between local and remote
add_many_to_many_relation	Many-to-many through a junction table

How ReconciliateRpc works

If you rename collections in your RPC agents, make sure all agents are synchronized. The ReconciliateRpc plugin relies on collection names matching across all agents.

The ReconciliateRpc plugin must be added in the main agent:

# In your main agent (create_agent.rb)
@agent.use(ForestAdminDatasourceRpc::ReconciliateRpc)