This is a working guide to Kademi's agents framework: how an agent is defined, how work is shared between a root agent and its specialists, the difference between a tool and a skill, how much thinking and work a run is allowed, and how agents run on their own from events and timers. It also covers what agents remember, how to put an agent in front of your partners on a website, and how to review what agents have been doing. It is written for administrators who configure agents and for developers who build on them.

For a first introduction, start with The Agents Framework. For a step-by-step walk through the wizard, see How to Create an Agent Definition in Kademi.

Definitions and agents

Two words come up throughout, and the difference matters:

• An agent definition is a template. It says what the agent is for, what it is allowed to do, which model it runs on, and what makes it run.
• An agent is one person's instance of a definition. It always acts as that person, so it can only see and do what they could see and do. It holds no permissions of its own.

Everything here lives under AI Agents in the admin menu:

• Agents Designer: the definitions
• Agent Manager: the agents people have
• Web Access: the websites agents may read
• AI Chat History: every conversation, including runs nobody typed

Configuring an agent definition

Open a definition to see its tabs: Basic Information, Functions, Groups, Timers, Events, Skills and Memory. Each tab covers a separate part of the same agent.

1. Where the definition comes from. The definitions Kademi supplies come from an app, and the blue banner says this one is following the app, so it improves whenever the app is updated. Saving any change, even to the title, takes your own copy, and from then on that copy is used and app improvements stop reaching it. If an agent you changed starts behaving worse than the stock one, use Reset to app defaults. The exceptions are event handlers and skills, which you can add without taking a copy (see below).
2. Instructions: the agent's standing brief, given to it on every turn. This is the setting that most changes how an agent behaves.
3. Description: one line, read by other agents deciding whether to hand work to this one. The agent itself never reads it. Leave it blank unless the agent is a specialist.
4. Can delegate to: the specialists this agent may hand work to, as a comma-separated list of definition names. Leave it blank for an agent that does its own work.
5. Model tier: Fast, Balanced or Deep (see Thinking, models and budget).
6. Allow planning: lets the agent work out an approach before it acts. It costs an extra model call, so turn it on for multi-step work and leave it off for agents that answer questions.

Groups decide who may have an agent from this definition. They also limit delegation: an agent can only hand work to a specialist whose groups include the agent's owner.

The definition as XML

A definition you create is stored as an XML file in the account's queries repository, under agents/. Edit XML file on the Basic Information tab opens it. A few settings can only be changed there, including attributes, a pinned model and per-phase thinking levels. This is a complete definition for a partner-facing agent:

<agent>
  <name>PartnerHelper</name>
  <title>Partner Helper</title>
  <instructions>You help channel partners using our partner portal. Answer questions about the
    programme, how to earn and redeem points, and where to find things on the site. Search the
    documentation before answering, and say so when it does not cover the question rather than
    guessing. Keep answers short and friendly, and link to the page that has the detail.</instructions>
  <functions>
    <string>KPartnerAssistant2_searchDocumentation</string>
    <string>agents-lib_currentDateTime</string>
  </functions>
  <groups>
    <string>Customers</string>
  </groups>
  <attributes>
    <entry>
      <string>useJavaOrchestrator</string>
      <string>true</string>
    </entry>
  </attributes>
  <description>Answers partner questions about the programme from the site's own content.</description>
  <modelTier>balanced</modelTier>
</agent>

Supplying definitions from an app

Developers can ship definitions with an app, so every account that installs it gets them, and gets improvements when the app is updated. Register an agentDefProviders implementation in the app's APP-INF scripts:

controllerMappings.newImplementationBuilder('agentDefProviders').implementationObject({
    getAgentDefs: function () { return buildClaimsAgentDefs(); }
}).build();

function buildClaimsAgentDefs() {
    var atts = formatter.newMap();
    atts.useJavaOrchestrator = 'true';
    var def = services.agentManager.newAgentDefBuilder()
        .name('AcmeClaimsAgent.xml')
        .title('Claims helper')
        .instructions('You help administrators review sales claims...')
        .functions(formatter.toList(['KSalesData_queryClaims', 'agents-lib_currentDateTime']))
        .groups(formatter.toList(['administrators']))
        .attributes(atts)
        .build()
        .withDescription('Sales claims: finding, reviewing and correcting them.')
        .withModelTier('balanced')
        .withSkill('claims-policy', 'Claims policy', 'When a claim may be approved or rejected',
            'approve, reject, duplicate claim, evidence', '## Rules\n...', false);
    return formatter.toList([def]);
}

