Difinity Platform Guide
Technical guide to Hub, the Platform API, the Flow runtime, policy controls, and run evidence.
Difinity.ai governs what AI agents and AI chat are allowed to do inside an organisation. This page describes the platform as it works today.
It is written for the people who decide whether to turn it on, and for whoever will own the first deployment. Everything below describes behaviour that is built, not planned.
What Difinity is
Difinity runs two kinds of work under one set of controls. If your agents only answer questions, most of what follows is more than the job needs. It earns its keep once an agent starts acting in systems that matter.
Governed chat is a person asking a model something. A governed agent is an assistant that can also act in other systems, such as sending an email or posting a message. Both run through the same enforcement pipeline. What differs is where the history comes from and whose credentials are used.
An organisation configures its use cases, agents and connections in Hub. People do the work in the chat and agent workspace at chat.difinity.ai. An application can also call the runtime directly.
Three things hold throughout. An agent does not set its own authority: every action is bounded by what its version binds, what the caller is entitled to and what the use case permits. Every action it takes leaves through a gateway that holds the credential and decides. What happened is written to an append-only record as it happens.
The parts and what each does
Difinity has four parts. Three are things an organisation configures or calls. The fourth is where actions actually happen, and nobody outside the platform calls it.
Hub
Hub is the administrative interface for an organisation: use cases, agents and their versions, connectors, tool servers, people, roles and permissions, billing, and the review of evidence.
Hub is an administrative interface, not the system that owns the state. It reads and writes through the Platform API.
Platform API
The Platform API at platform.difinity.ai is the system of record. It holds agents and agent versions, use cases, conversations and messages, connector and tool server registrations, approvals, the run trail, credits and metering, and identity records.
It also issues the short-lived tokens an application uses to reach the runtime.
The runtime reads what a run needs from the Platform API when the run starts, and cannot serve while the Platform API is unavailable.
Flow
Flow at api.difinity.ai is the runtime. It runs the guardrail pipeline, the model call, streaming and the agent loop. It holds no state of its own.
The tool gateway
Every action an agent takes leaves through the tool gateway (internally, Marshal). The gateway holds the credential, applies the rules the organisation set, decides, and acts.
An agent does not hold a credential. Every action on a connected system is proposed to a gateway that decides, holds the credential and acts. The exception is the code sandbox: if an agent's builder turns on Full internet, code in the sandbox can send data to any website without passing through the gateway.
People reach all of this through the chat and agent workspace at chat.difinity.ai, and applications reach it through the API.
How a governed run works
A turn runs in a fixed order, and the order is part of the code rather than a configuration option.
- The incoming message is checked first. Where the use case is configured to detect personal information, detected values are replaced. The message is also evaluated against the use case's compliance rules, topic scope and blocked words.
- Routing happens next, on the redacted text. Where the use case selects a model automatically, the router reads the redacted message and never the original.
- The model is called.
- The answer is checked before it is returned.
A refusal at any stage stops the turn. A request refused before the model is called never reaches a provider and is not charged. If an output check refuses an answer after the model has generated it, that model call has already happened and is metered.
An agent run puts a loop around that sequence. The agent thinks, proposes an action, the gateway decides, and the result comes back to the agent. The run is bounded, and an action that needs a person stops the run until that person answers.
Chat and agent runs share one pipeline. Whether a run is recorded is decided by the route, not by the caller. There is no request field that switches the trail off.
Agents
What an agent is
An agent is a named assistant that lives inside one use case and inherits that use case's policy. Several agents can share a use case. The agent itself has a stable identity and carries no configuration. Its configuration belongs to an agent version.
Agents are built in Hub. People run them in the workspace at chat.difinity.ai.
Purpose and instructions
Two fields do different jobs, and the difference matters.
Instructions are what the agent is told. They are sent to the model.
Purpose is what the agent exists to do, written by its author. It is not sent to the model. It is one of the things the gateway judges a proposed action against, so an agent built to answer questions about returns can be held to that when it proposes something else.
Versions and review
An agent version is an immutable definition: instructions, model, reasoning tier, tool bindings, knowledge and run limits. It is the unit that is reviewed, approved and published.
A version moves through Draft, In review, Approved, Published, then Superseded or Unpublished. A change note is required to submit one.
Whether a version needs review is a setting on the use case. If review is not required, submitting the version approves it directly. Who may approve is the Agents:approve permission, not a named approver group.
A conversation pins the version that is published at the moment it starts, so publishing a new version does not change a thread that is already running.
Tools, connectors and tool servers
An agent's tools are bound to the version, and each binding names the tool and the catalogue it was approved against.
The connector catalogue lists 169 apps. Apps connected through the Composio broker send each call to Composio in the United States (us-east-1), and Composio holds the linked account and its tokens. Other apps use Difinity's own connection or an official MCP server. An administrator can also add a REST API from its OpenAPI document, or register an MCP server. Hub labels these Tool servers. Agents can also use a built-in web search, which sends the query to Exa.
An administrator turns a connector on and chooses which of its tools agents may call at all. That is the organisation's ceiling. A person then connects their own account, and an agent acting for that person uses that person's credential, never anything wider than the ceiling.
An agent version can bind at most 32 tools, and every one is a deliberate choice rather than a default.
A published version keeps the tools it was approved with. Re-reading a tool server's list does not change a published agent. Picking up a new tool is a draft edit that goes back through review.
Authority is the intersection of three things: what the version binds, what the caller is entitled to, and what the use case permits. It is never a union.
Where a tool server runs under its own identity rather than the person's, Hub marks it as such, because a server like that can give a caller reach that person does not have.
Per-tool policy
Under each bound tool, the author writes when the agent may use it, in their own words. "Only email the customer on this order" is a policy.
That text is read by the judge and is never matched by a parser. Left blank, the judge has no rule of the author's to apply to that tool. That does not switch judging off for anything effectful, because the floor described below applies whatever the written policy says. A read-only tool with no written rule and no configured posture is not judged.
The gateway refuses any tool it holds no schema for. Arguments it cannot check are arguments it cannot constrain.
The judge
Every effectful action, meaning anything that changes something elsewhere, is read by the judge before it runs. A read-only tool is judged when its author wrote a rule for it or the organisation set a posture for it, and not otherwise. Where the judge runs, a first model tier on AWS Bedrock reads the call, a second tier on Bedrock reads the calls the first would not commit on, and a call neither tier can settle goes to a person.
The judge can only refuse or escalate. It can never permit something the deterministic rules refused, so its worst failure leaves the deterministic answer standing.
It never sees the conversation, because a judge given the conversation is given whatever was hidden in it.
Anything that changes something elsewhere is reviewed whatever the written policy says. Tools are marked as effectful or read-only, and the effectful ones carry a floor a policy cannot lower.
When the judge cannot decide, including when Bedrock cannot be reached, the outcome follows the tool's configured posture. An effectful tool escalates to a person whatever that posture says. A read-only tool set to permit is permitted, and a read-only tool that has a written rule but no posture escalates.
Approvals
By default the person the agent is acting for approves one of its actions. The agent's author can instead name one to ten people on a tool, and any one of them can decide. A run nobody answers expires.
An approval is single use.
An "always allow" answer is keyed to the policy clause that raised the question, and it is read back the next time that clause fires. It has no expiry, and there is no screen to list or withdraw one. The tool gateway keeps the arguments of submitted calls with no retention limit. A refusal is never standing, because "no, and never again" is a policy change rather than a side effect of an approval.
The person is shown the whole action and its arguments, not a summary. The answer is signed, and the gateway checks the signature and the digest against the action it stored before anything runs.
Reasoning tier and run limits
A version carries a reasoning tier, Quick or Deep. Deep is given a larger step budget, more time and a higher step ceiling per run. A per-run limit on credits is not enforced.
The tier belongs to the approved version and not to the request, so a caller cannot turn a quick assistant into an expensive one. There is no separate step budget for an author to set.
A run that reaches its ceiling stops and reports that it did.
Chat and agent workspace
chat.difinity.ai is the chat and agent workspace. It uses the same account as Hub, and one sign-in covers both. The workspace has no sign-up screen. A person can sign up through Hub, which creates a Free organisation.
Chat and agents
There are two workspaces. Plain chat runs against a chat use case the organisation has configured, and a person can pin one of that use case's models or let the router choose. An agent thread is bound to one agent, whose published version decides the model, so there is no picker.
Only agents with a published version are offered.
Files and document review
A person can attach a file. Accepted types are pdf, docx, pptx, xls, xlsx, csv, txt, md, html, json and xml. Legacy .doc and .ppt files are refused.
An attachment is at most 25 MB and is kept for 28 days.
Where an attached document carries personal information, the turn pauses and the person is shown the redacted copy of each document. They can correct it. Only what they confirm is sent, and the confirmed copy stays readable in the thread afterwards.
Watching a run
The workspace shows the run in the order it happened: the checks, the model's own reasoning, each tool call, and what a tool returned. The model that answered is shown on the answer.
A turn can be stopped. Stopping ends the run at its next step rather than hiding it.
Answering an approval in the thread
An action that needs approval appears in the thread at the point the run reached it, with the tool named and its arguments in full.
The arguments shown are the restored, real ones. That is what was signed and what will run.
What the workspace does not do
A conversation can be archived, which hides it while its messages remain. There is no rename. An organisation can use the self-service export for its data (transcripts of conversations the person running it owns or has been given access to, plus the organisation's trail), and a person can download back a file they attached, one file at a time until the file expires.
Integrating an application by API
An application can call the runtime directly instead of working through the workspace. The run is governed in the same way.
- An administrator registers the application in Hub and issues an API token. The token secret is shown once, when it is created, and never again.
- The administrator assigns the use cases that application may run against.
- The application exchanges its API token at
POST /api/v1/auth/exchangeon platform.difinity.ai and receives an identity token valid for 15 minutes. - It calls Flow at api.difinity.ai with that token, naming the use case on every request as the
use_case_idquery parameter or theX-Use-Case-IDheader. - An administrator reads the evidence in Hub. The calling application does not read the trail.
The default rate limit is 60 requests per 60 seconds per application. A 429 carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After.
Request and response shapes, the error envelopes, streaming and the provider-compatible endpoints are in the API reference.
Personal information
The boundary is one sentence. The model works on redacted text, and real values are restored in the last step before an action leaves through the gateway.
Restoring real values
An agent proposes actions in redacted form, because redacted text is all it has seen. The arguments are restored immediately before the action is submitted to the gateway, because every argument rule the gateway holds is written about real values.
An action waiting for approval shows the restored form, which is what was signed and what will run.
A run that stops for an approval keeps its redaction map, so results that arrive after the answer do not reach the model with real values in them.
Checking what comes back
A tool result is checked before the model reads it. Values already hidden in that session are hidden the same way in the result, so the model sees one stand-in per value. A result that cannot be checked is withheld.
What is configured, and what this does not do
What counts as personal information is configured per use case. Defaults are seeded where they can be read, narrowed or removed, and whatever stands there is what runs. An empty list stops the detector being called.
Detection is a model, and it is not perfect. Where a use case is set to protect, a failed check refuses the request rather than passing text on. Where it is set only to report, it never refuses, because someone who asked to be told about personal information has not asked for the conversation to stop.
Where detection and replacement are enabled, the trail records the redacted stand-ins used during the run, not the original detected personal values. This applies to recorded messages, model output, tool-call arguments and results, and policy reasons. If an organisation turns personal-information detection off, the trail stores the raw text and labels the run accordingly.
Evidence
There are two separate records. They exist for different purposes and must not be treated as interchangeable. This is where most of the confusion starts.
The run trail
The run trail, which Hub calls the AI Trail, is append-only evidence of one run: the message, each guardrail verdict, each model turn, each proposed action, the gateway's decision, approvals asked for and answered, each executed action, redactions, and the outcome.
It cannot be edited. The application role holds no update grant, the table carries no policy that would allow one, and a repeated write is rejected rather than stored twice.
The actor records who vouched for the person, not merely who was named: the subject, the issuer, and whether the identity was verified. Where an application asserts an end user of its own, the trail shows that as an unverified claim by that application.
A stated reason is displayed as a claim and never as a fact. The model writes it, and under a prompt injection that means an attacker writes it.
The Configuration Log
The Configuration Log holds the activity log, which is who changed what, and the access log, which is one request against the API surface. Both are append-only, and there is no route that edits either.
A transcript is not the trail
A transcript is the person's own data and keeps the real values for their own conversation history. The trail is evidence. Neither is derived from the other and both are written. Deriving one from the other would force a choice between refusing an erasure request and destroying evidence.
What the trail does not record
Where detection and replacement are enabled, tool arguments and results are recorded as redacted stand-ins, not the original detected personal values. If detection is turned off, the trail stores the raw text. The gateway also keeps a keyed digest of each result. Separately, the gateway keeps its own record of submitted calls, including refused and automatically allowed ones, with their arguments, and a memory of standing approvals as they ran. That record is not redacted and has no automatic expiry.
Redaction entries record the kind of value and its stand-in, not the original detected personal value.
Retention and erasure
Each organisation sets its own periods. The run trail defaults to seven years and cannot be set below six months. Transcript retention defaults to while the organisation remains subscribed and can instead be set to a specified number of days. If the organisation does not choose a period, those defaults apply. When a period expires, the applicable data is deleted. Mapping rows expire with the trail records they belong to.
A legal hold pauses scheduled expiry and erasure until the hold is lifted. Chat attachments and artifacts expire after 28 days, even under a legal hold. Runs waiting for approval can no longer be read after seven days, or after one day past the approval deadline if that is later, and never after more than 15 days. Database backups are kept for seven days with point-in-time recovery.
An organisation can use the self-service export while subscribed. The organisation enters the Terminated state only when authorised Difinity staff set that state. It then has 90 days to use the self-service export. At the end of that window, a scheduled job deletes the organisation's database records unless a legal hold pauses erasure. The export contains transcripts and the trail only. Transcripts are limited to conversations the person running the export owns or has been given live access to. The scheduled job does not delete run trails, which stay until their own retention period ends. Difinity removes files in storage and stored secrets by hand within 30 days of the end of the window. Stripe keeps the customer record under its own terms. Composio linked accounts and the gateway's call records are removed within 30 days of a request to privacy@difinity.ai. Database backups containing erased data age out seven days later; older versions of stored files are removed by hand.
The stand-in-to-original mapping is held apart from the trail and envelope-encrypted. A data key encrypts the values; one Platform AWS KMS key, configured for automatic rotation, protects the data key. Only a person with the PII:view permission can ask the server to reveal a mapped value, and every reveal is logged. The trail is therefore pseudonymised, not anonymous, while a revealable mapping exists.
Values masked with asterisks have no revealable mapping and cannot be revealed.
Metering and credits
Two units, never mixed
Every billable unit of work is recorded once, and the record says whose key paid for it.
Difinity funds model and tool work on credits. Where an organisation's own provider keys are enabled for it, that work is billed by the provider instead. One usage record never carries both.
Which one applies
Credits are how the work Difinity funds is metered. Work that runs on an organisation's own provider keys is priced by that provider, in the provider's own currency, and carries no credit charge.
Neither arrangement falls back to the other. A provider that cannot be paid for is left out, and if none can be paid for, the turn is refused rather than quietly charged the other way.
Tool calls are metered separately from model calls. A free tool is recorded at a zero rate rather than not recorded at all.
A request refused before the model is called never reaches a provider and is not charged. An answer refused by an output check after generation is metered.
Running out
Every plan carries a credit allowance. If an organisation's allowance has not been set up, a turn that uses Difinity's provider keys is refused.
When the balance reaches zero, or the organisation is suspended for an unpaid charge, a turn that uses Difinity's provider keys returns HTTP 402 with the error code OUT_OF_CREDITS. In the signed-in app's streaming routes the same error arrives as an event in the stream. It applies to applications calling the API as well. Work on an organisation's own provider keys is not refused for credits. The check runs before the model call. If Platform cannot answer the check, the turn goes ahead.
Credits are a prepaid ledger, and a balance is the sum of its entries. Usage is settled shortly after each run, so runs happening at the same time can spend past a balance by the amount in flight.
Paid plans are charged by card through Stripe. A failed charge gives 3 days of grace, then spending on Difinity-funded work stops until the amount is paid. Nothing is deleted.
This page publishes no credit price and no credit-to-token conversion. Rates are set in the applicable order form or enterprise agreement.
Where your data lives
Hosting regions
Difinity hosting is live in AWS Australia (Sydney). The European Union (Frankfurt) and the United States are available by arrangement, and a dedicated deployment is set up when a customer signs. The Platform API, Flow and the tool gateway run in the hosting region. Difinity-hosted models are called from the hosting region, but a call can be routed to another AWS region. Calls to model providers, to connector apps and to the built-in web search can leave the hosting region. Composio, which brokers many connector apps, processes in the United States (us-east-1).
The sub-processors page lists the vendors involved in delivering the service itself, and the region each one works in.
Difinity's own account and website data, including sign-in, is processed where those vendors host it. Those vendors are named in the privacy policy and the cookie policy, not on the sub-processors page.
Where it is stored
Service data sits in Aurora PostgreSQL 16.14 in private subnets with no public access, encrypted at rest with an AWS KMS key managed by Difinity, with 7-day backups and point-in-time recovery.
Attachment bytes sit in object storage under one prefix, and are removed 28 days after upload.
Provider keys and the credentials of connectors Difinity connects directly are held as write-only credentials, never in the database. For apps connected through Composio, Composio holds the linked account and its tokens. Sign-in is provided by Supabase Auth.
Credentials
Provider keys and connector credentials are write-only. They can be set, replaced and destroyed. No endpoint returns a stored credential, on the Platform API or on the tool gateway, and no screen can show one.
Removing a connector destroys every credential held for it, including the accounts individual people connected through it. For a brokered app, the linked account is deleted at Composio.
Model providers, and Difinity-hosted models
The configured model providers are OpenAI, Anthropic, Google and Grok (xAI). The built-in web search sends the search query and the caller's country to Exa. A query can contain personal information, and Difinity does not redact it, because redaction would stop the search returning correct results.
Difinity-hosted models do the platform's own work. Personal-information detection, the tool-call judge and compliance drafting run on AWS Bedrock. Subjective evaluation and the requirement router run on Amazon SageMaker.
The periods that are set
The run trail defaults to seven years with a six-month minimum. Transcripts default to while subscribed or can use a set number of days. Chat attachments and artifacts expire after 28 days. An agent run waiting for an approval can no longer be read after seven days, or after one day past the approval deadline if that is later, and never after more than 15 days. Database backups are kept for seven days with point-in-time recovery. A legal hold pauses expiry and erasure. A Terminated organisation has 90 days to use the self-service export before its data is erased; backups containing erased data age out seven days later.
Difinity staff access
Authorised Difinity staff use a separate, role-gated administration surface. They can administer organisations and people, billing, credits and plans, and view aggregate usage counts.
That surface does not give staff access to conversations, transcripts, run trails, agent definitions, prompts or uploaded files. Staff do not sign in as one of an organisation's people. There is no impersonation. Staff can be added to an organisation only in a non-admin role.
Every staff action on an organisation, including adding a staff member, is written to a privileged-access log that identifies the staff member and organisation. The application cannot update or delete these entries. The log is deleted with the organisation when it is erased. The log is available to authorised Difinity staff and is not currently visible through customer-facing interfaces.
The data processing agreement sets out the contractual side of all of this.
What agents can keep, and where
Agents can use memory, a knowledge library, a code sandbox, triggers and webhooks, alerts, sharing, artifacts, OpenAPI connectors and conversation-access grants. The sandbox has no internet by default. A builder can choose a listed-websites-only mode (not yet available in production), or choose Full internet, in which case code in the sandbox can send data to any website. A triggered run acts as the agent's own identity, not as a person. Memory and knowledge are kept until deleted. Artifacts expire after 28 days. A conversation-access grant lasts at most 7 days. The privacy policy has a table of what each feature stores, how long it is kept and who can see it.
Compliance evidence
Governed run records can contribute operational evidence to wider EU AI Act, ISO/IEC 42001, risk, and audit processes. Difinity does not determine that an organisation or AI system is compliant, and it does not provide ISO/IEC 42001 certification.
Legal, risk, security and compliance owners remain responsible for determining which obligations apply and how platform evidence is used within the organisation's broader programme.
Planning a first deployment
Start with one bounded job, and make the operating boundary explicit before anything is switched on. Start smaller than feels useful. Settle the commercial side with Difinity first: model and tool work runs on credits Difinity funds, unless an organisation's own provider keys are enabled for it.
Define the job
Write down the business outcome, the accountable owner, the people who will use it, the systems it touches, the data involved, and the actions it needs to take.
Decide the authority
Decide which actions the agent may complete on its own, which go to a person, and which it should not have at all. Bind only the tools the job needs, and write a per-tool policy for each tool that can change something.
Agree the evidence
Agree what security, risk, audit and business owners need to read after a run. Check that the connected systems provide the events that record needs.
Validate before expanding
Test the ordinary path, a policy refusal, a document with personal information in it, a system that is down, and an approval nobody answers. Read the resulting trail before giving the agent more to do.
Where to go next
- API reference: tokens, endpoints, errors, streaming and rate limits for an application.
- Data processing agreement: the processing terms, the security measures and the transfer mechanisms.
- Sub-processors: who else is involved, and for what.
- Platform overview: the product in shorter form.
- Request a demo to talk through a specific job.