Core concepts of the Inkeep Agent Platform

Agents, Tools

Inkeep is designed with Agents as the primary building blocks of AI systems.

In simple terms:

• An Agent is an LLM (AI model) that receives a message and can use tools or collaborate with other agents to accomplish a goal.
• Tools are actions that an Agent can take, like looking up information or taking an action on third-party systems and APIs.

In Inkeep, tools are added to agents as MCP Servers. Many services provide out-of-the-box MCP Servers, but you can also create your own. With Inkeep, you can register MCP servers and their associated Credentials, then use them within Agents as tools.

Typically, you want an Agent to handle narrow, well-defined tasks. Keeping the scope narrow allows you to optimize your prompt (instructions) and the tools an agent has to be specific to a scenario or task. As a general rule of thumb, only add up to 5-7 tools to an agent.

Graphs

When what you're trying to accomplish gets complex, it can be useful to break up your logic into a "team" of agents that work together.

At Inkeep, we call that a Graph. A Graph is made up of one or more Agents that collaborate to complete a task and respond to the user.

Agent to Agent relationships

With Inkeep, every Graph has a Default Agent that receives the initial message and decides how to proceed.

In a Graph, an Agent can choose to:

• Transfer control of the chat to another Agent so a different Agent can respond to the user.
• Delegate a subtask for another Agent to do and wait for its response before proceeding with the next step.

Agent 'turn'

In summary, when an Agent receives a message, it can choose to:

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

The Graph keeps executing steps 2 and 3 until an Agent in the graph chooses to respond to the user with a final result or a next message.

Chatting with an Agent

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

• UI Chat Components: Drop-in React components for chat UIs with built-in streaming and rich UI customization. See React Chat Button.
• 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 a server-side events (SSE) data-stream format. Use from any language/runtime, including the Vercel AI SDK. 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 graph using:

• API Keys: Securely hashed keys that are scoped to specific graphs
• 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 agent graphs.

Agent replies with Structured Data

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

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

• Data Components: Structured Outputs that agents can output in their messages so they can render rich, interactive UIs (lists, buttons, forms, etc.) or convey structured information.
• Artifacts: An Agent can save information from a tool call result as an artifact in order to make it available to others. For example, an Agent that did a web search can save the contents of a webpage it looked at as an artifact. Once saved, an Agent can cite or reference artifacts in its response, and other 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 agent is doing during longer operations.

Passing context to Agents

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

• Headers: In the API request to an Agent, the calling application can include headers (a.k.a Request Context) for an agent.
• Context Fetchers: Can be configured for a Graph 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 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 Agent to use.

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

Ways to build

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

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

Projects

You can organize your related MCP Servers, Credentials, Graphs, 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 Graphs 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) and has an index.ts file that exports a project.

• Push (code → Builder): Sync locally defined graphs, 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 updating your local TypeScript files to reflect Builder changes.

inkeep pull

See the CLI Reference for full command details.