Put agentic AI inside your own product — not beside it.

Choose the first workflow, not the first feature

Pick a screen where users already lose time assembling context — a case detail page, a supplier record, a ticket queue. Embedded AI earns its place by removing the tab-switching around one screen, and that screen tells you exactly which endpoints become tools in step 3.

Bridge identity with one shared secret

Your backend already knows who the user is. Sign a short-lived HS256 token with the same JWT_SECRET_KEY the Agent Hub verifies with, and include an app_id claim so the platform knows which product is calling.

import jwt, time

def vdf_token(user, app_id="acme-erp", ttl=900):
    now = int(time.time())
    return jwt.encode(
        {
            "user_id": str(user.id),   # or "sub" / "uid"
            "app_id": app_id,          # identifies YOUR product
            "iat": now,
            "exp": now + ttl,
        },
        JWT_SECRET_KEY,
        algorithm="HS256",
    )

Agent Hub reads user_id, sub, or uid — first match wins — and scopes responses to that identity. Send it as Authorization: Bearer <token>.

Publish a tool manifest from your product

Expose one endpoint that describes the capabilities you are willing to lend an agent. Each entry is an endpoint you already own plus a JSON Schema for its parameters.

GET /api/tools/manifest

{
  "tools": [
    {
      "name": "acme_supplier_profile",
      "description": "Return the full supplier record, contracts and open risks for a supplier id.",
      "http_method": "GET",
      "endpoint": "/api/tools/acme_supplier_profile",
      "auth_method": "bearer_passthrough",
      "parameters_schema": {
        "type": "object",
        "properties": { "supplier_id": { "type": "string" } },
        "required": ["supplier_id"]
      }
    }
  ]
}

Write descriptions for a planner, not for a developer. The description and schema are what the platform reads when deciding whether this tool answers the sub-task in front of it.

Register the app and sync its tools

Registration is a server-side operation performed by an operator or your installer. It records the callback base URL, the manifest location, and the agent allowlist, then upserts every manifest entry into the shared tool catalogue.

from app.services.app_registry_service import register_app, fetch_and_sync_tools

register_app(
    app_id="acme-erp",
    display_name="Acme ERP",
    callback_base_url="https://erp.acme.internal",
    allowed_agents=["supplier_risk_analyst", "contract_summarizer"],
)

fetch_and_sync_tools("acme-erp")
# -> {"app_id": "acme-erp", "tools_synced": 4, "manifest_url": "..."}

Re-run the sync whenever your manifest changes; entries are upserted by tool name, so a new release adds capabilities without a migration.

Scope what the embedded surface may do

Three controls stack, and you should set all three before the first customer sees the panel:

• allowed_agents on the registered app — requests carrying your app_id can only reach the agents on that list.
• Domains — each domain carries its own context instructions, tool preferences, model hints, and a regulated flag that forces routing to approved models only.
• Themes — the catalogue grouping that decides which agents your customers actually see listed in your UI.

Call the agent from your own screen

Keep the call server-side so the shared secret never reaches a browser. Carry session_id back into the next turn and the conversation keeps its thread.

curl -X POST "$AGENTHUB/api/agent/execute" \
  -H "Authorization: Bearer $VDF_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "supplier_risk_analyst",
    "prompt": "Summarise open risks for supplier 41822 before tomorrow renewal call.",
    "context": { "client_id": "acme-erp", "session_id": "6f0e…" }
  }'

The response carries output, the provider and model that served it, a token usage block, and an execution_id you can store next to your own record for traceability.

Meter it the way you intend to sell it

Every metered call resolves the user, company, and plan, estimates the request, reserves that estimate so concurrent calls cannot overshoot a hard limit, executes, then records the provider's actual usage. Decide early whether AI is bundled into your existing tiers or sold as an add-on — the per-tenant records support either, but retrofitting the commercial model is harder than choosing it.

Ship it wherever your product ships

The same containers install inside a customer's perimeter. For an on-prem release, hand your installer three values — the Agent Hub base URL, the shared JWT secret, and the callback base URL your product answers on — then register the app during setup. Air-gapped customers additionally pin routing to local models; see the Day 1 Docker quickstart for the base install.