Call the build function from inside getAgentDefs, as above, rather than passing a variable from another file. A variable defined in a later source file may not exist yet when the app loads.

The root agent, specialists and delegation

The Kademi Copilot is a root agent. It holds almost no tools of its own. Its job is to understand the request, decide which specialist owns it, state the task in full and hand it over. Each specialist owns one area of the platform and holds the tools and knowledge for it:

A few rules shape how delegation behaves:

• The description is the only thing the root sees. When choosing a specialist, the root reads each one's name and description and nothing else, not even its tools. If a specialist is never asked about something it can do, fix its description.
• A specialist starts with only the task. It sees none of the conversation, so the root has to include every id, name and date range it needs. This keeps specialists focused and stops conversation history from growing with every tool the platform adds.
• Delegation is one level deep. A specialist does its own work and does not hand it on, and it does not plan. The root does that.
• The specialist runs as the same person. Delegating never widens what the agent can do.

In the Copilot panel, a delegation shows as a progress line naming the specialist:

Most agents you build will be single agents: a definition with its own functions and no Can delegate to. Build a root with specialists only when the work genuinely spans several areas.

Tools and skills

An agent has two ways to know how to do something. A tool (Kademi calls them functions) does something: it reads or changes data. A skill is a document the agent reads to learn how to approach a task.

Functions

• An agent can only call the functions its definition lists, and only when its owner holds the roles the function requires. That is checked again when the function runs, not just when it is offered.
• Names are prefixed with the app that supplies them, such as KReporting_ or admin-lib_, so you can see where each one comes from.
• Developers register functions through promptFunctionsProviders. A function is offered to agents only if its supportedUsage includes 'Agents', and only if it declares roles.
• Functions marked as needing consent stop and ask the user before they act, for example before deleting anything.

Skills

On every turn the agent sees each skill's name, purpose and keywords. When a task matches, it reads the body with a built-in readSkill call, either the whole skill or one ## section. A long skill therefore costs nothing on turns that do not need it. A skill marked always read is given to the agent in full on every turn instead. Use that for short rules that always apply.

Skills that come with an app are read-only on the Skills tab. To add your own without taking a copy of the definition, create agents/skills/<definition name>.xml in the queries repository with a <skills> root. Your skills are added to the app's, and a skill with the same name as an app skill replaces it.

Write a skill when an agent has the tools but keeps using them badly: the same mistake, the wrong default, an answer that is technically right but not useful. The best skills pair advice with the tool call that checks it, so the agent answers about this account rather than reciting general advice.

Thinking, models and budget

Three settings control how capable a run is and what it costs. Each is resolved the same way: what the run asks for, then the agent's own setting, then the platform default.

Model tier

An agent names the kind of model it needs, and Kademi picks the best model of that kind that your account has. An agent on a tier moves to newer models without anyone editing it. Pinning an exact model in the XML is possible, but it overrides the tier and keeps the agent on that model.

• Fast: routing, classifying, short answers. The Copilot root uses this.
• Balanced: the default. A specialist choosing among its tools and reading the results.
• Deep: work where a wrong answer is expensive, not just slow. The Developer agent uses this.

Thinking (reasoning effort)

Thinking is Low, Medium or High. Each stage of a turn has its own default: acting (calling tools) is Low, while planning and checking the result are Medium. Raise it for work where each step depends on what the last one found. You can set it:

• on an event handler, for every run that handler starts (see below)
• with the definition attributes actReasoningEffort, planReasoningEffort and verifyReasoningEffort, through Edit XML
• in code, for a single run, with withReasoningEffort('high')

Thinking and model tier set on a run also apply to the specialists that run hands work to, which is where the work happens.

Budget

Every run has a fixed allowance, sized for someone waiting for an answer:

Two settings raise the allowance. Both multiply it rather than removing it:

• Extra work allowance on an event handler, from 1 to 10. It multiplies tool calls and time for runs that handler starts. Nobody is waiting on an event-driven run, so it can afford to dig further than a chat answer.
• The toolCallBoost attribute on a definition. When a specialist is asked, it gets a fair share of the calls left: the calls remaining divided by the specialists still allowed. That is about 12 for the first one. toolCallBoost multiplies that share, so give it to a specialist whose work needs many calls. Account Security uses 4, and Developer uses 5.

When a run stops on a limit, it says which one. In AI Chat History this shows as Out of budget (see Reviewing chats). There is no separate limit on tokens. The tokens a run used are recorded and shown, but not capped.

