Environments

An environment is one end-customer your agents serve. When a single Fruxon org serves many customers off the same agents, the environment is how you keep each one separate — as a record you manage in the Directory, as the unit an agent is enrolled to serve, and as the tag that splits cost and analytics per customer.

Concretely, an environment gives you three things:

• A directory record — a display name, an immutable slug, an optional logo and description, and the contacts (the people at that customer) whose identity belongs to it.
• An enrollment target — enroll one of your Application's agents onto an environment and it answers that customer's connected channel directly.
• An analytics dimension — every run tagged with the slug rolls up into per-customer cost, usage, and trends.

When to use environments

Use environments when your backend embeds Fruxon to serve multiple customers from the same agent. Typical setups:

• B2B SaaS — one agent per product feature; you want to know what Acme Corp's usage costs separately from Globex's.
• Reseller / agency — you sell agent-powered automation to many end-clients off one Fruxon org.
• Multi-tenant chat product — each conversation belongs to one of your tenants.

If your agent serves one audience (your own users), you don't need environments — leave the field unset.

How environments work

An environment is a tenant-scoped row identified by a slug. Pass the slug on every relevant execution and Fruxon:

1. Auto-creates the environment on first sighting (no upfront setup required).
2. Tags the execution record with the slug.
3. Splits cost and usage analytics by environment in the dashboard and the per-environment summary endpoint.

Slug rules

A slug is a short, URL-safe identifier:

• Must start with a lowercase letter.
• Allowed characters: lowercase letters, digits, underscores. No hyphens.
• Maximum 64 characters.

Pattern: ^[a-z][a-z0-9_]+$

Examples: acme_corp, globex, customer_123.

The one-slug-per-customer rule

One slug per end-customer, reused across every execution for that customer.

This is the single most important thing to get right. The slug should map to a stable entity in your product — a tenant id, account id, workspace id — translated into a slug-safe form. Same customer → same slug, every time.

Passing a slug

From the API

Send environmentSlug in the body of any :execute or :stream call:

curl -X POST "https://api.fruxon.com/v1/tenants/$TENANT/agents/$AGENT:execute" \
  -H "Authorization: Bearer $FRUXON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": { "user_query": "Refund my last order" },
    "sessionId": "conv-7f2a",
    "environmentSlug": "acme_corp"
  }'

The :stream endpoint accepts the same field. See the execute endpoint for the full request shape.

From Agent Network

When you bind a participant channel or trigger to an agent, you can pin that inbound path to an environment. Every message or event that arrives through that path is tagged automatically — no API change in your channel handler.

From the SDK

Pass environment_slug to execute (or stream, stream_text). Your org is your Fruxon account; the slug segments your end-customers underneath it, passed per call — so a single client serves every environment.

from fruxon import FruxonClient

client = FruxonClient(token=os.environ["FRUXON_TOKEN"], org="my-org")
client.execute(
    "support-bot",
    parameters={"user_query": "Where's my order?"},
    session_id="globex-thread-42",
    environment_slug="globex",
)

Omit it and the run is untagged. Only tag real end-customer traffic, so your per-customer cost and analytics stay meaningful.

What you get back

The execution record carries the slug, which surfaces in Observability:

• The Execution History list — filter to one customer's runs.
• The environments fleet table on the agent Overview — execution count, cost (with share), error rate, p95 latency, and last-active per environment, with week-over-week trends.
• The compare view — overlay several environments' cost-over-time and metrics side by side.

Limits

When the cap is reached

Your organization admins receive an email with diagnostics — recently-created slugs, count created in the last 24h, and a likely-cause hint. If the cap was hit by a misconfigured integration (UUIDs as slugs, for example), you'll usually see the bug in the sample slugs.

A soft-warn email also fires when the organization crosses 80% of the cap, so you have time to fix a leaking integration before runs start failing.

If you legitimately need more than the cap allows, contact support to raise it.

Managing environments

Directory → Environments lists every environment in your organization — display name, slug, contact count, and when it was created. Open one to manage it.

Environments arrive two ways:

• Auto-created on first sighting of a new slug on a run — no setup call required.
• Created manually with Add environment, or brought in by a contact import that carries an external id.

The Default environment is a system record — Fruxon-managed and read-only. An environment auto-created during onboarding is marked Unverified until it's reconciled against a source record.

On an environment you can:

• Rename the display name and add a description and logo, so the fleet table and compare views read in human terms. The slug itself is immutable — it's the identifier used in connector bindings and API calls.
• Roll the account up to a group — the chain or holding it belongs to.

Contacts

An environment holds the contacts whose identity belongs to that customer. Link a contact two ways:

• Set the environment on a person from their Directory profile.
• Import contacts carrying this environment's external id.

Contacts are what an enrolled agent serves, and what a contact sync populates before enrollment.

Enrolling an agent

Enroll one of your Application's agents onto an environment to have it answer that customer's connected channel. Enrollment takes over the connected transport and silences any bot already replying there; offboarding hands it straight back.

Per-environment usage (execution count, cost, last active) lives in the agent's observability views, not the Directory list.

FAQ

What happens if I send a slug I've never used before? The environment is auto-created on first use. No setup call required.

Is the slug visible to the end-customer? No. It's a server-side tag. End-customers never see it.

Can I change a slug after the fact? No. Slugs are identifiers — change them and the execution history splits. If you renamed a customer in your system, register the new slug going forward; the old one stays in your history under its original slug.

Do I have to set this for every execution? No, it's optional. Leave it unset for runs not tied to a specific end-customer. Just be consistent — don't tag some of a customer's runs and leave others untagged, or the analytics will look incomplete.

Does this affect data isolation between my customers? No. Environments are an analytics dimension, not a security boundary. Fruxon's tenant isolation operates at the organization level — your data is isolated from other Fruxon customers, but everything within your org is in one tenant. Don't rely on environments to separate sensitive data.