---
title: AI agents overview
description: Build AI agents that use your app's functions, and share tools with MCP clients.
pagination: false
sidebar:
  icon: bot
---

Use agents when your application needs a model to interpret a request and choose how to complete it. Tools let it do useful work in
your app: look up an order, search a catalog, or prepare a response using current data.

> **Start here**
>
> Start with [Build an offline agent](/guides/ai/build-an-offline-agent) for installation, a working
> assistant, and a test without a model API key. The [Agents](/docs/api/agents),
> [Tools](/docs/api/tools), and [LangChain integration](/docs/api/integrations/langchain) references
> describe the exact APIs.

**RELKIT agents run through native LangChain and LangGraph APIs.** RELKIT connects those workflows to
your application's functions, validation, permissions, durable threads, and execution limits. Use
`defineAgent` for model-driven work, or `defineGraph` and `defineGraphNode` for explicit workflows.
Adding subagents, skills, memory files, or a backend to `defineAgent` selects native DeepAgents
behavior through the same declaration.

Use an agent when the next step depends on a user's question. Use an ordinary function when you already know the steps, such as calculating a total or saving an order.

## Pre-setup

Use local Docker Redis for agent checkpoints and live updates. Model execution is a separate
choice: begin with the deterministic model in the [offline agent guide](/guides/ai/build-an-offline-agent).
Docker does not supply a hosted model or an API key.

1. **Install agent execution and Redis support**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @langchain/core@1.2.9 @langchain/langgraph@1.4.14 @relkit/langchain@0.7.13 @relkit/local@0.7.12 langchain@1.5.10 langsmith@0.10.8
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.12 @relkit/redis@0.8.1
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    The agent cohort also installs the filesystem provider used by the offline tutorial. This
    configuration selects Docker Redis for the running application instead.

2. **Configure checkpoint and realtime profiles**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** Agent checkpoints and live updates use separate Docker Redis capabilities. */
    import { defineApp, defineEnv } from "@relkit/app/config";
    import { docker } from "@relkit/docker";
    import { redisAgentState, redisRealtime } from "@relkit/redis";

    export default defineApp({
      env: defineEnv({}),
      realtime: docker(redisRealtime()),
      "agent-state": docker(redisAgentState()),
      defaults: { realtime: "default", "agent-state": "default" },
    });
    ```

    Use `stateProfile: "default"` in the agent, or omit it to select this default. Redis credentials
    come from Docker. The deterministic model needs no environment key. When selecting a hosted model,
    declare its required key as `env.secret()` in your existing `defineEnv`, supply it to the backend
    process, and follow that model's [native configuration](/docs/modules/ai/agents).
    The declaration validates the key; it does not configure the model automatically.

    Tools exposed only through MCP do not need checkpoint storage. Workspace files use a separate
    [bucket profile](/docs/modules/storage#pre-setup) when selected.

3. **Check and start after registering the agent**

    Check Docker before continuing. After adding the resource and its service registration, run from the app root:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run typecheck
    bun run dev
    ```

    `check` validates the graph; it starts no containers. `dev` starts only Docker recipes used by
    that graph, waits for readiness, and binds their generated connection values. An unused profile
    alone does not start a container. Keep the server running and use `bun run relkit local status`
    in another terminal to inspect the services. [Local Docker](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

## The AI APIs

Usually, adding tools to a model means writing argument schemas, dispatching tool calls, handling results, and controlling how long the model can keep working. RELKIT lets you reuse validated functions as tools, choose which tools an agent can use, and set limits on each run.

| API                 | What you use it for                                                       |
| ------------------- | ------------------------------------------------------------------------- |
| `defineAgent`       | Set native model, tool, middleware, DeepAgents, and client behavior.      |
| `defineGraph`       | Register a typed native LangGraph workflow and its public result.         |
| `defineGraphNode`   | Validate graph-node state updates, routes, and human continuation.        |
| `defineTool`        | Give an existing function a tool name, description, and execution policy. |
| `function.asTool()` | Turn a function into a tool directly.                                     |
| `mcp`               | Choose whether a tool is available to external MCP clients.               |

The same tool can serve a RELKIT agent and an external AI client through **Model Context Protocol (MCP)**. You do not need a RELKIT agent just to expose tools over MCP.

## Native framework boundary

Pass compatible LangChain models, tools, and middleware directly—there is no public adapter wrapper.
RELKIT function-backed tools remain native-compatible while preserving function execution, validation,
authorization, and tool policies. LangGraph owns scheduling and control flow; RELKIT validates declared
state and public output around it.

## Observe durable execution

Client-exposed agents stream one canonical event history over HTTP iteration, AG-UI SSE, or WebSocket.
AG-UI is independently opt-in. Only when selecting that protocol, install its SDK and set
`server.agUi` to `true` in your existing application configuration:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @ag-ui/core@0.0.59
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

This optional protocol is validated before readiness; ordinary
typed agent RPC and streaming do not select it.
The typed client exposes messages, tools, progress, selected middleware state, waiting requests, nested
execution, and final output separately. Every run, observation, control, and continuation supplies an
application-owned `threadId`; mounting a hook never invents one or starts work.

See [Agent streaming](/docs/modules/ai/streaming) and [Threads and recovery](/docs/modules/ai/threads-recovery).

For the complete native boundary, continue with [Native runtime and DeepAgents](/docs/modules/ai/native-runtime)
and [LangGraph, persistence, and resume](/docs/modules/ai/graphs-persistence).

## Choose where to start

Follow the [greeting-assistant tutorial](/guides/ai/build-an-offline-agent) to add an agent to an existing app and test it without a model API key.

Already have application functions? [Turn one into a tool](/docs/modules/ai/function-tools), then [give it to an agent](/docs/modules/ai/agents) or [connect an MCP client](/docs/modules/ai/mcp).

With the separately installed and enabled [Inspector](/docs/modules/operations/inspector), open **Agents**
to review an agent's tools and limits, or **Tools** to review the functions each tool calls.

> **Review MCP access**
>
> MCP is disabled by default. When you explicitly enable it, tools are exposed unless you set `mcp:
> false`. Before making your app reachable by other users, review tool visibility and protect
> `/mcp`. An agent's tools list does not restrict the MCP endpoint.