Tools

A chat model can only produce text. A tool is a function you give the agent so it can do more: fetch the weather, query your database, file a ticket. The result folds back into the conversation.

The loop:

1. The model proposes a tool: a name plus arguments.
2. Your code runs it. It calls an API, reads a database, or does whatever the tool does.
3. The result returns to the conversation, and the agent continues, usually turning it into a final answer.

user: "What's the weather in Tokyo?"
  └─ model proposes:  get_weather({ city: "Tokyo" })
       └─ your code runs it → { tempC: 22, sky: "clear" }
            └─ result returns to the agent
                 └─ agent: "It's 22°C and clear in Tokyo right now."

The trust boundary stays in your code. The model only proposes which tool to call and with what arguments. Execution, provider keys, and the tool implementations live on the server and never reach the browser.

Integrate your own tool

A tool is a name, a description, and a JSON Schema for its arguments. The model uses the description and schema to decide when and how to call it, so write them like prompts.

const tools = [
  {
    type: "function",
    name: "get_weather",
    description: "Get the current weather for a city.",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string", description: "City name, e.g. 'Tokyo'" },
      },
      required: ["city"],
      additionalProperties: false,
    },
  },
];

That declaration is what the model sees. The implementation, the code that actually fetches the weather, stays private and runs only when the agent calls the tool.

This declaration is the same on OpenUI Cloud and self-hosted. Your code always runs your own tools. Only the built-in tools below run inside Cloud.

Built-in tools (OpenUI Cloud)

OpenUI Cloud ships tools you enable without writing any implementation. Cloud holds the keys and runs them. For example, image_search lets the agent pull in relevant images.

Tools and artifacts

A tool call is also one way an artifact gets produced. When the agent calls something like generate_report, the interface matches a renderer to that tool by name and draws the result in its own panel. The tool call is the mechanism; the artifact is the output. Many tool calls, like get_weather, produce no artifact at all. See Custom artifacts to render a tool's result as an artifact.