Skip to main content

Building an integration

This section is for developers embedding Delegate agents into their own application — giving each of their customers an agent that can search, act on, and answer questions about that customer's data.

It describes a specific, deliberate shape. If your application is multi-tenant — each customer isolated from the others — this shape maps onto it cleanly and is the one we recommend. The running example is a photo application whose users ask things like "show me pictures of Sean in the winter", but nothing here is specific to photos.

The shape​

One agent per customer, all owned by a single service account, and each customer's own credential is what scopes their agent.

your customers (N)  →  one Delegate tenant  →  one Delegate service user
                                                      │
                                            owns │  one agent per customer (N)
                                                      │
                                    each agent carries │  its own token (N)

Read the links carefully, because two of them are deliberately one:

  • One Delegate tenant for your whole integration.
  • One Delegate service user — your own account — that owns every customer's agent. Your customers do not get Delegate users. That is the point: a Delegate user carrying a customer's real email could sign in over SSO, and you don't want your customers holding a Delegate login. See the security model.
  • One agent per customer, owned by that service user.
  • One token per customer, held on that customer's agent and presented to your API on every tool call.

The last link is the one that does the security work. The agent holds a token you issued for that customer, and presents it to your API on every call. Your API decides which data to return from the token it just authenticated — not from anything the agent or the model said.

This means you can verify your own isolation by reading your own code. The alternative — passing the customer's identity as an argument in the request — leaves you unable to tell an argument the platform injected from one a model produced; they are the same field. With the credential carrying the scope, a model cannot widen it, because a model cannot author a bearer token.

Your service user's single API key drives any of its agents (ownership grants access), so your backend authenticates once and routes each customer's request to that customer's agent_id.

What you'll build​

Three things, in order:

  1. Expose your capabilities as tools. You stand up an MCP server in front of the operations an agent should be able to perform — search, look up, and any mutations you choose to allow. Delegate calls it; your server authenticates the per-customer token and scopes every response. See Exposing your tools over MCP.

  2. Provision a customer. At signup, one call creates that customer's agent and tool wiring, and discovers what your MCP server offers. See Provisioning customers.

  3. Let customers talk to their agent. You stream a task to the agent and render its progress. The Python SDK does this, with a fake transport so you can build the UI before wiring up a live agent.

What you need first​

  • A Delegate tenant for your application, and one service user inside it with the tenant-admin role. This is the account that will own every customer's agent; your customers never sign in as it or as anyone.
  • That service user's API key. It must be a user key (not a tenant key). Mint it once, in the browser, and keep it server-side. It is effectively a master key for your tenant — it provisions agents and drives all of them — so it lives only on your backend.
  • An MCP server reachable over HTTPS on a public address. (Delegate refuses to call private, loopback, or link-local addresses — see the security model.)

The one thing to confirm before you start​

This shape assumes each of your customers is isolated from the others — one customer's agent should only ever see that customer's data. That is what the per-customer token guarantees, end to end.

If instead several of your users share one dataset (a team, a household with a shared library), the boundary moves: the agent is scoped to the account, and you are responsible for deciding which member may see or change what. That is a sound design too, but it is a different one, and the token no longer draws the whole line. Know which you are building before you provision anything.