Running on events

An agent can run by itself when something happens in the account. On the definition's Events tab, add a handler naming the event and saying what to do.

• Event name: a platform event such as LeadCreatedEvent, or the id of an event an app fires, such as OnAnomalyAlarm.
• Scope: All runs the handler for every agent made from the definition. Profile runs it only for the agent belonging to the person the event is about.
• Buffering: every run is an AI call, so events are collected and the agent runs once over the batch when either figure is reached. Use 1 event for something rare that deserves an immediate answer, and a larger batch for something frequent. Left blank, the defaults are 10 events or 300 seconds.
• Thinking, Model and Extra work allowance override the agent's normal settings for these runs only.

Things to know:

• Handlers run per agent, not per definition. A handler with scope All on a definition that fifty people have runs fifty times. Specialists have no agents of their own, so put handlers on a root or on a single agent.
• Adding a handler does not take a copy of the definition. Handlers you add, or app handlers you switch off, are stored separately in agents/events/<definition>.xml, so an app-supplied agent keeps following the app. A switched-off app handler is listed under Switched off with a Restore button.
• Each run appears in AI Chat History, titled Event: <event name>, with the events it handled.

For developers: firing an event an agent can handle

Agents do not run the moment an event fires. The event is stored, and the agent reads it back later. So an app has to declare that its event's attributes can be stored, by passing true to eventBuilder:

eventManager
    .eventBuilder(true)                         // attributes must be storable, checked as each is added
    .withTriggerId('OnClaimFlagged')
    .addAttribute('claimId', claim.id)
    .addAttribute('reason', reason)
    .addAttributeUrn('profile', 'profile', claim.profile)   // an entity is passed as a reference, never as itself
    .fireEvent();

Strings, numbers and dates are fine. A database entity such as a profile or an organisation is refused with an error naming the attribute. Pass it with addAttributeUrn instead, and the agent receives a reference like urn:profile:123. An event fired without true still works for ordinary event listeners, but agents ignore it and the server log says why.

Anomaly detection: having the AI explain an alarm

Anomaly detectors say what moved. An agent can work out why. Detectors fire three events: OnAnomalyDetected for every unusual period, OnAnomalyAlarm when a detector goes into alarm, and OnAnomalyRecovered when it returns to normal. Each event carries the detector's name, the period, the observed and expected values, the percentage of normal, the direction and a summary.

The Copilot has a handler for OnAnomalyAlarm ready to use, but it is off until you turn it on, because each investigation is an AI run. In the admin, go to Reporting > Anomaly detectors:

Once it is on:

• When detectors go into alarm, the Copilot collects the alarms (up to 3, or for 30 minutes) and investigates them together, because alarms that fire together are usually one incident. It runs with twice the standard work allowance.
• It hands the investigation to the right specialist, usually Reporting & Analytics, and to Account Security for errors or sign-in patterns. It breaks the period down by at least two dimensions, checks for other open alarms, and looks up captured server errors where they are relevant.
• It sends one report per run to each administrator who uses the Copilot, by email unless their remembered preferences ask for something else, such as Slack. The report answers three questions: is anything broken, does anyone need to act, and does the detector need tuning.
• On a detector that is in alarm, Investigate runs the same investigation immediately, for you only.
• To change or switch off the handler later, use the Copilot's Events tab in the Agents Designer.

Running on a timer

On the Timers tab, a timer runs the agent on a schedule with the instructions you give it:

• The time of day is in the agent owner's time zone, or the organisation's if they have none.
• Like event handlers, timers run per agent. A timer on a definition that ten people have runs ten times, once for each person, as that person. That is often what you want ("email me a summary"), but it is worth knowing before you start agents for a whole group.
• On Agent Manager, an agent's page lists its timers with their next run time, and Test runs one immediately.
• Runs appear in AI Chat History titled Timer: <timer name>.
• Unlike event handlers, saving a timer on an app-supplied definition takes your own copy of it. For scheduled work, create your own definition.

Memory

An agent remembers things between conversations, so nobody has to repeat themselves. What it remembers is given to it at the start of every run, including runs started by events and timers. There are two kinds:

• Personal facts are about one person and how they work: how they like answers, which part of the account is theirs, what a word means to them. Only that person's agent is ever told them. They are saved immediately.
• Account facts are about the business: when the programme year starts, what a bucket is for. Telling the agent one only proposes it. Until an administrator confirms it, it reaches only the person who said it.

