Core concepts

Agents

In Inkeep, an Agent is the top-level entity you can interface with via conversational experiences (chat) or trigger programmatically (via API).

Under the hood, an Agent is made up of one or more Sub Agents that work together to respond to a user or complete a task.

Tools

When you send a message to an Agent, it is first received by a Default Sub Agent that decides what to do next.

In a simple Agent, there may be only one Sub Agent with a few tools available to it.

Tools are actions that a Sub Agent can take, like looking up information or performing a task on apps and APIs.

In Inkeep, tools can be added to Sub Agents as:

• MCP Servers: A common way to connect to external services and APIs. Many SaaS providers provide out-of-the-box MCP Servers, but you can also create your own and register them with their associated Credentials on Inkeep for Agents to use.
• Function Tools: Custom JavaScript functions that Agents can execute directly without the need for standing up an MCP server.

Typically, you want a Sub Agent to handle narrow, well-defined tasks. As a general rule of thumb, keep Sub Agents to be using 5-7 related tools at a time.

Sub Agent relationships

When your scenario gets complex, it can be useful to break up your logic into multiple Sub Agents that are specialized in specific parts of your task or workflow. This is often referred to as a "Multi-agent" system.

A Sub Agent can be configured to:

• Transfer control of the chat to another Sub Agent. When a transfer happens, the receiving Sub Agent becomes the primary driver of the thread and can respond to the user directly.
• Delegate a subtask for another ('child') Sub Agent to do and wait for its response before proceeding with the next step. A child Sub Agent cannot respond directly to a user.

Sub Agent 'turn'

When it's a Sub Agent's turn, it can choose to:

1. Send an update message to the user
2. Call a tool to collect information or take an action
3. Transfer or delegate to another Sub Agent

An Agent's execution stays in this loop until one of the Sub Agents chooses to respond to the user with a final result.

Chatting with an Agent

You can talk to an Inkeep Agent in a few ways, including:

• UI Chat Components: Drop-in React components for chat UIs with built-in streaming and rich UI customization. See agents-ui.
• As an MCP server: Use your Inkeep Agent as if was an MCP Server. Allows you to connect it to any MCP client, like Claude, ChatGPT, Claude and other Agents. See MCP server.
• Via API (Vercel format): An API that streams responses over server-side events (SSE). Use from any language/runtime, including the Vercel's useChat and AI Element primitives for custom UIs. See API (Vercel format).
• Via API (A2A format): An API that follows the Agent-to-Agent ('A2A') JSON-RPC protocol. Great for when combining Inkeep with different Agent frameworks that support the A2A format. See A2A protocol.

Authentication & API Keys

You can authenticate with your Agent using:

• API Keys: Securely hashed keys that are scoped to specific Agents
• Development Mode: No API key required, perfect for local development and testing
• Bypass Secrets: For internal services and infrastructure that need direct access

API keys are the recommended approach for production use, providing secure, scoped access to your Agents.

Agent replies with Structured Data

Sometimes, you want your Agent to reply not in plain text but with specific types of well-defined information, often called 'Structured Outputs' (JSON).

With Inkeep, there are a few ways to do this:

• Data Components: Structured Outputs that Sub Agents can output in their messages so they can render rich, interactive UIs (lists, buttons, forms, etc.) or convey structured information.
• Artifacts: A Sub Agent can save information from a tool call result as an artifact in order to make it available to others. For example, a Sub Agent that did a web search can save the contents of a webpage it looked at as an artifact. Once saved, a Sub Agent can cite or reference artifacts in its response, and other Sub Agents or users can fetch the full artifacts if they'd like.
• Status Updates: Real-time progress updates that can be plain text or Structured Outputs that can be used to keep users informed about what the Sub Agent is doing during longer operations.

Passing context to Sub Agents

Beyond using Tools to fetch information, Sub Agents also receive information via:

• Headers: In the API request to an Agent, the calling application can include headers for a Sub Agent. Learn more here.
• Context Fetchers: Can be configured for an Agent so that at the beginning of a conversation, an API call is automatically made to an external service to get information that is then made available to any Sub Agent. For example, your Headers may include a user-id, which can be used to auto-fetch information from a CRM about the user for any Sub Agent to use.

Headers and fetched context can then be referenced explicitly as {{variables}} in Sub Agent prompts. Learn more here.

Ways to build

Quick reference to the key docs for building with the Visual Builder or the TypeScript SDK.

The Visual Builder and TypeScript SDK work seamlessly together—define your Sub Agents in code, push them to the Visual Builder, and iterate visually.

Projects

You can organize your related MCP Servers, Credentials, Agents, and more into Projects. A Project is generally used to represent a set of related scenarios.

For example, you may create one Project for your support team that has all the MCP servers and Agents related to customer support.

CLI: Push and pull

The Inkeep CLI bridges your TypeScript SDK project and the Visual Builder.

Run the following from your project (the folder that contains your inkeep.config.ts) which has an index.ts file that exports a project.

• Push (code → Builder): Sync locally defined agents, Sub Agents, tools, and settings from your SDK project into the Visual Builder.

inkeep push

• Pull (Builder → code): Fetch your project from the Visual Builder back into your SDK project. By default, the CLI will LLM-assist in updating your local TypeScript files to reflect Builder changes.

inkeep pull

See the CLI Reference for full command details.

Deployment

Once you've built your Agents, you can deploy them using:

Architecture

The Inkeep Agent framework is composed of several key services and libraries that work together:

• agents-manage-api: An API that handles configuration of Agents, Sub Agents, MCP Servers, Credentials, and Projects with a REST API.
• agents-manage-ui: Visual Builder web interface for creating and managing Agents. Writes to the agents-manage-api.
• agents-sdk: TypeScript SDK (@inkeep/agents-sdk) for declaratively defining Agents and custom tools in code. Writes to agents-manage-api.
• agents-cli: Includes various handy utilities, including inkeep push and inkeep pull which sync your TypeScript SDK code with the Visual Builder.
• agents-run-api: The Runtime API that exposes Agents as APIs and executes Agent conversations. Keeps conversation state and emits OTEL traces.
• agents-ui: A UI component library of chat interfaces for embedding rich, dynamic Agent conversational experiences in web apps.