Skip to main content

Embedded agents

An AI agent inside your product, calling your own functions.

Distri runs the agent. Your web or mobile app hands it functions as client-side tools, and they run where the user is: in the browser or on the phone, with their session, your state and your permissions.

Client-side tools

The agent runs on Distri. Its tools run in your app.

A client-side tool is a function you already have, handed to the agent with a name and a JSON Schema. When the model calls it, Distri sends the call to the open page or app, and your handler runs there.

So the agent can fill your form, add to your cart, move your router or read what is on screen, and you never build a backend API for it or hand it a credential.

  1. 1
    The user asks, in your UI

    Add two oat milks to my cart

    message
  2. 2
    Distri runs the agent and calls the modelagent shop_assistant · model gpt-4.1-mini
  3. 3
    The model calls a tool it was givenadd_to_cart({ sku: "oat-milk-1l", qty: 2 })
    tool call
  4. 4
    Your function runs, where the user isawait cart.add("oat-milk-1l", 2)
    • your state
    • the user’s session
    • your permissions
    result
  5. 5
    The result goes back to the model{ ok: true, items: 3 }
    reply, streamed
  6. 6
    The agent answers, and the cart has already changed

    Added 2 × Oat milk 1 L. Your cart has 3 items.

No endpoint was built for the agent, and no credential left your app. Distri saw a tool name, its arguments and what your function returned.

What a tool can be

  • fill_field
    Fill the form on screen

    Write into the same form state your inputs use, so validation and autosave still run.

  • set_filters
    Change app state

    Call your store or reducer. The UI updates the way it does when the user clicks.

  • go_to
    Navigate

    Push a route with your own router and land the user on the right screen.

  • get_orders
    Call your existing API

    fetch() from the page sends the user’s cookies, so your backend applies its usual permissions.

  • cancel_order
    Ask before acting

    Leave autoExecute off and the chat shows Approve and Decline before the handler runs.

In code

One tool, three ways to mount it.

Define the tool and render the chat in React, React Native (preview) or with a script tag. On the other side is the agent that is allowed to call it: a markdown file.

In your app Define the tool, mount the chat

import '@distri/react/styles.css';
import { useMemo } from 'react';
import { DistriProvider, Chat } from '@distri/react';
import type { DistriFnTool } from '@distri/core';
import { useCart } from './cart';
export function ShopAssistant() {
const cart = useCart(); // your state, as it is
const tools = useMemo<DistriFnTool[]>(() => [{
name: 'add_to_cart',
description: 'Add a product to the cart',
type: 'function',
parameters: {
type: 'object',
properties: {
sku: { type: 'string' },
qty: { type: 'number' },
},
required: ['sku'],
},
autoExecute: true, // leave out to ask the user first
handler: async ({ sku, qty = 1 }) => {
await cart.add(sku, qty); // runs in the browser
return { ok: true, items: cart.count };
},
}], [cart]);
return (
<DistriProvider config={{
baseUrl: 'https://api.distri.dev/v1',
clientId: 'dpc_…',
workspaceId: '…',
}}>
<Chat agentId="shop_assistant" externalTools={tools} />
</DistriProvider>
);
}

npm install @distri/react @distri/core

On Distri The agent that may call it

agents/shop_assistant.md
---
name = "shop_assistant"
description = "Helps shoppers find products and check out"
max_iterations = 5
[tools]
# Tools the page or app provides. ["*"] allows all.
external = ["add_to_cart", "get_cart"]
[model_settings]
model = "gpt-4.1-mini"
---
# ROLE
You help shoppers on our store. Use the page's tools
to read and change the cart. Never guess what a
tool can tell you.
# TASK
{{task}}

A markdown file with TOML front matter. external lists the tools your app provides; distri push ships it.

distrijs

The client libraries, MIT licensed: @distri/core, @distri/react, @distri/react-native and @distri/angular.

distrihub/distrijs

Quick start

Live in three steps.

  1. Write the agent, push it

    An agent is a markdown file. Install the CLI, sign in, and push the folder to your workspace.

    agents/shop_assistant.md
    ---
    name = "shop_assistant"
    description = "Helps shoppers check out"
    [tools]
    external = ["add_to_cart"]
    [model_settings]
    model = "gpt-4.1-mini"
    ---
    # ROLE
    You help shoppers on our store.
    Terminal
    curl -fsSL https://distri.dev/install.sh | sh
    distri login
    distri push

    The agent is in your workspace, ready to be called from your product.

  2. Hand it your functions

    Pass the functions the agent may call as client-side tools and render the chat. The handlers run in the browser.

    App.tsx
    // npm install @distri/react @distri/core
    const addToCart: DistriFnTool = {
    name: 'add_to_cart',
    description: 'Add a product to the cart',
    type: 'function',
    parameters: {
    type: 'object',
    properties: { sku: { type: 'string' } },
    },
    autoExecute: true,
    handler: async ({ sku }) => {
    await cart.add(sku); // your code
    return { ok: true, items: cart.count };
    },
    };
    <DistriProvider config={{ baseUrl, clientId }}>
    <Chat
    agentId="shop_assistant"
    externalTools={[addToCart]}
    />
    </DistriProvider>

    Not on React? The same tool works from React Native or a script tag.

    A streaming chat renders inside your app. How client-side tools work

  3. Ask it something

    Open your app and type. The agent calls your function, and your UI changes the way it does for a click.

    Each run is recorded with its tokens and cost. Usage · Traces

Get started for free

You need a model provider key, for example OPENAI_API_KEY. Prefer your own machine? Run it locally, or follow the full guide.

Auth and identity

The browser never holds your API key.

There are two ways for an embedded agent to reach Distri Cloud. Both keep the secret on your side, and a local server needs neither.

