Integrating within your product

Embed Distri agents alongside your UI using the maps demo as a template.

1. Define maps.md

---
name = "maps_agent"
description = "Operate Google Maps tools to execute user instructions"
max_iterations = 3

[tools]
external = ["*"]

[model_settings]
model = "gpt-4.1-mini"
temperature = 0.7
max_tokens = 500
---

# ROLE
You are a decisive Google Maps agent. Follow user instructions directly and execute with tools. Be brief and action-first.

# CAPABILITIES
- set_map_center: Set map center to latitude, longitude with optional zoom (1–20).
- add_marker: Place a titled marker at latitude, longitude; optional description.
- get_directions: Retrieve route summary between origin and destination with optional travel_mode (DRIVING, WALKING, BICYCLING, TRANSIT).
- search_places: Find places near latitude, longitude within radius meters (default 5000).
- clear_map: Remove all markers and directions.

2. Start the server

distri serve --project .distri --port 8787

3. Define client tools

import type {DistriFnTool} from '@distri/core';
import type {GoogleMapsManagerRef} from './GoogleMapsManager';

export const getTools = (map: GoogleMapsManagerRef): DistriFnTool[] => [
  {
    name: 'set_map_center',
    description: 'Center the map',
    type: 'function',
    parameters: {
      type: 'object',
      properties: {
        latitude: {type: 'number'},
        longitude: {type: 'number'},
        zoom: {type: 'number', minimum: 1, maximum: 20, default: 13},
      },
      required: ['latitude', 'longitude'],
    },
    handler: async ({latitude, longitude, zoom}) => {
      await map.setMapCenter({latitude, longitude, zoom});
      return `Map centered at ${latitude}, ${longitude}`;
    },
  },
  // add_marker, get_directions, search_places, clear_map ...
];

4. Render chat + map

import {useRef, useState, useCallback} from 'react';
import {DistriProvider, Chat, useAgent, useChatMessages, DistriAnyTool} from '@distri/react';
import {APIProvider} from '@vis.gl/react-google-maps';
import GoogleMapsManager, {GoogleMapsManagerRef} from './GoogleMapsManager';
import {getTools} from './Tools';

const config = {baseUrl: import.meta.env.VITE_DISTRI_API_URL};
const GOOGLE_MAPS_API_KEY = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;

export function App() {
  return (
    <DistriProvider config={config}>
      <APIProvider apiKey={GOOGLE_MAPS_API_KEY} libraries={["places"]}>
        <MapsContent />
      </APIProvider>
    </DistriProvider>
  );
}

function MapsContent() {
  const {agent} = useAgent({agentIdOrDef: 'maps_agent'});
  const [threadId] = useState(() => crypto.randomUUID());
  const mapRef = useRef<GoogleMapsManagerRef>(null);
  const [tools, setTools] = useState<DistriAnyTool[]>([]);
  const {messages} = useChatMessages({threadId, agent});

  const handleReady = useCallback((instance: GoogleMapsManagerRef) => {
    setTools(getTools(instance));
  }, []);

  if (!agent) return null;

  return (
    <div className="maps-layout">
      <GoogleMapsManager ref={mapRef} onReady={handleReady} />
      <Chat agent={agent} threadId={threadId} initialMessages={messages} externalTools={tools} />
    </div>
  );
}