• Memory belongs to a definition. Facts given to the Copilot are not known to another definition.
• Only the root agent remembers. Specialists see a single task, which is the wrong place to judge what is true about a person or a business.
• Administrators can see and decide on account facts. They cannot see other people's personal facts.
• Each person can have up to 50 facts, and each definition up to 50 confirmed account facts. Saving under an existing key replaces the old fact.
• Import from another agent can copy confirmed account facts to a new definition.

Agents on your website: KPartnerAssistant2

The same framework can put an agent in front of your partners. KPartnerAssistant2 adds a chat sidebar to a website, and a Chatbot component for pages. Each person who uses it gets their own agent from the definition you choose, acting as them.

A website agent is usually a single agent: one definition with a small set of functions suited to partners, no specialists and no planning. That keeps answers fast and predictable, and keeps the tools limited to what a partner should be able to do.

1. Create a definition for partners, like the Partner Helper above. Give it useJavaOrchestrator, a group your partners belong to, and only functions whose roles partners hold.
2. Install KPartnerAssistant2 and switch it on for the website on the website's Apps tab.
3. Go to AI Agents > Partner Assistant, choose the website, and pick the definition:

Things to know:

• The sidebar only appears to logged-in users who have agreed to the use of AI.
• The agent acts as the logged-in partner, so a function they lack the roles for is never offered.
• Functions that need consent show a button in the chat, and the action only happens when the partner clicks it.
• While the agent works, the sidebar shows what each tool is doing. The answer arrives complete rather than word by word.
• The built-in searchDocumentation function searches the site's own content. Set the definition attribute docsWebsite to search a different website.
• For anonymous visitors, use KCustomerAssistant instead. It runs every visitor's conversation through one agent owned by a profile you choose.

For developers building their own front end. KPartnerAssistant2 is a thin layer over the same server API, and you can use it directly:

var am = services.agentManager;
var agents = am.findAgentsForUser('PartnerHelper.xml', profile);       // one agent per person
var agent = formatter.isEmpty(agents)
    ? am.createAgent(am.findAgentDef('PartnerHelper.xml'), profile)
    : agents.get(0);

var acc = services.agentChatManager.initChat('MyApp', chatId, agent, null);   // null chatId starts a conversation
var answer = acc.prompt(question);    // runs the turn as the current user, and saves it
// afterwards: acc.chatId, acc.consent (an action awaiting approval), acc.contextUsage

Pass withConsentFunc({toolId, chatItemId}) on the next call to carry out an action the user approved. To show progress, listen for BeforePromptFunctionCall and push each tool's start message over your own websocket. For long-running work, follow the Copilot: queue the turn as a background task and send the reply over the websocket, rather than holding the request open.

Starting agents for people

An agent is created automatically the first time someone uses a definition in the Copilot or on a website. To give people an agent before then, for example so a timer runs for them, use Agent Manager > Start agents:

Reviewing chats

AI Agents > AI Chat History lists every conversation in the account. That includes the Copilot, website assistants, Slack, and runs nobody typed, such as timers, events and journey tasks.

The App name filter tells you where a conversation came from. Copilot conversations, and event and timer runs, are listed as Internal System. Website conversations are listed under their app, such as Partner Assistant 2. Each person's conversations are also on the AI Chats tab of their profile.

Opening a conversation shows a Summary of what the run did and what it cost:

The Transcript tab shows every step: the question, each function call with its arguments and output, each delegation with the exact task the specialist was given, and what it reported back. Open Full transcript to see the specialist's own run.

What to look for:

• Out of budget on a specialist means it was stopped before finishing, so the answer was built on incomplete work. If one specialist does this regularly, raise its toolCallBoost, or give the event handler that started the run more extra work allowance.
• The same tool many times in Tools used usually means the agent is gathering data one item at a time that a single query could answer. Look for a function that aggregates, or a skill that tells it which one to use.
• The wrong specialist, or a task missing details the user gave, points to the specialist descriptions or the root's instructions.
• Function output that is empty or an error, when the data exists, points to a problem with the function rather than the agent.
• Tokens spent is the cost of the whole run, specialists included. It is usually dominated by the tool descriptions sent with every call, which is why a long function list is expensive even when few are used.

Clear chat deletes a conversation permanently.

Related articles

• The Agents Framework
• How to Create an Agent Definition in Kademi
• How to Assign an AI Agent to Automate Journey Tasks
• Anomaly detectors
• Connecting to Kademi over MCP: the same tools, from an AI client outside Kademi