A client ID, for a public page

A client ID is a public identifier made in project settings. It can read and invoke agents, nothing else, and only from the origins you allow. Enough for a chat widget on a site where visitors are anonymous.

<DistriProvider config={{ clientId: 'dpc_…' }}>
<Chat agentId="shop_assistant" />
</DistriProvider>

A short-lived token, for a signed-in user

Your backend exchanges its API key for a token and passes it to the page. The provider attaches it to every call and asks your endpoint for a new one when it expires.

<DistriProvider
config={{
baseUrl: 'https://api.distri.dev',
workspaceId: 'your-workspace-id',
accessToken: tokens.access_token,
refreshToken: tokens.refresh_token,
onTokenRefresh: async () => {
const res = await fetch('/distri/token', { method: 'POST' });
return (await res.json()).access_token;
},
}}
>
<App />
</DistriProvider>

The token says who the end user is

Pass an identifier_id when you issue the token, and every run made with it is recorded against that user or tenant. Add limits and that user gets their own daily and monthly token budget.

Usage history can then be filtered by the same identifier, so you can see what each of your users consumed.

// Issue a token for one of your users, with its own limits
await fetch('https://api.distri.dev/v1/token', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DISTRI_API_KEY}`,
'X-Workspace-Id': process.env.DISTRI_WORKSPACE_ID,
'Content-Type': 'application/json',
},
body: JSON.stringify({
identifier_id: 'user-123',
limits: { daily_tokens: 10000, monthly_tokens: 100000 },
}),
});

Architecture

What runs where.

Your app keeps the UI, the functions and the user’s session. Distri keeps the agent loop, the model calls and the record of what they cost.

PieceIn your appOn Distri
The chat UIRendered in your page or app by @distri/react, @distri/react-native or the script-tag embed.Streams the run to it: messages, steps and tool calls.
Client-side toolsYour handlers run here, with your state, the user’s session and your permissions.Sees the tool name, its arguments and what your function returned.
The agentA markdown file in your repo, pushed with distri push.Runs the agent loop and calls the model, with your provider keys.
Other toolsNothing to host.Calls the remote MCP servers the agent lists.
CredentialsThe API key stays on your server. The browser holds a client ID or a short-lived token.Checks the token and the limits on it before each call.
Usage and tracesNothing to build.Records tokens and cost per agent and end user, and an OpenTelemetry trace per run.

Control

The user approves. Your design system styles it.

Human approval for tools

A tool runs straight away only when you set autoExecute: true. Leave it out and the chat shows Approve and Decline before the handler runs, which is what you want for anything that spends money or cannot be undone. Tools can also pause for a form or a picker; @distri/react ships the UI for them.

const cancelOrder: DistriFnTool = {
name: 'cancel_order',
description: 'Cancel an order by id',
type: 'function',
parameters: {
type: 'object',
properties: { orderId: { type: 'string' } },
required: ['orderId'],
},
// no autoExecute: the chat shows Approve and Decline
handler: async ({ orderId }) => {
await orders.cancel(orderId);
return { ok: true };
},
};

Theming

The chat is styled with CSS variables on Tailwind and shadcn/ui tokens. Import the default theme, or override the variables you care about: colours as HSL channels for light and dark, the radius, the width of the thread.

/* your-app.css */
@import '@distri/react/globals.css';
:root {
--primary: 220 90% 50%; /* HSL channels */
--radius: 0.5rem;
}
.dark {
--primary: 220 80% 60%;
}

Protocol-native

Open protocols in, open protocols out.

Nothing about an embedded agent is locked to Distri’s own clients. It speaks MCP to tools and A2A to callers, and the runtime is yours to host.

MCP-native

Besides your app’s functions, an agent can use remote MCP servers as tools, over Streamable HTTP or SSE. A connection can be shared by the workspace, or each end user authorises their own account from a one-time link.

[tools]
# your app's functions
external = ["*"]
# a remote MCP server
[[tools.mcp]]
server = "fetch"
include = ["fetch_*"]
exclude = ["fetch_secret"]
Tool configuration →

A2A-compatible

The embedded agent is also an A2A JSON-RPC endpoint with an agent card: message/send, message/stream, tasks/get and tasks/cancel. Your backend or another agent can call the same agent.

# Agent card
curl localhost:7777/agents/form_filler\
/.well-known/agent.json
# JSON-RPC, streamed over SSE
curl -N localhost:7777/agents/form_filler \
-d '{ "jsonrpc": "2.0", "id": "1",
"method": "message/stream",
"params": { ... } }'
API reference →

Self-hostable

Run the runtime on your own machine or servers and point the client at it, or push the same files to Distri Cloud. Client libraries are MIT; the server is fair-code.

# Run the runtime yourself
export OPENAI_API_KEY="sk-..."
distri serve # API on :7777
# Or push the same files to Cloud
distri login
distri push
Self-hosting →

Reference

One agent, reachable four ways.

Local runs need no account, only a model provider key. The same agent is then reachable from the terminal, your server, your UI, or plain HTTP.

# Install
curl -fsSL https://distri.dev/install.sh | sh
# Run an agent against a task
distri run --task "File a phishing report for John Smith" \
--agent form_filler
# Chat with it interactively
distri tui form_filler
# Serve it as a streaming API (listens on :7777)
distri serve
# Ship the whole agents/ skills/ templates/ tree to your workspace
distri push
distri push --dry-run # preview what would upload
distri push skills/my-skill # or push a single item
# Or push one resource at a time
distri agents push agents/form_filler.md
distri skills push skills/ --all
distri prompts push templates/system.hbs
# Pull the workspace back down into the same layout
distri checkout

Put an agent in your product today.

Free to self-host. Distri Cloud has a free tier.