# Core concepts (/concepts)

Learn about the key building blocks of Inkeep - Agents, Sub Agents, tools, data components, and more.



## 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**: Connect to external services and APIs via the Model Context Protocol. You can:

  * **Connect to Native MCP servers** provided directly by SaaS vendors (no building required)
  * **Access Composio's platform** for 10,000+ out-of-box MCP servers for popular services (no building required)
  * **Use Gram** to convert OpenAPI specs into MCP servers
  * **Build and deploy Custom servers** for your own APIs and business logic

  Register any of these with their associated **Credentials** for your 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.

<Note>
  Sub Agents in Inkeep are designed to respond to the user as a single, cohesive unit by default.
</Note>

## 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`](/talk-to-your-agents/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](/talk-to-your-agents/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)](/talk-to-your-agents/api).
  * **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](/talk-to-your-agents/a2a).
  * **Via Webhook Triggers**: Create webhook endpoints that allow external services (GitHub, Slack, Stripe, etc.) to invoke your Agents. See [Triggers](/talk-to-your-agents/triggers).

  <Cards>
    <Card title="React UI" icon="LuMessageSquare" href="/talk-to-your-agents/react/chat-button">
      Drop-in chat components for React apps with streaming and rich UI.
    </Card>

    <Card title="API (Vercel format)" icon="LuNetwork" href="/talk-to-your-agents/chat-api">
      POST /api/chat, SSE (text/event-stream), x-vercel-ai-data-stream: v2.
    </Card>

    <Card title="A2A protocol" icon="LuNetwork" href="/talk-to-your-agents/a2a">
      JSON-RPC messages at /agents/a2a with blocking and streaming modes.
    </Card>

    <Card title="MCP server" icon="LuServer" href="/talk-to-your-agents/mcp-server">
      HTTP JSON-RPC endpoint at /v1/mcp with session header management.
    </Card>

    <Card title="Webhook Triggers" icon="LuWebhook" href="/talk-to-your-agents/triggers">
      Webhook endpoints for event-driven Agent invocation.
    </Card>
  </Cards>
</>

## Triggers

**Triggers** are webhook endpoints that allow external services to invoke your Agents. When a webhook is received, the payload is validated, transformed into a message, and used to start a new conversation.

Triggers are useful for:

* **Event-driven workflows** - Respond to events from external services like GitHub, Slack, or Stripe
* **Third-party integrations** - Connect any service that can send HTTP webhooks to your Agents
* **Automated pipelines** - Kick off Agent tasks from CI/CD, cron jobs, or other automation systems

Each trigger can be configured with:

* **Input validation** - JSON Schema to validate incoming payloads
* **Message templates** - Transform webhook payloads into natural language messages using `{{placeholder}}` syntax
* **Authentication** - API keys, bearer tokens, or basic auth to secure the endpoint
* **Signature verification** - HMAC-SHA256 verification for services like GitHub that sign webhooks

When a webhook is received, the trigger creates a new conversation and invokes the Agent asynchronously, returning immediately with an invocation ID for tracking.

<Cards>
  <Card title="Webhook Triggers" icon="LuWebhook" href="/talk-to-your-agents/triggers">
    Learn how triggers work and when to use them.
  </Card>

  <Card title="TypeScript SDK" icon="LuCode" href="/typescript-sdk/triggers">
    Define triggers in code with the SDK.
  </Card>
</Cards>

## 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](/typescript-sdk/headers).
* **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](/typescript-sdk/headers).

## Ways to build

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

<Tabs>
  <Tab title="Visual Builder">
    <Cards>
      <Card title="MCP Servers" icon="LuServer" href="/visual-builder/tools/mcp-servers">
        Configure and manage MCP servers for your Sub Agents.
      </Card>

      <Card title="Agents" icon="LuSpline" href="/visual-builder/sub-agents">
        Create and manage Agents visually.
      </Card>

      <Card title="Data Components" icon="LuBlocks" href="/visual-builder/structured-outputs/data-components">
        Build rich UI elements Sub Agents can render in conversations.
      </Card>

      <Card title="Artifact Components" icon="TbInputSpark" href="/visual-builder/structured-outputs/artifact-components">
        Define structured outputs generated by tools or Sub Agents.
      </Card>

      <Card title="Status Components" icon="LuClock" href="/visual-builder/structured-outputs/status-components">
        Show progress updates during longer operations.
      </Card>

      <Card title="Credentials" icon="LuKey" href="/visual-builder/tools/credentials">
        Manage secrets and auth for MCP servers.
      </Card>

      <Card title="Project Management" icon="LuFolder" href="/visual-builder/project-management">
        Organize agents, MCP Servers, and other entities in Projects.
      </Card>
    </Cards>
  </Tab>

  <Tab title="TypeScript SDK">
    <Cards>
      <Card title="Sub Agent Settings" icon="LuUser" href="/typescript-sdk/agent-settings">
        Configure Sub Agents with prompts, tools, and data components.
      </Card>

      <Card title="MCP Servers" icon="LuHammer" href="/typescript-sdk/tools/mcp-servers">
        Add tools as MCP servers.
      </Card>

      <Card title="Function Tools" icon="LuCode" href="/typescript-sdk/tools/function-tools">
        Create custom JavaScript functions that run in secure sandboxes.
      </Card>

      <Card title="Sub Agent Relationships" icon="LuUsers" href="/typescript-sdk/agent-relationships">
        Define how Sub Agents transfer and delegate tasks.
      </Card>

      <Card title="Data Components" icon="LuBlocks" href="/typescript-sdk/structured-outputs/data-components">
        Build custom UI elements Sub Agents can render.
      </Card>

      <Card title="Artifact Components" icon="TbInputSpark" href="/typescript-sdk/structured-outputs/artifact-components">
        Create structured outputs from tools or Sub Agents.
      </Card>

      <Card title="Status Updates" icon="LuClock" href="/typescript-sdk/structured-outputs/status-updates">
        Provide real-time progress updates.
      </Card>

      <Card title="Context Fetchers" icon="LuCirclePlus" href="/typescript-sdk/context-fetchers">
        Dynamically fetch and cache external context.
      </Card>

      <Card title="Credentials" icon="LuKey" href="/typescript-sdk/credentials/overview">
        Store and retrieve credentials for MCP tools.
      </Card>

      <Card title="Triggers" icon="LuWebhook" href="/typescript-sdk/triggers">
        Create webhook endpoints for external services.
      </Card>
    </Cards>
  </Tab>
</Tabs>

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.

```bash
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.

```bash
inkeep pull
```

<Note>
  Push and pull operate at the project level (not individual agents). Define agents in your project and push/pull the whole project.
</Note>

See the [CLI Reference](/typescript-sdk/cli-reference) for full command details.

## Deployment

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

<Cards>
  <Card title="Deploy with Docker" icon="LuContainer" href="/self-hosting/docker">
    Self-host your Agents using Docker for full control and flexibility.
  </Card>

  <Card title="Deploy to Vercel" icon="LuRocket" href="/self-hosting/vercel">
    Deploy your Agents to Vercel for easy serverless hosting.
  </Card>
</Cards>

## Architecture

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

* **agents-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-api`.
* **agents-sdk**: TypeScript SDK (`@inkeep/agents-sdk`) for declaratively defining Agents and custom tools in code. Writes to `agents-api`.
* **agents-cli**: Includes various handy utilities, including `inkeep push` and `inkeep pull` which sync your TypeScript SDK code with the Visual Builder.
* **agents-ui**: A UI component library of chat interfaces for embedding rich, dynamic conversational AI experiences in web apps.