<Tool />

<Tool /> grants an application function created by defineTool() to its nearest containing <Agent />. The function runs in the AML application process, not inside an active <Sandbox />.

import { Agent, AmlRuntime, defineTool, Tool } from "@aml-jsx/sdk"
import { DeterministicAgentProvider } from "@aml-jsx/sdk/testing"
import { z } from "zod"

const lookupOrder = defineTool({
  name: "lookup_order",
  description: "Read one order by its public identifier",
  input: z.object({ id: z.string() }),
  execute: async ({ id }) => ({ id, status: "paid" }),
})

const runtime = new AmlRuntime({ agentProvider: new DeterministicAgentProvider() })
await runtime.evaluate(
  <Agent>
    <Tool use={lookupOrder} />
    Summarize order A-42.
  </Agent>
)

This example uses Zod as a Standard Schema implementation; install it separately with npm install zod.

Call a Tool from application code

Call the function returned by defineTool() inside an active AML function component when application code, rather than a model, chooses to run the Tool:

import { AmlRuntime, defineTool } from "@aml-jsx/sdk"
import { z } from "zod"

const loadOrder = defineTool({
  name: "load_order",
  description: "Load one order for application workflow code",
  input: z.object({ id: z.string() }),
  output: z.object({ id: z.string(), status: z.literal("paid") }),
  execute: async ({ id }) => ({ id, status: "paid" as const }),
})

async function Workflow() {
  const order = await loadOrder({ id: "order-17" })
  return `${order.id}:${order.status}`
}

await new AmlRuntime().evaluate(<Workflow />)

Calling loadOrder() requires no surrounding <Agent /> or <Tool />. It validates and snapshots through the same registered Tool execution path, inherits evaluation cancellation and tracing, and runs in the AML host process. Calling a Tool never grants it to a model. The callable API is available only while the function component is active, and AML joins started calls before enclosing resources clean up.

The same Tool can be granted separately when a model should decide whether to call it:

<Agent>
  <Tool use={loadOrder} />
  Check order-17.
</Agent>

<Tool use> accepts only the exact callable returned by defineTool(). An inline definition is valid—<Tool use={defineTool({...})} />—but a structurally similar plain object is not.

Props

Prop	Type	Required	Meaning
`use`	`AmlTool`	yes	Exact Tool identity returned by `defineTool()`.

<Tool /> accepts no children or name prop. Tool names must be unique inside one <Agent /> and may be restricted by the runtime allowedTools allowlist.

Execution boundary

AML validates model input before calling execute.
Tool output must be JSON-compatible and is snapshotted before it crosses the provider boundary.
An optional output schema validates the function’s returned value.
The callback receives cancellation and trace context, but it does not inherit Sandbox process execution merely because its Agent is sandboxed.
Sibling and parent <Agent /> components do not receive the grant unless they declare it separately.

See the runnable programmatic-tool example, Build a JavaScript Tool, Tool or MCP?, and production security.