Built-in tools

Capabilities Agentheya ships with — searchable from the agent loop and callable from your own custom code tools via the injected ctx.

Built-in tools

Agentheya ships a set of built-in tools your agent can call out of the box. Each is enabled per-agent from the Tools tab of the agent editor.

Once enabled, two things become true:

1. The agent can call the tool directly. The LLM decides when to use it based on the conversation.
2. Your custom code tools can call it programmatically. Every custom code tool’s handler receives a ctx object with ctx.tools.<name>(input) — see Custom tool ctx.

// Inside a custom JavaScript code tool
export async function handle(input, ctx) {
  const search = await ctx.tools.web_search({ query: input.topic });
  const summary = await ctx.tools.calculate({ expression: '15% of 4200' });
  return { search, summary };
}

All built-in tools

Web

• web_search — search the web and return result snippets
• web_fetch — fetch a URL as clean markdown

Files

• present_public_file — offer a public file as a download card
• show_file_excerpt — show a slice of a public text file inline
• show_image — render a public image in the chat bubble
• surface_file — save generated content and return a download URL

Utility

• calculate — deterministic arithmetic, percentages, and unit conversions
• get_current_time — current ISO 8601 time, optionally in an IANA timezone
• render_ui — emit a Generative UI spec

Interactive

• confirm_action — ask the user to approve a destructive action
• commit_action — gatekeeper that verifies prior approval
• collect_form — render a structured form and collect fields

Outbound

• send_email — send transactional email (recipient-allowlisted; supports CC/BCC, custom headers, attachments, scheduled delivery)
• check_email_status — look up delivery status + event timeline + advice for a previously-sent email
• request_human_handoff — escalate to a configured human channel

The anti-hallucination contract

Interactive tools (confirm_action, collect_form, render_ui with interactive: true, request_human_handoff) return an interaction_id and never describe what the user did. The user’s actual response arrives on the next turn as a synthetic tool-result. This means a misbehaving LLM cannot fabricate “the user said yes” — destructive flows pair confirm_action with commit_action, and the server is the only writer of approval state.

Calling built-ins from your code

Every custom code tool runs in a sandbox and gets a ctx parameter:

export async function handle(input, ctx) {
  // ctx.agentId, ctx.powerUserId, ctx.toolCallId, ctx.agentName
  const result = await ctx.tools.<tool_name>(<input>);
  await ctx.audit('event_name', { ... });
  return result;
}

See Custom tool ctx for the full ctx surface.