To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Definition of a single event handler an agent responds to, firing its instructions when a matching event occurs. Matching events can optionally be buffered for a time window or up to a count before the handler fires with the collected events. An account may add its own handlers to a definition an app supplies, and may replace or disable the ones the app declares, without taking a copy of the whole definition - see AgentDef.AgentDefEventHandlerSet. Written as an event element inside the agent element.
Group: AI Agents
Properties
| Property | Returns | Description |
|---|---|---|
| budgetBoost | Integer | How much more work this handler's run may do than an interactive turn, as a multiple of the standard ceilings. An event handler runs unattended, minutes after the thing it is about, and is often asked a question worth more querying than a chat question - "why did this metric move" is answered by breaking a period down, looking at what that returns and breaking it down again. The standard budget is sized for someone watching a spinner, and a specialist reaching the end of it mid-investigation reports a failure rather than an answer. |
| bufferSecs | Integer | If set, matching events are buffered for up to this many seconds before the handler fires with the events recorded during that window. |
| bufferSize | Integer | If set, matching events are buffered until this many have been recorded, then the handler fires with them. |
| disabled | boolean | Whether this handler is switched off, ie present in the definition but not listening. How an account takes away a handler its app supplies: the app keeps declaring it, the account's copy says disabled, and the definition otherwise carries on following the app. |
| instructions | String | Instructions run when a matching event fires. |
| modelTier | String | Which class of model this handler's run should use, named for the job rather than for a model: fast, balanced or deep. A definition already carries a tier for its own interactive use, and the root agent's is deliberately fast because routing is nearly always obvious. That is the wrong setting for a handler whose job is working something out - and it matters more than it looks, because a specialist inherits the model of the run that delegated to it, so this raises the whole tree rather than just the agent that received the event. |
| name | String | The event name this handler listens for: the class name of a FunnelEvent, or the trigger id of an event an app fires with eventManager.eventBuilder(true). |
| reasoningEffort | String | How hard the model should think when this handler runs, overriding the per-phase defaults. Effort defaults are tuned for what each phase usually does, and Act - the tool-calling loop - is cheap on purpose, because it is normally choosing an obvious next step. Some handlers are not like that: working out which dimension to break an anomaly down by, given what the last breakdown returned, is the work rather than a step towards it. Such a handler says so here. |
| scope | String | How this handler's events are scoped. Null matches all events regardless of profile; SCOPE_CUST_PROFILE matches only events for the lead's own profile. |
Methods
getModelTier() · withModelTier(String newTier) · getReasoningEffort() · withReasoningEffort(String newEffort) · getBudgetBoost() · withBudgetBoost(Integer newBoost) · isDisabled() · withDisabled(boolean newDisabled) · getName() · getInstructions() · getScope() · getBufferSecs() · getBufferSize() · withInstructions(String newInstructions) · withScope(String newScope) · withBufferSecs(Integer newSecs) · withBufferSize(Integer newSize)
getModelTier()
Returns: String
Which class of model this handler's run should use, named for the job rather than for a model: fast, balanced or deep. A definition already carries a tier for its own interactive use, and the root agent's is deliberately fast because routing is nearly always obvious. That is the wrong setting for a handler whose job is working something out - and it matters more than it looks, because a specialist inherits the model of the run that delegated to it, so this raises the whole tree rather than just the agent that received the event.
withModelTier(String newTier)
Returns: AgentDefEventHandler
Returns a copy of this event handler with the given model tier.
| Parameter | Description |
|---|---|
newTier | a tier name such as deep, or null to use the agent definition's own |
getReasoningEffort()
Returns: String
How hard the model should think when this handler runs, overriding the per-phase defaults. Effort defaults are tuned for what each phase usually does, and Act - the tool-calling loop - is cheap on purpose, because it is normally choosing an obvious next step. Some handlers are not like that: working out which dimension to break an anomaly down by, given what the last breakdown returned, is the work rather than a step towards it. Such a handler says so here.
withReasoningEffort(String newEffort)
Returns: AgentDefEventHandler
Returns a copy of this event handler with the given reasoning effort.
| Parameter | Description |
|---|---|
newEffort | an effort such as low, medium or high, or null for the phase defaults |
getBudgetBoost()
Returns: Integer
How much more work this handler's run may do than an interactive turn, as a multiple of the standard ceilings. An event handler runs unattended, minutes after the thing it is about, and is often asked a question worth more querying than a chat question - "why did this metric move" is answered by breaking a period down, looking at what that returns and breaking it down again. The standard budget is sized for someone watching a spinner, and a specialist reaching the end of it mid-investigation reports a failure rather than an answer.
withBudgetBoost(Integer newBoost)
Returns: AgentDefEventHandler
Returns a copy of this event handler with the given budget boost.
| Parameter | Description |
|---|---|
newBoost | the multiple to apply to the run's ceilings, or null for the standard budget |
isDisabled()
Returns: boolean
Whether this handler is switched off, ie present in the definition but not listening. How an account takes away a handler its app supplies: the app keeps declaring it, the account's copy says disabled, and the definition otherwise carries on following the app.
withDisabled(boolean newDisabled)
Returns: AgentDefEventHandler
Returns a copy of this event handler switched on or off.
| Parameter | Description |
|---|---|
newDisabled | true to stop the handler receiving events |
getName()
Returns: String
The event name this handler listens for: the class name of a FunnelEvent, or the trigger id of an event an app fires with eventManager.eventBuilder(true).
getInstructions()
Returns: String
Instructions run when a matching event fires.
getScope()
Returns: String
How this handler's events are scoped. Null matches all events regardless of profile; SCOPE_CUST_PROFILE matches only events for the lead's own profile.
getBufferSecs()
Returns: Integer
If set, matching events are buffered for up to this many seconds before the handler fires with the events recorded during that window.
getBufferSize()
Returns: Integer
If set, matching events are buffered until this many have been recorded, then the handler fires with them.
withInstructions(String newInstructions)
Returns: AgentDefEventHandler
Returns a copy of this event handler with the given instructions.
| Parameter | Description |
|---|---|
newInstructions | the instructions to run when a matching event fires |
withScope(String newScope)
Returns: AgentDefEventHandler
Returns a copy of this event handler with the given scope.
| Parameter | Description |
|---|---|
newScope | null to match all events, or a scope constant such as SCOPE_CUST_PROFILE to match only events for the lead's own profile |
withBufferSecs(Integer newSecs)
Returns: AgentDefEventHandler
Returns a copy of this event handler with the given buffering window.
| Parameter | Description |
|---|---|
newSecs | how many seconds to buffer matching events for before firing, or null to not time-buffer |
withBufferSize(Integer newSize)
Returns: AgentDefEventHandler
Returns a copy of this event handler with the given buffering count.
| Parameter | Description |
|---|---|
newSize | how many matching events to buffer before firing, or null to not count-buffer |
© 2025 Kademi Ltd