### TypeScript Agents SDK
A code-first framework so engineering teams can build with the tools they expect.
```typescript
import { agent, subAgent } from "@inkeep/agents-sdk";
const helloAgent = subAgent({
id: "hello-agent",
name: "Hello Agent",
description: "Says hello",
prompt: 'Only reply with the word "hello", but you may do it in different variations like h3110, h3110w0rld, h3110w0rld! etc...',
});
export const basicAgent = agent({
id: "basic-agent",
name: "Basic Agent",
description: "A basic agent that just says hello",
defaultSubAgent: helloAgent,
subAgents: () => [helloAgent],
});
```
The **Visual Builder and TypeScript SDK are fully interoperable**: your technical and non-technical teams can edit and manage Agents in either format and switch or collaborate with others at any time.
## Use cases
Inkeep Agents can operate as **Agentic Chat Assistants**, for example:
* a customer experience agent for help centers, technical docs, or in-app experiences
* an internal copilot to assist your support, sales, marketing, ops, and other teams
Agents can also be used for **Agentic Workflow Automation** like:
* Creating and updating knowledge bases, documentation, and blogs
* Updating CRMs, triaging helpdesk tickets, and tackling repetitive tasks
## Platform Overview
**Inkeep Open Source** includes:
* A Visual Builder & TypeScript SDK with 2-way sync
* Multi-agent architecture to support teams of agents
* MCP Tools with credentials management
* A UI component library for dynamic chat experiences
* Triggering Agents via MCP, A2A, & Vercel SDK APIs
* Observability via a Traces UI & OpenTelemetry
* Easy deployment to Vercel and using Docker
Interested in a managed platform? Sign up for the [Inkeep Cloud waitlist](https://inkeep.com/cloud-waitlist) or learn about [Inkeep Enterprise](https://inkeep.com/enterprise).
## Our Approach
Inkeep is designed to be extensible and open: you can use the LLM provider of your choice, use Agents via open protocols, and with a [fair-code](/community/license) license and great devex, easily deploy and self-host Agents in your own infra.
[Follow us](https://docs.inkeep.com/community/inkeep-community) to stay up to date, get help, and share feedback.
## Next Steps
#### What's Included in the Trace Export
When you click `Copy Trace`, the system exports a JSON object containing:
```json
{
"metadata": {
"conversationId": "unique-conversation-id",
"traceId": "distributed-trace-id",
"agentId": "agent-identifier",
"agentName": "Agent Name",
"exportedAt": "2025-10-14T12:00:00.000Z"
},
"timing": {
"startTime": "2025-10-14T11:59:00.000Z",
"endTime": "2025-10-14T12:00:00.000Z",
"durationMs": 60000
},
"timeline": [
// Array of all activities with complete details:
// - Agent messages and responses
// - Tool calls and results
// - Agent transfers
// - Artifact information
// - Execution context
]
}
```
#### How to Use Copy Trace
1. Navigate to the **Traces** section in the management UI
2. Open the conversation you want to debug
3. Click the **Copy Trace** button at the top of the timeline
4. The complete trace JSON is copied to your clipboard
5. Paste it into your preferred tool for analysis
This exported trace contains all the activities shown in the timeline, making it easy to share complete execution context with team members or support.
## Step 2: Check SigNoz
SigNoz provides distributed tracing and observability for your agent system, offering deeper insights when the built-in timeline isn't sufficient.
### Accessing SigNoz from the Timeline
You can easily access SigNoz directly from the timeline view. In the **Traces** section, click on any activity in the conversation timeline to view its details. Within the activity details, you'll find a **"View in SigNoz"** button that takes you directly to the corresponding span in SigNoz for deeper analysis.
### What SigNoz Shows
* **Distributed traces**: End-to-end request flows across services
* **Performance metrics**: Response times, throughput, and error rates
### Key Metrics to Monitor
* **Agent response times**: How long each agent takes to process requests
* **Tool execution times**: Performance of MCP servers and external APIs
* **Error rates**: Frequency and types of failures
## Agent Stopped Unexpectedly
### StopWhen Limits Reached
If your agent stops mid-conversation, it may have hit a configured stopWhen limit:
* **Transfer limit reached**: Check `transferCountIs` on your Agent or Project - agent stops after this many transfers between Sub Agents
* **Step limit reached**: Check `stepCountIs` on your Sub Agent or Project - execution stops after this many tool calls + LLM responses
**How to diagnose:**
* Check the timeline for the last activity before stopping
* Look for messages indicating limits were reached
* Review your stopWhen configuration in Agent/Project settings
**How to fix:**
* Increase the limits if legitimate use case requires more steps/transfers
* Optimize your agent flow to use fewer transfers
* Investigate if agent is stuck in a loop (limits working as intended)
See [Configuring StopWhen](/typescript-sdk/agent-settings#configuring-stopwhen) for more details.
## Common Configuration Issues
### General Configuration Issues
* **Missing environment variables**: Ensure all required env vars are set
* **Incorrect API endpoints**: Verify you're using the right URLs
* **Network connectivity**: Check firewall and proxy settings
* **Version mismatches**: Ensure all packages are compatible
### MCP Server Connection Issues
* **MCP not able to connect**:
* Check that the MCP server is running and accessible
* **401 Unauthorized errors**:
* Verify that credentials are properly configured and valid
* **Connection timeouts**:
* Ensure network connectivity and firewall settings allow connections
### AI Provider Configuration Problems
* **AI Provider key not defined or invalid**:
* Ensure you have one of these environment variables set: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENERATIVE_AI_API_KEY`
* Verify the API key is valid and has sufficient credits
* Check that the key hasn't expired or been revoked
* **GPT-5 access issues**:
* Individual users cannot access GPT-5 as it requires organization verification
* Use GPT-4 or other available models instead
* Contact OpenAI support if you need GPT-5 access for your organization
### Credit and Rate Limiting Issues
* **Running out of credits**:
* Monitor your OpenAI usage and billing
* Set up usage alerts to prevent unexpected charges
* **Rate limiting by AI providers**:
* Especially common with high-frequency operations like summarizers
* Monitor your API usage patterns and adjust accordingly
### Context Fetcher Issues
* **Context fetcher timeouts**:
* Check that external services are responding within expected timeframes
# Manage API
URL: /api-reference
undefined
***
title: Manage API
full: true
\_openapi:
toc:
* depth: 2
title: List Projects
url: '#list-projects'
* depth: 2
title: Create Project
url: '#create-project'
* depth: 2
title: Get Project
url: '#get-project'
* depth: 2
title: Update Project
url: '#update-project'
* depth: 2
title: Delete Project
url: '#delete-project'
* depth: 2
title: List SubAgents
url: '#list-subagents'
* depth: 2
title: Create SubAgent
url: '#create-subagent'
* depth: 2
title: Get SubAgent
url: '#get-subagent'
* depth: 2
title: Delete SubAgent
url: '#delete-subagent'
* depth: 2
title: Update SubAgent
url: '#update-subagent'
* depth: 2
title: List Agent Relations
url: '#list-agent-relations'
* depth: 2
title: Create Agent Relation
url: '#create-agent-relation'
* depth: 2
title: Get Agent Relation
url: '#get-agent-relation'
* depth: 2
title: Delete Agent Relation
url: '#delete-agent-relation'
* depth: 2
title: Update Agent Relation
url: '#update-agent-relation'
* depth: 2
title: List Agents
url: '#list-agent-graphs'
* depth: 2
title: Create Agent
url: '#create-agent-graph'
* depth: 2
title: Get Agent
url: '#get-agent-graph'
* depth: 2
title: Delete Agent
url: '#delete-agent-graph'
* depth: 2
title: Update Agent
url: '#update-agent-graph'
* depth: 2
title: Get Related Agent Infos
url: '#get-related-agent-infos'
* depth: 2
title: Get Full Agent Definition
url: '#get-full-agent-definition'
* depth: 2
title: List SubAgent Tool Relations
url: '#list-subagent-tool-relations'
* depth: 2
title: Create SubAgent Tool Relation
url: '#create-subagent-tool-relation'
* depth: 2
title: Get SubAgent Tool Relation
url: '#get-subagent-tool-relation'
* depth: 2
title: Delete SubAgent Tool Relation
url: '#delete-subagent-tool-relation'
* depth: 2
title: Update SubAgent Tool Relation
url: '#update-subagent-tool-relation'
* depth: 2
title: Get SubAgents for Tool
url: '#get-subagents-for-tool'
* depth: 2
title: Get Artifact Components for Agent
url: '#get-artifact-components-for-agent'
* depth: 2
title: Get Agents Using Artifact Component
url: '#get-agents-using-artifact-component'
* depth: 2
title: Associate Artifact Component with Agent
url: '#associate-artifact-component-with-agent'
* depth: 2
title: Remove Artifact Component from Agent
url: '#remove-artifact-component-from-agent'
* depth: 2
title: Check if Artifact Component is Associated with Agent
url: '#check-if-artifact-component-is-associated-with-agent'
* depth: 2
title: Get Data Components for Agent
url: '#get-data-components-for-agent'
* depth: 2
title: Get Agents Using Data Component
url: '#get-agents-using-data-component'
* depth: 2
title: Associate Data Component with Agent
url: '#associate-data-component-with-agent'
* depth: 2
title: Remove Data Component from Agent
url: '#remove-data-component-from-agent'
* depth: 2
title: Check if Data Component is Associated with Agent
url: '#check-if-data-component-is-associated-with-agent'
* depth: 2
title: List Artifact Components
url: '#list-artifact-components'
* depth: 2
title: Create Artifact Component
url: '#create-artifact-component'
* depth: 2
title: Get Artifact Component
url: '#get-artifact-component'
* depth: 2
title: Delete Artifact Component
url: '#delete-artifact-component'
* depth: 2
title: Update Artifact Component
url: '#update-artifact-component'
* depth: 2
title: List Context Configurations
url: '#list-context-configurations'
* depth: 2
title: Create Context Configuration
url: '#create-context-configuration'
* depth: 2
title: Get Context Configuration
url: '#get-context-configuration'
* depth: 2
title: Delete Context Configuration
url: '#delete-context-configuration'
* depth: 2
title: Update Context Configuration
url: '#update-context-configuration'
* depth: 2
title: List Credentials
url: '#list-credentials'
* depth: 2
title: Create Credential
url: '#create-credential'
* depth: 2
title: Get Credential
url: '#get-credential'
* depth: 2
title: Delete Credential
url: '#delete-credential'
* depth: 2
title: Update Credential
url: '#update-credential'
* depth: 2
title: List Data Components
url: '#list-data-components'
* depth: 2
title: Create Data Component
url: '#create-data-component'
* depth: 2
title: Get Data Component
url: '#get-data-component'
* depth: 2
title: Delete Data Component
url: '#delete-data-component'
* depth: 2
title: Update Data Component
url: '#update-data-component'
* depth: 2
title: List External Agents
url: '#list-external-agents'
* depth: 2
title: Create External Agent
url: '#create-external-agent'
* depth: 2
title: Get External Agent
url: '#get-external-agent'
* depth: 2
title: Delete External Agent
url: '#delete-external-agent'
* depth: 2
title: Update External Agent
url: '#update-external-agent'
* depth: 2
title: List Function Tools
url: '#list-function-tools'
* depth: 2
title: Create Function Tool
url: '#create-function-tool'
* depth: 2
title: Get Function Tool by ID
url: '#get-function-tool-by-id'
* depth: 2
title: Delete Function Tool
url: '#delete-function-tool'
* depth: 2
title: Update Function Tool
url: '#update-function-tool'
* depth: 2
title: List Functions
url: '#list-functions'
* depth: 2
title: Create Function
url: '#create-function'
* depth: 2
title: Get Function by ID
url: '#get-function-by-id'
* depth: 2
title: Delete Function
url: '#delete-function'
* depth: 2
title: Update Function
url: '#update-function'
* depth: 2
title: List Tools
url: '#list-tools'
* depth: 2
title: Create Tool
url: '#create-tool'
* depth: 2
title: Get Tool
url: '#get-tool'
* depth: 2
title: Delete Tool
url: '#delete-tool'
* depth: 2
title: Update Tool
url: '#update-tool'
* depth: 2
title: List API Keys
url: '#list-api-keys'
* depth: 2
title: Create API Key
url: '#create-api-key'
* depth: 2
title: Get API Key
url: '#get-api-key'
* depth: 2
title: Delete API Key
url: '#delete-api-key'
* depth: 2
title: Update API Key
url: '#update-api-key'
* depth: 2
title: Create Full Agent
url: '#create-full-agent'
* depth: 2
title: Get Full Agent
url: '#get-full-agent'
* depth: 2
title: Delete Full Agent
url: '#delete-full-agent'
* depth: 2
title: Update Full Agent
url: '#update-full-agent'
* depth: 2
title: Create Full Project
url: '#create-full-project'
* depth: 2
title: Get Full Project
url: '#get-full-project'
* depth: 2
title: Delete Full Project
url: '#delete-full-project'
* depth: 2
title: Update Full Project
url: '#update-full-project'
* depth: 2
title: Initiate OAuth login for MCP tool
url: '#initiate-oauth-login-for-mcp-tool'
* depth: 2
title: OAuth authorization callback
url: '#oauth-authorization-callback'
structuredData:
headings:
* content: List Projects
id: list-projects
* content: Create Project
id: create-project
* content: Get Project
id: get-project
* content: Update Project
id: update-project
* content: Delete Project
id: delete-project
* content: List SubAgents
id: list-subagents
* content: Create SubAgent
id: create-subagent
* content: Get SubAgent
id: get-subagent
* content: Delete SubAgent
id: delete-subagent
* content: Update SubAgent
id: update-subagent
* content: List Agent Relations
id: list-agent-relations
* content: Create Agent Relation
id: create-agent-relation
* content: Get Agent Relation
id: get-agent-relation
* content: Delete Agent Relation
id: delete-agent-relation
* content: Update Agent Relation
id: update-agent-relation
* content: List Agents
id: list-agent-graphs
* content: Create Agent
id: create-agent-graph
* content: Get Agent
id: get-agent-graph
* content: Delete Agent
id: delete-agent-graph
* content: Update Agent
id: update-agent-graph
* content: Get Related Agent Infos
id: get-related-agent-infos
* content: Get Full Agent Definition
id: get-full-agent-definition
* content: List SubAgent Tool Relations
id: list-subagent-tool-relations
* content: Create SubAgent Tool Relation
id: create-subagent-tool-relation
* content: Get SubAgent Tool Relation
id: get-subagent-tool-relation
* content: Delete SubAgent Tool Relation
id: delete-subagent-tool-relation
* content: Update SubAgent Tool Relation
id: update-subagent-tool-relation
* content: Get SubAgents for Tool
id: get-subagents-for-tool
* content: Get Artifact Components for Agent
id: get-artifact-components-for-agent
* content: Get Agents Using Artifact Component
id: get-agents-using-artifact-component
* content: Associate Artifact Component with Agent
id: associate-artifact-component-with-agent
* content: Remove Artifact Component from Agent
id: remove-artifact-component-from-agent
* content: Check if Artifact Component is Associated with Agent
id: check-if-artifact-component-is-associated-with-agent
* content: Get Data Components for Agent
id: get-data-components-for-agent
* content: Get Agents Using Data Component
id: get-agents-using-data-component
* content: Associate Data Component with Agent
id: associate-data-component-with-agent
* content: Remove Data Component from Agent
id: remove-data-component-from-agent
* content: Check if Data Component is Associated with Agent
id: check-if-data-component-is-associated-with-agent
* content: List Artifact Components
id: list-artifact-components
* content: Create Artifact Component
id: create-artifact-component
* content: Get Artifact Component
id: get-artifact-component
* content: Delete Artifact Component
id: delete-artifact-component
* content: Update Artifact Component
id: update-artifact-component
* content: List Context Configurations
id: list-context-configurations
* content: Create Context Configuration
id: create-context-configuration
* content: Get Context Configuration
id: get-context-configuration
* content: Delete Context Configuration
id: delete-context-configuration
* content: Update Context Configuration
id: update-context-configuration
* content: List Credentials
id: list-credentials
* content: Create Credential
id: create-credential
* content: Get Credential
id: get-credential
* content: Delete Credential
id: delete-credential
* content: Update Credential
id: update-credential
* content: List Data Components
id: list-data-components
* content: Create Data Component
id: create-data-component
* content: Get Data Component
id: get-data-component
* content: Delete Data Component
id: delete-data-component
* content: Update Data Component
id: update-data-component
* content: List External Agents
id: list-external-agents
* content: Create External Agent
id: create-external-agent
* content: Get External Agent
id: get-external-agent
* content: Delete External Agent
id: delete-external-agent
* content: Update External Agent
id: update-external-agent
* content: List Function Tools
id: list-function-tools
* content: Create Function Tool
id: create-function-tool
* content: Get Function Tool by ID
id: get-function-tool-by-id
* content: Delete Function Tool
id: delete-function-tool
* content: Update Function Tool
id: update-function-tool
* content: List Functions
id: list-functions
* content: Create Function
id: create-function
* content: Get Function by ID
id: get-function-by-id
* content: Delete Function
id: delete-function
* content: Update Function
id: update-function
* content: List Tools
id: list-tools
* content: Create Tool
id: create-tool
* content: Get Tool
id: get-tool
* content: Delete Tool
id: delete-tool
* content: Update Tool
id: update-tool
* content: List API Keys
id: list-api-keys
* content: Create API Key
id: create-api-key
* content: Get API Key
id: get-api-key
* content: Delete API Key
id: delete-api-key
* content: Update API Key
id: update-api-key
* content: Create Full Agent
id: create-full-agent
* content: Get Full Agent
id: get-full-agent
* content: Delete Full Agent
id: delete-full-agent
* content: Update Full Agent
id: update-full-agent
* content: Create Full Project
id: create-full-project
* content: Get Full Project
id: get-full-project
* content: Delete Full Project
id: delete-full-project
* content: Update Full Project
id: update-full-project
* content: Initiate OAuth login for MCP tool
id: initiate-oauth-login-for-mcp-tool
* content: OAuth authorization callback
id: oauth-authorization-callback
contents:
* content: Check if the management service is healthy
* content: List all projects within a tenant with pagination
heading: list-projects
* content: Create a new project
heading: create-project
* content: Get a single project by ID
heading: get-project
* content: Update an existing project
heading: update-project
* content: Delete a project. Will fail if the project has existing resources.
heading: delete-project
* content: List all API keys for a tenant with optional pagination
heading: list-api-keys
* content: >-
Create a new API key for an Agent. Returns the full key (shown only
once).
heading: create-api-key
* content: Get a specific API key by ID (does not return the actual key)
heading: get-api-key
* content: Delete an API key permanently
heading: delete-api-key
* content: Update an API key (currently only expiration date can be changed)
heading: update-api-key
* content: >-
Create a complete agent with all Sub Agents, tools, and
relationships from JSON definition
heading: create-full-agent
* content: >-
Retrieve a complete agent definition with all Sub Agents, tools, and
relationships
heading: get-full-agent
* content: >-
Delete a complete agent and cascade to all related entities
(relationships, not other Sub Agents/tools)
heading: delete-full-agent
* content: >-
Update or create a complete agent with all Sub Agents, tools, and
relationships from JSON definition
heading: update-full-agent
* content: >-
Create a complete project with all agents, Sub Agents, tools, and
relationships from JSON definition
heading: create-full-project
* content: >-
Retrieve a complete project definition with all agents, Sub Agents, tools,
and relationships
heading: get-full-project
* content: >-
Delete a complete project and cascade to all related entities (agents,
Sub Agents, tools, relationships)
heading: delete-full-project
* content: >-
Update or create a complete project with all agents, Sub Agents, tools,
and relationships from JSON definition
heading: update-full-project
* content: >-
Detects OAuth requirements and redirects to authorization server
(public endpoint)
heading: initiate-oauth-login-for-mcp-tool
* content: >-
Handles OAuth authorization codes and completes the authentication
flow
heading: oauth-authorization-callback
***
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
REST API for the management of the Inkeep Agent Framework.
## Run `inkeep pull`
Make some changes, like changing a prompt, and let's walk through `inkeep pull`.
### Requirements
The `inkeep pull` command in-part leverages AI to sync your TypeScript files to the state of your Visual Builder, so **at least one** of the below environment variables to be defined:
```txt .env
# Choose one:
ANTHROPIC_API_KEY=your_api_key_here
# or
OPENAI_API_KEY=your_api_key_here
# or
GOOGLE_API_KEY=your_api_key_here
```
The CLI prioritizes Anthropic → OpenAI → Google.
Here are the models used:
| Provider | Model(s) | Where to Get API Key |
| --------- | ------------------------------------- | --------------------------------------------------- |
| Anthropic | Claude Sonnet 4.5 (extended thinking) | [Anthropic Console](https://console.anthropic.com/) |
| OpenAI | GPT-4.1 | [OpenAI Platform](https://platform.openai.com/) |
| Google | Gemini models (with thinking mode) | [Google AI Studio](https://ai.google.dev/) |
### Step 1: Make an edit visually
Make an edit to the docs assistant agent in the UI, such as changing the prompt of the agent.
### Step 2: Pull code from visual
Navigate to your docs assistant project.
```bash
cd src/projects/docs-assistant
```
Use `inkeep pull` to pull the code from the Visual Builder to your local project.
```bash
inkeep pull
```
### Step 3: Verify the code was pulled
Check the `src/projects/docs-assistant/agents/docs-assistant.ts` file for the updated prompt.
```bash
cat src/projects/docs-assistant/agents/docs-assistant.ts
```
## Next steps
Next, we recommend setting up observability to see live traces of your agent. See [Traces](/get-started/traces) to get started.
### Step 4: Install Inkeep MCP (optional)
To help with development, add the `Inkeep Agents MCP` to your preferred IDE or MCP client. It has tools to help "vibe code" agents with the Inkeep SDK.
## Setup Options
You can set up SigNoz in two ways:
1. **Cloud Setup**: Use SigNoz Cloud
2. **Local Setup**: Run SigNoz locally using Docker
## Option 1: SigNoz Cloud Setup
Click on any conversation to see detailed execution flow:
<>
### Copy Trace for Debugging
The `Copy Trace` button in the timeline view allows you to export the entire conversation trace as JSON. This is particularly useful for offline analysis and debugging complex flows.
#### What's Included in the Trace Export
When you click `Copy Trace`, the system exports a JSON object containing:
```json
{
"metadata": {
"conversationId": "unique-conversation-id",
"traceId": "distributed-trace-id",
"agentId": "agent-identifier",
"agentName": "Agent Name",
"exportedAt": "2025-10-14T12:00:00.000Z"
},
"timing": {
"startTime": "2025-10-14T11:59:00.000Z",
"endTime": "2025-10-14T12:00:00.000Z",
"durationMs": 60000
},
"timeline": [
// Array of all activities with complete details:
// - Agent messages and responses
// - Tool calls and results
// - Agent transfers
// - Artifact information
// - Execution context
]
}
```
#### How to Use Copy Trace
1. Navigate to the **Traces** section in the management UI
2. Open the conversation you want to debug
3. Click the **Copy Trace** button at the top of the timeline
4. The complete trace JSON is copied to your clipboard
5. Paste it into your preferred tool for analysis
This exported trace contains all the activities shown in the timeline, making it easy to share complete execution context with team members or support.
### 2. SigNoz Dashboard
For detailed analysis and further debugging:
1. Open your SigNoz dashboard (cloud or local)
2. Navigate to **Traces** to see all agent executions
3. Use filters to find specific conversations or agents
4. Click on traces to see:
* Step-by-step execution details
* Performance metrics
* Error information
* Agent-to-agent communication flows
For more detailed information on using traces, see the [SigNoz Usage guide](/typescript-sdk/signoz-usage).
## Additional Observability and Evals
👉 For additional observability or a dedicated Evals platform, you can connect to any OTEL-based provider. For example, check out the [Langfuse Usage guide](/typescript-sdk/langfuse-usage) for end-to-end instructions.
# Deploy to AWS EC2
URL: /self-hosting/aws-ec2
Deploy to AWS EC2 with Docker Compose
***
title: Deploy to AWS EC2
sidebarTitle: AWS EC2
description: Deploy to AWS EC2 with Docker Compose
icon: "LuServerCog"
-------------------
## Create a VM Instance
* Go to [Compute Engine](https://console.aws.amazon.com/ec2/v2/home).
* Launch an instance
* Select Amazon Machine Image (AMI)
* Recommended size is at least `t2.large` (2 vCPU, 8 GiB Memory).
* Click "Edit" in the "Network settings" section. Set up an Inbound Security Group Rules for (TCP, 3000, 0.0.0.0/0), (TCP, 3002-3003, 0.0.0.0/0), (TCP, 3050-3051, 0.0.0.0/0), and (TCP, 3080, 0.0.0.0/0). These are the ports exposed by the Inkeep services.
* Auto-assign public IP
* Increase the size of storage to 30 GiB.
## Install Docker Compose
1. SSH into the EC2 Instance
2. Install packages
```bash
sudo dnf update
sudo dnf install -y git
sudo dnf install -y docker
```
```bash
sudo mkdir -p /usr/libexec/docker/cli-plugins
sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o /usr/libexec/docker/cli-plugins/docker-compose
sudo chmod +x /usr/libexec/docker/cli-plugins/docker-compose
```
## Deploy SigNoz and Nango
Clone this repo, which includes Docker files with SigNoz and Nango:
```bash
git clone https://github.com/inkeep/agents-optional-local-dev inkeep-external-services
cd inkeep-external-services
```
Run this command to autogenerate a `.env` file:
```bash
cp .env.example .env && \
encryption_key=$(openssl rand -base64 32) && \
tmp_file=$(mktemp) && \
sed "s|timeout value in sandbox configurationvcpus for resource-intensive functionsvcpus allocation if functions don't need maximum resourcesFor more information on function tools, see:
**Setting up the LLM Connection:**
1. **Navigate to "Evaluator Library"** in your Langfuse dashboard
2. **Click "Set up"** next to "Default Evaluation Model"
3. **Configure the LLM connection**:
* **LLM Adapter**: Select your preferred provider
* **Provider Name**: Give it a descriptive name (e.g., "openai")
* **API Key**: Enter your OpenAI API key (stored encrypted)
* **Advanced Settings**: Configure base URL, model parameters if needed
4. **Click "Create connection"** to save
#### Navigate to Evaluator Setup
1. **Go to "Evaluations"** → **"Running Evaluators"**
2. **Click "Set up evaluator"** button
3. **You'll see two main steps**: "1. Select Evaluator" and "2. Run Evaluator"
#### Choose Your Evaluator Type
You have two main options:
## Option A: Langfuse Managed Evaluators
Langfuse provides a comprehensive catalog of **pre-built evaluators**
**To use a managed evaluator:**
1. **Browse the evaluator list** and find one that matches your needs
2. **Click on the evaluator** to see its description and criteria
3. **Click "Use Selected Evaluator"** button
#### Customizing Managed Evaluators for Dataset Runs
Once you've selected a managed evaluator, you can **edit it to target your dataset runs**. This is particularly useful for evaluating agent performance against known test cases.
### Example: Customizing a Helpfulness Evaluator
1. **Select the "Helpfulness" evaluator** from the managed list
2. Under **Target** select dataset runs
3. **Configure variable mapping**
* **{`{{input}}`}** → **Object**: Trace, **Object Variable**: Input
* **{`{{generation}}`}** → **Object**: Trace, **Object Variable**: Output
## Option B: Create Custom Evaluator
1. **Click "+ Create Custom Evaluator"** button
2. **Fill in evaluator details**:
* **Name**: Choose a descriptive name (e.g., "weather\_tool\_used")
* **Description**: Explain what this evaluator measures
* **Model**: Select evaluation model
* **Prompt**: Configure a custom prompt
### Example: Customizing a Weather Tool Evaluator
1. **Prompt**
```
You are an expert evaluator for an AI agent system.
Your task is to rate the correctness of tool usage on a scale from 0.0 to 1.0.
Instructions:
If the user’s question is not weather-related and the tool used is not get_weather_forecast, return 1.0.
If the user’s question is not weather-related and the tool is get_weather_forecast, return 0.0.
If the user’s question is weather-related, return 1.0 only if the tool used is get_weather_forecast; otherwise return 0.0.
Input:
User Question: {`{{input}}`}
Tool Used: {`{{tool_used}}`}
```
2. **Configure variable mapping**:
* **{`{{input}}`}** → **Object**: Trace, **Object Variable**: Input
* **{`{{tool_used}}`}** → **Object**: Span, **Object Name**: weather-forecaster.ai.toolCall, **Object Variable**: Metadata, **JsonPath**: $.attributes\["ai.toolCall.name"]
## Enable and Monitor
1. **Click "Enable Evaluator"** to start automatic evaluation
2. **Monitor evaluation progress** in the dashboard
3. **View evaluation results** as they complete
# Project Structure
URL: /typescript-sdk/project-structure
Learn how to organize your Inkeep Agent projects for optimal development and deployment
***
title: Project Structure
description: Learn how to organize your Inkeep Agent projects for optimal development and deployment
icon: "LuFolder"
----------------
## Overview
Inkeep Agent projects follow a standardized directory structure that enables the CLI to automatically discover and manage your Agents, Sub Agents, tools, and configurations. This convention-based approach simplifies project organization and deployment workflows.
## Standard Project Layout
```
workspace-root/ # Repository/workspace root
├── package.json # Workspace package.json
├── tsconfig.json # TypeScript configuration
├── inkeep.config.ts # Inkeep configuration file
├── my-agent-project/ # Individual project directory
│ ├── index.ts # Project entry point
│ ├── agents/ # Agent definitions
│ │ ├── main-agent.ts
│ │ └── support-agent.ts
│ ├── tools/ # Tool definitions
│ │ ├── search-tool.ts
│ │ └── calculator-tool.ts
│ ├── data-components/ # Data component definitions
│ │ ├── user-profile.ts
│ │ └── product-catalog.ts
│ ├── external-agents/ # External agent definitions
│ │ ├── exernal-agent-example.ts
│ └── environments/ # Environment-specific configurations
│ ├── index.ts
│ ├── development.env.ts
│ ├── staging.env.ts
│ └── production.env.ts
└── another-project/ # Additional projects can coexist
├── index.ts
└── ...
```
## Core Files
### `inkeep.config.ts`
The configuration file at the workspace root that defines settings for all projects in this workspace:
```typescript
// Located at workspace root, same level as package.json
import { defineConfig } from '@inkeep/agents-cli/config';
export default defineConfig({
tenantId: 'my-company',
agentsManageApiUrl: 'http://localhost:3002',
agentsRunApiUrl: 'http://localhost:3003',
});
```
**Important**: This file lives at the workspace/repository root level, **not** inside individual project directories.
### `index.ts`
The project entry point inside each project directory that exports your project definition:
```typescript
// Located inside project directory (e.g., my-agent-project/index.ts)
import { project } from '@inkeep/agents-sdk';
import { mainAgent } from './agents/main-agent';
import { supportAgent } from './agents/support-agent';
import { searchTool } from './tools/search-tool';
import { calculatorTool } from './tools/calculator-tool';
import { userProfile } from './data-components/user-profile';
export const myProject = project({
id: 'my-agent-project',
name: 'My Agent Project',
description: 'A comprehensive multi-agent system',
subAgents: () => [mainAgent, supportAgent],
tools: () => [searchTool, calculatorTool],
dataComponents: () => [userProfile],
});
```
## Directory Conventions
### `/agents/`
Contains agent definitions. Each file typically exports one agent:
```typescript
// agents/customer-support.ts
import { agent, subAgent } from '@inkeep/agents-sdk';
const routerSubAgent = subAgent({
id: 'support-router',
name: 'Support Router',
prompt: 'Route customer inquiries to appropriate specialists',
});
const billingSubAgent = subAgent({
id: 'billing-specialist',
name: 'Billing Specialist',
prompt: 'Handle billing and payment inquiries',
});
export const customerSupportAgent = agent({
defaultSubAgent: routerSubAgent,
subAgents: () => [routerSubAgent, billingSubAgent],
});
```
### `/tools/`
Tool definitions that can be used by Sub Agents:
```typescript
// tools/database-query.ts
import { tool } from '@inkeep/agents-sdk';
export const databaseQueryTool = tool({
id: 'db-query',
name: 'Database Query Tool',
description: 'Execute SQL queries against the database',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string' },
database: { type: 'string' }
}
},
// Tool implementation...
});
```
### `/data-components/`
Data components for structured UI output:
```typescript
// data-components/customer-data.ts
import { dataComponent } from '@inkeep/agents-sdk';
import { z } from 'zod';
export const customerData = dataComponent({
id: 'customer-data',
name: 'Customer Information',
description: 'Customer profile and interaction history',
props: z.object({
customerId: z.string().describe("Customer ID"),
name: z.string().describe("Customer name"),
email: z.string().describe("Customer email"),
}),
});
```
### `/external-agents/`
External agent definitions:
```typescript
import { externalAgent } from '@inkeep/agents-sdk';
export const exernalAgentExample = externalAgent({
id: 'exernal-agent-example',
name: 'Exernal Agent Example',
description: 'An example external agent',
baseUrl: 'https://api.example.com/agents/support',
credentialReference: myCredentialReference,
});
```
### `/environments/`
Environment-specific configurations for different deployment stages:
```typescript
// environments/production.env.ts
import { registerEnvironmentSettings } from '@inkeep/agents-sdk';
import { CredentialStoreType } from '@inkeep/agents-core';
export const production = registerEnvironmentSettings({
credentials: {
"openai-prod": {
id: "openai-prod",
type: CredentialStoreType.memory,
credentialStoreId: "memory-default",
retrievalParams: {
key: "OPENAI_API_KEY_PROD",
},
},
},
});
```
## File Discovery Process
The CLI automatically discovers files using these patterns:
1. **Config Discovery**: Searches for `inkeep.config.ts`:
* Starts from current working directory
* Traverses **upward** through parent directories until found
* Looks at the same level as `package.json` and `tsconfig.json`
* Can be overridden with `--config` flag
2. **Project Discovery**: Once config is found:
* Uses the config file's directory as the workspace root
* Scans for project subdirectories containing `index.ts`
* Each project directory is treated as a separate agent project
3. **Resource Discovery**: Within each project directory:
* Excludes `node_modules/` and `.git/`
* Categorizes files by directory name and content
* Processes dependencies and relationships
4. **File Categorization**:
* **Index files**: `index.ts`, `main.ts` (project entry points)
* **Agent files**: Files in `/agents/` directory
* **Sub Agent files**: Files containing Sub Agent definitions
* **Tool files**: Files in `/tools/` directory
* **Data component files**: Files in `/data-components/` directory
* **External agent files**: Files in `/external-agents/` directory
* **Environment files**: Files in `/environments/` directory
## Best Practices
### Naming Conventions
* Use kebab-case for file names: `customer-support-agent.ts`
* Use camelCase for variable names: `customerSupportAgent`
* Use descriptive IDs: `id: 'customer-support-router'`
### File Organization
* **One primary export per file**: Each file should export one main resource
* **Group related functionality**: Keep related Sub Agents in the same Agent file
* **Separate concerns**: Keep tools, data components, and agents in separate directories
* **Environment isolation**: Use separate files for different environments
### Dependencies
* **Explicit imports**: Import all dependencies explicitly
* **Circular dependency avoidance**: Structure imports to prevent circular references
* **Type safety**: Use TypeScript for all configuration files
## Troubleshooting
### Common Issues
**Config file not found:**
```bash
Error: Could not find inkeep.config.ts in current directory or parent directories
```
* Ensure `inkeep.config.ts` exists at your **workspace root** (same level as `package.json`)
* CLI searches upward from current directory - make sure you're in or below the workspace
* Use `--config` flag to specify custom location if needed
**Invalid project structure:**
```bash
Warning: No agents found in project
```
* Check that you're running from within a project directory (containing `index.ts`)
* Verify Agent files are in the project's `/agents/` subdirectory
* Ensure exports are properly named and typed
**Missing dependencies:**
```bash
Error: Cannot resolve import './agents/missing-agent'
```
* Ensure all imported files exist within the project directory
* Check relative file paths and extensions
* Verify imports use correct paths relative to project root
### Validation
Use the CLI to validate your project structure:
```bash
# Validate project without pushing
inkeep push --json
# Check config resolution
inkeep config get
```
## Migration from Legacy Structures
If migrating from older project structures:
1. **Move config to workspace root**: Ensure `inkeep.config.ts` is at same level as `package.json`
2. **Create project directories**: Organize agents into project subdirectories
3. **Create standard subdirectories**: Add `/agents/`, `/tools/`, `/data-components/` within each project
4. **Move files appropriately**: Organize existing files into correct project and subdirectories
5. **Update imports**: Fix import paths after restructuring
6. **Test compilation**: Run `inkeep push --json` to validate structure
7. **Update CI/CD**: Adjust build scripts for new workspace structure
This standardized structure ensures your projects work seamlessly with the Inkeep CLI and can be easily shared, deployed, and maintained across different environments.
# Push and Pull Workflows
URL: /typescript-sdk/push-pull-workflows
Understand the complete workflows for pushing and pulling agent projects with detailed flow diagrams
***
title: Push and Pull Workflows
description: Understand the complete workflows for pushing and pulling agent projects with detailed flow diagrams
icon: "LuGitBranch"
-------------------
## Overview
The `inkeep push` and `inkeep pull` commands implement sophisticated workflows for deploying and synchronizing agent projects. These workflows handle project discovery, configuration resolution, resource compilation, and bidirectional synchronization between local and remote environments.
## Push Workflow
The push workflow deploys your local project to the Inkeep management API:
```mermaid
graph TD
A[inkeep push] --> B[Parse CLI Arguments]
B --> C{--config provided?}
C -->|Yes| D[Load specified config]
C -->|No| E[Search for inkeep.config.ts]
E --> F{Config found?}
F -->|No| G[Error: Config not found]
F -->|Yes| H[Load config file]
D --> I[Apply Environment Variables]
H --> I
I --> J[Apply CLI Flag Overrides]
J --> K{--env provided?}
K -->|Yes| L[Load environment config]
K -->|No| M[Use base config only]
L --> N{Environment file exists?}
N -->|No| O[Error: Environment not found]
N -->|Yes| P[Merge environment settings]
P --> Q[Project Discovery]
M --> Q
Q --> R[Scan project directory]
R --> S[Find TypeScript files]
S --> T[Categorize files by type]
T --> U[Load and compile resources]
U --> V{--json flag?}
V -->|Yes| W[Export to JSON file]
V -->|No| X[Validate project resources]
X --> Y[Connect to Management API]
Y --> Z[Deploy resources]
Z --> AA[Print deployment summary]
W --> BB[Save JSON and exit]
G --> CC[Exit with error]
O --> CC
```
### Push Process Details
1. **Argument Parsing**: CLI parses command-line arguments and flags
2. **Configuration Resolution**: Loads and merges configuration from multiple sources
3. **Environment Application**: Applies environment-specific settings if specified
4. **Project Discovery**: Scans project directory for resources
5. **Resource Compilation**: Compiles TypeScript files and resolves dependencies
6. **Validation**: Validates resource configurations and relationships
7. **Deployment**: Uploads resources to management API
8. **Confirmation**: Returns deployment summary
### Configuration Resolution Flow
```mermaid
graph TD
A[Start Config Resolution] --> B{--config flag?}
B -->|Yes| C[Load specified file]
B -->|No| D[Current working directory]
D --> E{inkeep.config.ts exists?}
E -->|Yes| F[Load config from current dir]
E -->|No| G[Check parent directory]
G --> H{At filesystem root?}
H -->|No| E
H -->|Yes| I[Config not found error]
C --> J[Base Configuration]
F --> J
J --> K[Apply Environment Variables]
K --> L[Apply CLI Flags]
L --> M{--env flag?}
M -->|Yes| N[Load environments/env.env.ts from project]
M -->|No| O[Final Configuration]
N --> P{Environment file exists in project?}
P -->|No| Q[Environment error]
P -->|Yes| R[Merge environment settings]
R --> O
style C fill:#e1f5fe
style F fill:#e1f5fe
style O fill:#c8e6c9
style I fill:#ffcdd2
style Q fill:#ffcdd2
%% Notes
S["📝 Config file lives at workspace root
The traces explorer shows:
* **Timestamp**: When each span occurred
* **Service Name**: The service that generated the span (e.g., `inkeep-agents-run-api`)
* **Operation Name**: Specific operations like `ai.generateObject`, `tls.connect`, `ai.toolCall`
* **Duration**: How long each operation took (in milliseconds)
* **HTTP Method**: For HTTP operations, shows the method (POST, GET, etc.)
* **Response Status Code**: HTTP status codes (200, 404, etc.)
Key features of the traces view:
* **Filtering Options**: Use the left sidebar to filter by duration, deployment environment, service name, and more
* **Time Range Selection**: Choose from preset ranges or custom time periods
* **Multiple Views**: Switch between List View, Traces, Time Series, and Table View
* **Real-time Updates**: Traces refresh automatically to show new data
* **Trace List**: Browse all traces with filtering options
* **Trace Details**: Drill down into individual traces
* **Span Timeline**: See the execution flow across agents
#### Filtering Traces
```
# Filter by service
service_name = "inkeep-agents-run-api"
# Filter by operation
operation = "agent.generate"
# Filter by status
status = "error"
# Filter by duration
duration > 1000ms
# Filter by custom attributes
agent.id = "customer-support-agent"
```
#### Analyzing Individual Traces
When you click on a specific trace from the list, you'll see the detailed trace view with a flamegraph visualization:
**Flamegraph Visualization:**
* **Horizontal Bars**: Each bar represents a span (operation) in your trace
* **Bar Width**: Proportional to the duration of the operation
* **Color Coding**:
* Blue bars: Successful operations
* Red bars: Operations with errors
**Key Information Displayed:**
* **Total Spans**: Total number of operations in this trace (e.g., 122)
* **Error Spans**: Number of spans that encountered errors (e.g., 19)
* **Trace Duration**: Total time for the entire trace (e.g., 5.2 mins)
* **Timestamp**: When the trace occurred
* **Service**: The primary service (e.g., `inkeep-agents-run-api`)
**Span Details Panel (Right Side):**
* **Span Name & ID**: Operation name and unique identifier
* **Timing**: Start time and duration
* **Service & Kind**: Which service and span type (Server, Client, etc.)
* **Status**: Success/error status code
* **Attributes, Events & Links**: Additional span metadata
**How to Use This View:**
1. **Identify Bottlenecks**: Look for the widest bars in the flamegraph - these represent the longest-running operations
2. **Find Errors**: Red bars indicate operations that failed - click on them to see error details
3. **Understand Flow**: Follow the vertical hierarchy to see how operations call each other
4. **Analyze Performance**: Use the timeline to see which operations run in parallel vs. sequentially
5. **Drill Down**: Click on any span to see detailed attributes, events, and error information
# JSON Schema guide for components
URL: /ui-components/json-schema-validation
Guide for writing valid JSON Schemas for data components and artifact components
***
title: JSON Schema guide for components
sidebarTitle: JSON Schemas
description: Guide for writing valid JSON Schemas for data components and artifact components
icon: LuFileCheck
keywords: JSON Schema, data components, artifact components, LLM compatibility
------------------------------------------------------------------------------
This guide shows you how to write valid JSON Schemas for your components. The framework validates these schemas to ensure they work properly with LLMs.
## Why validation matters
LLMs need clear, structured information to understand how to use your components. The validation ensures:
* All properties have descriptions (so the LLM knows what they're for)
* Required fields are clearly marked
* The schema structure is correct
## Data component props
When creating data components, your `props` field must be a valid JSON Schema:
### ✅ Valid example
```json
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The title of the content item"
},
"url": {
"type": "string",
"description": "The URL where this content can be accessed"
},
"tags": {
"type": "array",
"description": "List of tags to categorize this content",
"items": {
"type": "string"
}
},
"priority": {
"type": "string",
"enum": ["low", "medium", "high"],
"description": "Priority level for this content item"
}
},
"required": ["title", "url"]
}
```
### ❌ Common mistakes
```json
{
// ❌ Missing "type": "object"
"properties": {
"title": {
"type": "string"
// ❌ Missing description
}
}
// ❌ Missing required array
}
```
## Artifact component schemas
Artifact components use a single unified schema called `props` with `inPreview` indicators.
### Unified props schema
Fields marked with `inPreview: true` appear in summary views, while all fields are stored in the database:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Title of the artifact",
"inPreview": true
},
"status": {
"type": "string",
"enum": ["draft", "published", "archived"],
"description": "Current status of the artifact",
"inPreview": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the artifact was created",
"inPreview": true
},
"content": {
"type": "string",
"description": "Main content of the artifact"
},
"metadata": {
"type": "object",
"description": "Additional metadata for the artifact",
"properties": {
"author": {
"type": "string",
"description": "Who created this artifact"
},
"version": {
"type": "string",
"description": "Version number of the artifact"
}
},
"required": ["author"]
},
"attachments": {
"type": "array",
"description": "Files attached to this artifact",
"items": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Name of the attached file"
},
"url": {
"type": "string",
"description": "URL to download the file"
}
},
"required": ["filename", "url"]
}
}
},
"required": ["title", "status", "content"]
}
```
### Using Zod schemas with preview helpers
You can also use Zod schemas with the preview helper:
```typescript
import { z } from 'zod';
import { preview } from '@inkeep/agents-core/utils/schema-conversion';
const artifactSchema = z.object({
title: preview(z.string().describe("Title of the artifact")),
status: preview(z.enum(["draft", "published", "archived"]).describe("Current status")),
content: z.string().describe("Main content of the artifact"),
metadata: z.object({
author: z.string().describe("Who created this artifact"),
version: z.string().describe("Version number")
})
});
```
## Validation rules
The editor enforces these rules:
1. **Must be an object**: Top level must have `"type": "object"`
2. **Must have properties**: Include a `"properties"` object
3. **Must have required array**: Include a `"required"` array (even if empty)
4. **All properties need descriptions**: Every property must have a `"description"` field
### Quick template
Need a starting point? Click the "Template" button in the editor, or use this:
```json
{
"type": "object",
"properties": {
"example_property": {
"type": "string",
"description": "Description of what this property represents"
}
},
"required": ["example_property"]
}
```
## Common patterns
### Optional vs required
```json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "User's full name"
},
"email": {
"type": "string",
"description": "User's email address (optional)"
}
},
"required": ["name"]
// email is optional since it's not in the required array
}
```
### Enums for fixed choices
```json
{
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": ["work", "personal", "urgent"],
"description": "Category to organize this item"
}
},
"required": ["category"]
}
```
### Arrays with specific item types
```json
{
"type": "object",
"properties": {
"images": {
"type": "array",
"description": "List of image URLs for this item",
"items": {
"type": "string",
"format": "uri"
}
}
},
"required": ["images"]
}
```
That's it! The editor will guide you with real-time validation feedback as you type.
# Context Fetchers
URL: /visual-builder/context-fetchers
Learn how to use context fetchers to fetch data from external sources and make it available to your agents
***
title: Context Fetchers
sidebarTitle: Context Fetchers
description: Learn how to use context fetchers to fetch data from external sources and make it available to your agents
icon: "LuCirclePlus"
--------------------
## Overview
Context fetchers allow you to embed real-time data from external APIs into your agent prompts. Instead of hardcoding information in your agent prompt, context fetchers dynamically retrieve fresh data for each conversation.
## Key Features
* **Dynamic data retrieval**: Fetch real-time data from APIs.
* **Dynamic Prompting**: Use dynamic data in your agent prompts
* **Headers integration**: Use request-specific parameters to customize data fetching.
* **Data transformation**: Transform API responses into the exact format your agent needs.
## Context Fetchers vs Tools
* **Context Fetchers**: Pre-populate agent prompts with dynamic data
* Run automatically before/during conversation startup
* Data becomes part of the agent's system prompt
* Perfect for: Personalized agent personas, dynamic agent guardrails
* Example Prompt: `You are an assistant for {{user.name}} and you work for {{user.organization}}`
* **Tools**: Enable agents to take actions or fetch data during conversations
* Called by the agent when needed during the conversation
* Agent decides when and how to use them
* Example Tool Usage: Agent calls a "send\_email" tool or "search\_database" tool
## Basic Usage
1. Go to the Agents tab in the left sidebar. Then click on the agent you want to configure.
2. On the right pane scroll down to the "Context Variables" section.
3. Add your context variables in JSON format.
4. Click on the "Save" button.
## Defining Context Variables
The keys that you define in the Context Variables JSON object are used to reference fetched data in your agent prompts.
Each key in the JSON should map to a fetch definition with the following properties:
* **`id`** (required): Unique identifier for the fetch definition
* **`name`** (optional): Human-readable name for the fetch definition
* **`trigger`** (required): When to execute the fetch:
* `"initialization"`: Fetch only once when a conversation is started with the agent
* `"invocation"`: Fetch every time a request is made to the agent
* **`fetchConfig`** (required): HTTP request configuration:
* **`url`** (required): The API endpoint URL (supports template variables)
* **`method`** (optional): HTTP method - `GET`, `POST`, `PUT`, `DELETE`, or `PATCH` (defaults to `GET`)
* **`headers`** (optional): Object with string key-value pairs for HTTP headers
* **`body`** (optional): Request body for POST/PUT/PATCH requests
* **`transform`** (optional): JSONPath expression or JavaScript transform function to extract specific data from the response
* **`timeout`** (optional): Request timeout in milliseconds (defaults to 10000)
* **`responseSchema`** (optional): Valid JSON Schema object to validate the API response structure.
* **`defaultValue`** (optional): Default value to use if the fetch fails or returns no data
* **`credential`** (optional): Reference to stored credentials for authentication
Here is an example of a valid Context Variables JSON object:
```json
{
"userInfo": {
"id": "user-info",
"name": "User Information",
"trigger": "initialization",
"fetchConfig": {
"url": "https://api.example.com/users/{{headers.user_id}}",
"method": "GET",
"headers": {
"Authorization": "Bearer {{headers.api_key}}"
},
"transform": "user"
},
"responseSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string"
}
},
},
"defaultValue": "Unable to fetch user information"
}
}
```
## Using Context Variables
Once you have defined your context variables, you can use them in your agent prompts.
1. Click on the agent you want to modify.
2. In the "Prompt" section, you can embed fetched data in the prompt using the key defined in the "Context Variables" section. Reference them using double curly braces `{{}}`.
Here is an example of an agent prompt using the context variable defined above:
```
You are a helpful assistant for {{userInfo.name}}.
```
# Related documentation
* [Headers](/visual-builder/headers) - Learn how to pass dynamic context to your agents via HTTP headers
# Headers
URL: /visual-builder/headers
Pass dynamic context to your agents via HTTP headers for personalized interactions
***
title: Headers
sidebarTitle: Headers
description: Pass dynamic context to your agents via HTTP headers for personalized interactions
icon: LuBoxes
keywords: headers, context fetchers, prompt variables, personalization
----------------------------------------------------------------------
## Overview
Headers allow you to pass request-specific values (like user IDs, authentication tokens, or organization metadata) to your agent at runtime via HTTP headers. These values are validated and made available throughout your agent system for:
* **Context Fetchers**: Dynamic data retrieval based on request values
* **External Tools**: Authentication and personalization for API calls
* **Agent Prompts**: Personalized responses using context variables
## Configuring Headers
1. Go to the Agents tab in the left sidebar. Then click on the agent you want to configure.
2. On the right pane scroll down to the "Headers schema" section.
3. Enter the schema in JSON Schema format.
4. Click on the "Save" button.
Here is an example of a valid headers schema:
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"userId": {
"type": "string"
}
},
"required": [
"userId"
],
"additionalProperties": {}
}
```
You can generate custom schemas using this [JSON Schema generator](https://transform.tools/json-to-json-schema).
## Sending Custom Headers
1. On your agent page, click on the **Try it** button in the top right corner.
2. Click on the "Custom headers" button in the top right corner.
3. Enter the custom headers in JSON format.
4. Click on the "Apply" button.
## Using Headers in Your Agent Prompts
1. Go to the Agents tab in the left sidebar. Then click on the agent you want to configure.
2. Either add a new agent or edit an existing agent by clicking on the agent you want to edit.
3. On the right pane scroll down to the "Prompt" section.
4. Use the double curly braces `{{}}` to reference the headers variables.
Here is an example of a valid prompt:
```text
You are a helpful assistant for {{headers.user_id}}!.
```
# Project Management
URL: /visual-builder/project-management
Learn how to create and manage projects in the Inkeep Agent Framework
***
title: Project Management
description: Learn how to create and manage projects in the Inkeep Agent Framework
icon: "LuFolder"
----------------
## Overview
Projects are the top-level organizational unit in the Inkeep Agent Framework. Each project contains its own agents, tools, and resources. This allows you to separate different applications or environments within a single tenant.
## Creating a Project
There are two ways to create a new project:
### Using the Project Dialog
When you have existing projects, you can create a new one using the "Create Project" button in the project switcher at the bottom of the sidebar.
### First Project Creation
If you don't have any projects yet, you'll be automatically redirected to the project creation page when you log in. You can also access it directly at `/{tenantId}/projects/new`.
## Project Fields
When creating a project, you'll need to provide:
* **Project ID**: A unique identifier for your project. This must:
* Start and end with lowercase alphanumeric characters
* May contain hyphens in the middle
* Cannot be changed after creation
* Examples: `my-project`, `production-v2`, `test-env1`
* **Project Name**: A friendly display name for your project (up to 100 characters)
* **Description**: A brief description of what the project is for (up to 500 characters)
## Project Structure
Each project can contain:
* **Agents**: Collections of AI agents that work together
* **API Keys**: Authentication keys for accessing your agents via API
* **MCP Servers**: Model Context Protocol servers for external tools
* **Data Components**: Reusable data structures for your agents
* **Artifact Components**: Reusable UI components for agent outputs
* **Credentials**: Secure storage for API keys and authentication tokens
## Project-Level Configuration
Projects can define default configurations that cascade down to all agents and Sub Agents within the project. This provides a consistent baseline while allowing specific overrides where needed.
### Model Settings
Define default models at the project level that all agents and Sub Agents will inherit:
```typescript
// Project configuration
{
id: "my-project",
name: "My AI Project",
models: {
base: {
model: "anthropic/claude-sonnet-4-5",
providerOptions: {
temperature: 0.7,
maxTokens: 4096
}
},
structuredOutput: {
model: "openai/gpt-4.1-mini",
providerOptions: {
temperature: 0.1,
maxTokens: 2048
}
},
summarizer: {
model: "openai/gpt-4.1-nano",
providerOptions: {
temperature: 0.3,
maxTokens: 1024
}
}
}
}
```
### StopWhen Configuration
Configure default stopping conditions to prevent infinite loops:
```typescript
{
id: "my-project",
stopWhen: {
transferCountIs: 5, // Max transfers between Sub Agents per conversation
stepCountIs: 20 // Max tool calls + LLM responses per Sub Agent execution
}
}
```
## Configuration Inheritance
The framework uses a cascading inheritance system with specific rules for different configuration types:
### Model Inheritance - Partial Cascading
**Project** → **Agent** → **Sub Agent**
The framework supports **partial cascading**, meaning each level can override specific model types while inheriting others. This provides maximum flexibility while maintaining sensible defaults.
#### How Partial Cascading Works
Each model type (`base`, `structuredOutput`, `summarizer`) cascades independently:
```typescript
// Project Level - Sets defaults for all agents
Project: {
models: {
base: { model: "anthropic/claude-sonnet-4-5" },
structuredOutput: { model: "openai/gpt-4.1-mini" },
summarizer: { model: "openai/gpt-4.1-nano" }
}
}
// Agent Level - Partially overrides project defaults
Agent: {
models: {
base: { model: "openai/gpt-4.1" } // Override: use different base model
// structuredOutput: INHERITED from project (openai/gpt-4.1-mini)
// summarizer: INHERITED from project (openai/gpt-4.1-nano)
}
}
// Sub Agent Level - Can override any inherited model
Sub Agent: {
models: {
summarizer: { model: "anthropic/claude-haiku-4-5" } // Override: use faster summarizer
// base: INHERITED from Agent (openai/gpt-4.1)
// structuredOutput: INHERITED from project (openai/gpt-4.1-nano)
}
}
```
#### Final Resolution Example
In the above example, the Sub Agent ends up with:
* **base**: `gpt-4.1` (from Agent)
* **structuredOutput**: `gpt-4.1-mini` (from project)
* **summarizer**: `claude-3.5-haiku` (from Sub Agent)
#### Provider Options Override
When a model is overridden at any level, the entire configuration (including provider options) is replaced:
```typescript
// Project defines base model with options
Project: {
models: {
base: {
model: "claude-sonnet-4-0",
providerOptions: {
temperature: 0.7,
maxTokens: 4096
}
}
}
}
// Agent completely overrides the base model settingsuration
Agent: {
models: {
base: {
model: "claude-sonnet-4-0", // Same model
providerOptions: {
temperature: 0.3, // New temperature
maxTokens: 2048 // New maxTokens - project maxTokens is NOT inherited
}
}
}
}
```
#### Fallback to Base Model
**Important**: `structuredOutput` and `summarizer` only fall back to the `base` model when there's nothing to inherit from higher levels (project/agent).
#### System Defaults
**Supported Providers**: The framework supports Anthropic, OpenAI, and Google models.
**API Keys**: You need the appropriate API key for the provider you choose to use:
* `ANTHROPIC_API_KEY` for Anthropic models
* `OPENAI_API_KEY` for OpenAI models
* `GOOGLE_GENERATIVE_AI_API_KEY` for Google models
```typescript
// No higher-level defaults - fallback to base occurs
Project: {
// No models configured
}
Agent: {
// No models configured
}
Sub Agent: {
models: {
base: {
model: "gpt-4.1-2025-04-14",
providerOptions: {
temperature: 0.7,
maxTokens: 2048
}
}
// No structuredOutput or summarizer specified
}
}
```
**Final Resolution with Fallback:**
* **base**: `gpt-4.1-2025-04-14` with specified provider options (from Agent)
* **structuredOutput**: `gpt-4.1-2025-04-14` with same provider options (falls back to Agent's base)
* **summarizer**: `gpt-4.1-2025-04-14` with same provider options (falls back to Agent's base)
**Contrast with Inheritance:**
```typescript
// Project has summarizer configured - inheritance takes priority
Project: {
models: {
summarizer: {
model: "gpt-4.1-mini";
}
}
}
Sub Agent: {
models: {
base: {
model: "gpt-4.1";
}
}
}
```
**Final Resolution with Inheritance:**
* **base**: `gpt-4.1` (from Sub Agent)
* **summarizer**: `gpt-4.1-mini` (inherited from project - NO fallback to Sub Agent's base)
* **structuredOutput**: Falls back to Sub Agent's base `gpt-4.1` (no inheritance available, so fallback occurs)
### StopWhen Inheritance
StopWhen settings inherit from Project → Agent → Sub Agent:
* **`transferCountIs`**: Project or Agent level
* **`stepCountIs`**: Project or Sub Agent level
```typescript
// Project sets defaults
Project: {
stopWhen: {
transferCountIs: 5, // Max transfers per conversation
stepCountIs: 15 // Max steps per Sub Agent
}
}
// Agent can override transfer limit, inherits step limit
Agent: {
stopWhen: {
transferCountIs: 8 // Override: allow more transfers in this Agent
// stepCountIs: 15 (inherited from project)
}
}
// Individual Sub Agent can override its own step limit
Sub Agent: {
stopWhen: {
stepCountIs: 25 // This Sub Agent can take more steps
// transferCountIs not applicable at Sub Agent level
}
}
```
## Switching Between Projects
Use the project switcher in the bottom left of the sidebar to quickly switch between projects. The switcher shows:
* The project name (or ID if no name is set)
* The project ID
* A brief description (if provided)
## API Access
Projects can be accessed programmatically via the CRUD API:
```typescript
// List all projects
GET /tenants/{tenantId}/crud/projects
// Get a specific project
GET /tenants/{tenantId}/crud/projects/{projectId}
// Create a new project
POST /tenants/{tenantId}/crud/projects
{
"id": "my-project",
"name": "My Project",
"description": "A project for my AI agents"
}
// Update a project
PATCH /tenants/{tenantId}/crud/projects/{projectId}
{
"name": "Updated Name",
"description": "Updated description"
}
// Delete a project
DELETE /tenants/{tenantId}/crud/projects/{projectId}
```
## Best Practices
1. **Use descriptive IDs**: Choose project IDs that clearly indicate their purpose (e.g., `customer-support`, `internal-tools`)
2. **Separate by environment**: Create different projects for development, staging, and production
3. **Document your projects**: Use the description field to explain what each project is for
4. **Organize by application**: Group related agents and tools within the same project
## Next Steps
After creating a project, you can:
* [Create your first Agent](/visual-builder/sub-agents)
* [Configure MCP servers for tools](/visual-builder/tools/mcp-servers)
* [Set up API keys for external access](/api-keys)
# Get started with the Visual Agent Builder
URL: /visual-builder/sub-agents
Create Agents with a No-Code Visual Agent Builder
***
title: Get started with the Visual Agent Builder
sidebarTitle: Agents & Sub Agents
description: Create Agents with a No-Code Visual Agent Builder
icon: "LuSpline"
----------------
## Overview
An Agent is the top-level entity you can chat and interact with in the Visual Builder.
An Agent is made up of one or more Sub Agents. The Sub Agents that make up an Agent can delegate or transfer control to each other, share context, or use tools to respond to a user or complete a task.
You can use the Visual Builder to add Sub Agents to an Agent, give Sub Agents tools, and connect Sub Agents with each other to establish their relationships.
## Creating your first Agent
1. Go to the Agents tab in the left sidebar. Then select "Create Agent".
2. Provide a name, prompt, and description.
### Agent Prompt
You can configure an Agent-level prompt that gets automatically added to all Sub Agents that make up the Agent. This provides consistent context and behavior guidelines so Sub Agents respond and act as one cohesive unit.
**Example uses:**
* Company-wide policies and tone guidelines
* Domain-specific context that applies to all sub-agents
* Consistent behavior rules across the sub-agent network
Once an Agent is created, you can always edit the prompt by:
1. Clicking on the **Agent Settings** button next to **Try it**
2. Modify your prompt in the "Agent Prompt" field
3. Click **Save**
## Default Sub Agent
When you create an Agent, it'll have a **Default Sub Agent** by default. This is the Sub Agent that first receives and processes a user message.
Configure its name and prompt, then click **Save**.
## Trying the Agent
To try the Agent, ensure it has at least one Sub Agent, then save the Agent by clicking the "Save changes" button in the top right corner.
Then, click the **Try it** button in the top right corner and type into the chat input.
## Adding tools
Tools are used to perform actions in the Agent. You can register MCP tools in the Visual Builder. See the [MCP Servers](/visual-builder/tools/mcp-servers) page to get started.
Once you have an MCP Server registered, you can add it to a Sub Agent by dragging and dropping the **MCP** block from the top left onto the Canvas.
To connect the tool to the Sub Agent, click the "+" icon at the top of the MCP block, then drag the connector to the Sub Agent. A line will appear, indicating that the tool is connected to the Sub Agent.
# Set up live traces
### Step 1: Launch docker containers
```bash
cd deploy/docker
docker compose up -d
```
### Step 2: Fetch SigNoz API Key
Open `http://localhost:3080` in the browser. Go to **Settings** → **Workspace Settings** → **API Keys** and copy the API key.
### Step 3: Configure environment variable
Create a `.env` file at `/agents-manage-ui/` with the following variable:
```
SIGNOZ_API_KEY=your-signoz-api-key-here
```
### Step 4: View your live traces
Refresh the live traces panel on the right to see your agents in action.
# Set up credentials
### Step 1: Create .env file and generate encryption key
```bash
cp deploy/docker/.env.nango.example deploy/docker/.env && encryption_key=$(openssl rand -base64 32) && sed -i '' "s|REPLACE_WITH_BASE64_256BIT_ENCRYPTION_KEY|$encryption_key|" deploy/docker/.env && echo "Docker environment file created with auto-generated encryption key"
```
### Step 2: Restart the containers
```bash
cd deploy/docker
docker compose up -d
```
### Step 3: Get your Nango API key
Open the Nango Dashboard: `http://localhost:3050` and navigate to **Environment Settings** → **API Keys** and copy the API key.
### Step 4: Configure environment variables
Navigate back to the root directory and paste the below command. Enter your Nango API key when prompted:
```bash
cd ../../
printf "Enter your Nango API key: " && read key && sed -i '' "s|^NANGO_SECRET_KEY=.*|NANGO_SECRET_KEY=$key|" agents-manage-api/.env agents-run-api/.env agents-manage-ui/.env && echo "Application files updated with Nango API key"
```
### Step 5: Start creating credentials!
Navigate to the Credentials tab in the left sidebar and click "Create credential".
# Development Workflow
### Git Hooks
This project uses Husky for Git hooks to maintain code quality. The hooks are automatically installed when you run `pnpm install`.
#### Pre-commit Hook
The pre-commit hook runs the following checks before allowing a commit:
1. **Type checking** - Ensures type safety across all packages
2. **Tests** - Runs the test suite
##### Bypassing Checks
While we recommend running all checks, there are legitimate cases where you might need to bypass them:
**Skip typecheck only (tests still run):**
```bash
SKIP_TYPECHECK=1 git commit -m "WIP: debugging issue"
```
**Skip all hooks (use sparingly):**
```bash
git commit --no-verify -m "emergency: hotfix for production"
```
> **Note:** Use these bypass mechanisms sparingly. They're intended for:
>
> * Work-in-progress commits that you'll fix before pushing
> * Emergency fixes where speed is critical
> * Commits that only touch non-code files (though hooks are smart enough to handle this)
### Code Quality
#### Type Checking
Run type checking across all packages:
```bash
pnpm typecheck
```
#### Linting
Run the linter:
```bash
pnpm lint
```
Format code automatically:
```bash
pnpm format
```
#### Testing
Run tests:
```bash
pnpm test # Run all tests
pnpm test:watch # Run tests in watch mode
pnpm test:coverage # Run tests with coverage report
```
### Building
Build all packages:
```bash
pnpm build
```
# CLI Development
## Running the CLI Locally
When developing the CLI, you can run the local version directly without global installation:
```bash
# Build the CLI first
cd agents-cli
pnpm build
# Run the local CLI from the repository root
node agents-cli/dist/index.js --version
# Or use the convenience script (if available)
./scripts/inkeep-local.sh --version
```
## Testing CLI Changes
1. **Build the CLI after making changes:**
```bash
cd agents-cli
pnpm build
```
2. **Test commands locally:**
```bash
# From repository root
node agents-cli/dist/index.js push examples/agent-configurations
node agents-cli/dist/index.js chat
```
3. **Run CLI tests:**
```bash
cd agents-cli
pnpm test
```
## Switching Between Local and Published CLI
During development, you may need to test both the local development version and the published npm package:
```bash
# Use local development version
node /path/to/agents/agents-cli/dist/index.js --version
# Use globally installed published version
inkeep --version
```
For detailed information about switching between versions, see the `INKEEP_CLI_SWITCHING.md` file in the repository root.
# Commit Messages
We follow conventional commit format:
```
type(scope): description
[optional body]
[optional footer]
```
Types:
* `feat`: New feature
* `fix`: Bug fix
* `docs`: Documentation changes
* `style`: Code style changes (formatting, etc.)
* `refactor`: Code refactoring
* `test`: Test changes
* `chore`: Build process or auxiliary tool changes
# Pull Requests
1. Fork the repository
2. Create a feature branch (`git checkout -b feat/amazing-feature`)
3. Make your changes
4. Ensure all checks pass (`pnpm typecheck && pnpm test`)
5. Commit your changes (following commit message guidelines)
6. Push to your fork
7. Open a pull request
### PR Guidelines
* Keep PRs focused on a single feature or fix
* Update tests for any behavior changes
* Update documentation as needed
* Ensure CI passes before requesting review
# Continuous Integration
Our CI pipeline runs on all pull requests and includes:
* Type checking (`pnpm typecheck`)
* Tests (`pnpm test`)
* Build verification (`pnpm build`)
These checks must pass before a PR can be merged. The same checks run in pre-commit hooks to catch issues early.
# Questions?
If you have questions about contributing, please:
1. Check existing issues and discussions
2. Open a new issue if your question isn't addressed
3. Reach out to the maintainers
Thank you for contributing!
# Data Layer constraints on Project relationships
URL: /community/contributing/project-constraints
How the Inkeep Agent Framework ensures data integrity with project constraints
***
title: Data Layer constraints on Project relationships
sidebarTitle: Project Data Layer
description: How the Inkeep Agent Framework ensures data integrity with project constraints
icon: "LuTriangleAlert"
-----------------------
# Project Constraints and Validation
The Inkeep Agent Framework implements multiple layers of validation to ensure that all agents and resources are associated with valid projects.
## Database-Level Constraints
### Foreign Key Constraints
All tables that reference projects include foreign key constraints to ensure referential integrity:
```sql
FOREIGN KEY (tenant_id, project_id)
REFERENCES projects(tenant_id, id)
ON DELETE CASCADE
```
This ensures that:
* No data can be inserted for non-existent projects
* Deleting a project cascades to remove all associated resources
* Data integrity is maintained at the database level
### Tables with Project Constraints
The following tables have foreign key constraints to the `projects` table:
1. `agent` - Agent definitions (top-level Agents)
2. `sub_agents` - Sub Agent configurations
3. `sub_agent_relations` - Relationships between Sub Agents
4. `tools` - Tool configurations
5. `context_configs` - Context configurations
6. `external_agents` - External agent references
7. `conversations` - Chat conversations
8. `messages` - Chat messages
9. `tasks` - Task records
10. And more...
## Runtime Validation
### CLI Validation
The Inkeep CLI validates project existence before pushing agents:
```typescript
// CLI checks if project exists
const existingProject = await getProject(dbClient)({
scopes: { tenantId, projectId },
});
if (!existingProject) {
// Prompt user to create project
// ...
}
```
### Data Access Layer Validation
The core package provides validation utilities for runtime checks:
```typescript
import { validateProjectExists } from "@inkeep/agents-core";
// Validate before any operation
await validateProjectExists(db, tenantId, projectId);
```
### Wrapped Operations
Data access functions can be wrapped with automatic validation:
```typescript
import { withProjectValidation } from "@inkeep/agents-core";
const validatedCreateAgent = withProjectValidation(db, createAgent);
// Now automatically validates project before creating agent
```
## Implementation Details
### Schema Definition
```typescript
export const agents = sqliteTable(
"agent",
{
tenantId: text("tenant_id").notNull(),
projectId: text("project_id").notNull(),
// ... other columns
},
(table) => [
primaryKey({ columns: [table.tenantId, table.projectId, table.id] }),
foreignKey({
columns: [table.tenantId, table.projectId],
foreignColumns: [projects.tenantId, projects.id],
name: "agent_project_fk",
}),
]
);
```
### Enabling Foreign Keys in SQLite
SQLite requires explicit enabling of foreign key constraints:
```sql
PRAGMA foreign_keys = ON;
```
This should be set when creating the database connection:
```typescript
const client = createClient({
url: dbUrl,
authToken: authToken,
});
// Enable foreign keys
await client.execute("PRAGMA foreign_keys = ON");
```
## Error Handling
When a constraint violation occurs, appropriate error messages guide users:
### CLI Error
```
⚠ Project "my-project" does not exist
? Would you like to create it? (Y/n)
```
### Database Error
```
Error: Project with ID "my-project" does not exist for tenant "my-tenant".
Please create the project first before adding resources to it.
```
## Best Practices
1. **Always validate at multiple levels**: Database constraints, runtime validation, and UI validation
2. **Provide clear error messages**: Help users understand what went wrong and how to fix it
3. **Offer solutions**: When a project doesn't exist, offer to create it
4. **Use transactions**: Ensure atomicity when creating projects and related resources
5. **Test constraints**: Verify that constraints work as expected in tests
## Migration Guide
For existing databases without constraints:
1. **Backup your database** before applying migrations
2. **Check for orphaned data**: Find resources referencing non-existent projects
3. **Clean up orphaned data** or create missing projects
4. **Apply foreign key constraints** using migrations
5. **Enable foreign key enforcement** in your database connection
```sql
-- Find orphaned agents
SELECT a.* FROM agent a
LEFT JOIN projects p
ON a.tenant_id = p.tenant_id
AND a.project_id = p.id
WHERE p.id IS NULL;
```
## Benefits
* **Data Integrity**: Prevents orphaned data and maintains consistency
* **Clear User Experience**: Users are guided to create projects when needed
* **Easier Debugging**: Constraint violations are caught early
* **Simplified Cleanup**: Cascading deletes remove all related data
* **Better Documentation**: Constraints document relationships in the schema
# Spans and Traces
URL: /community/contributing/spans
OpenTelemetry spans for distributed tracing and observability in the Inkeep Agent Framework
***
title: Spans and Traces
description: OpenTelemetry spans for distributed tracing and observability in the Inkeep Agent Framework
icon: "LuBug"
-------------
## Overview
The Inkeep Agent Framework uses OpenTelemetry for distributed tracing and observability. Spans provide detailed visibility into the execution flow of agents, context resolution, tool execution, and other framework operations.
## Getting Started with Spans
### 1. Import Required Dependencies
```typescript
import { SpanStatusCode, type Span } from "@opentelemetry/api";
import { getTracer, setSpanWithError } from "../tracer";
```
### 2. Get the Tracer
```typescript
// Use the centralized tracer utility
const tracer = getTracer("your-service-name");
```
## Creating and Using Spans
```typescript
return tracer.startActiveSpan(
"context.resolve",
{
attributes: {
"context.config_id": contextConfig.id,
"context.trigger_event": options.triggerEvent,
},
},
async (span: Span) => {
try {
// Your operation logic here
return result;
} catch (error) {
// Use setSpanWithError for consistent error handling
setSpanWithError(span, error);
throw error;
}
}
);
```
## Setting Span Attributes
### Basic Attributes
```typescript
span.setAttributes({
"user.id": userId,
"request.method": "POST",
});
```
## Adding Events to Spans
### Recording Important Milestones
```typescript
// Add events for significant operations
span.addEvent("context.fetch_started", {
definitionId: definition.id,
url: definition.fetchConfig.url,
});
```
### Error Events
```typescript
span.addEvent("error.validation_failed", {
definitionId: definition.id,
error_type: "json_schema_validation",
error_details: errorMessage,
});
```
## Error Handling and Status
### Using setSpanWithError Utility
The framework provides a convenient `setSpanWithError` utility function that handles error recording and status setting:
```typescript
try {
// Your operation
} catch (error) {
// Use the setSpanWithError utility for consistent error handling
setSpanWithError(span, error);
throw error;
}
```
## Best Practices
### 1. Consistent Naming Convention
The span naming convention follows a hierarchical structure that mirrors your code organization.
```typescript
// Format: 'class.function'
// Use descriptive span names that follow a hierarchical structure
// Agent operations
"agent.generate";
"agent.tool_execute";
"agent.transfer";
// Context operations
"context.resolve";
"context.fetch";
```
#### Naming Rules
1. **Class First**: Start with the class/module name (e.g., `agent`, `context`, `tool`)
2. **Function Second**: Follow with the specific function/method (e.g., `generate`, `resolve`)
3. **Use Underscores**: For multi-word functions, use underscores (e.g., `tool_execute`, `cache_lookup`)
4. **Consistent Casing**: Use lowercase with underscores for consistency
## Configuration and Setup
### Environment Variables
```bash
# OpenTelemetry configuration
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317
```
### Instrumentation Setup
The framework automatically sets up OpenTelemetry instrumentation in `src/instrumentation.ts`:
## Examples in the Codebase
### Agent Operations
See `src/agents/Agent.ts` for span usage in agent generation and tool execution.
**Example from Agent.ts:**
```typescript
// Class: Agent
// Function: generate
return tracer.startActiveSpan(
"agent.generate",
{
attributes: {
"agent.id": this.id,
"agent.name": this.name,
},
},
async (span: Span) => {
// ... implementation
}
);
```
## Summary
Spans provide powerful observability into your Inkeep Agent Framework operations. By following these patterns:
1. **Use `getTracer()`** for consistent tracing
2. **Use consistent naming**
3. **Set meaningful attributes** for searchability
4. **Handle errors properly** using `setSpanWithError` for consistent error handling
5. **Use `startActiveSpan`** for automatic lifecycle management
This will give you comprehensive visibility into your agent operations, making debugging and performance optimization much easier.
# Exa
URL: /connecting-your-data/3rd-party-tools/exa
Exa is a data scraping tool that allows you to scrape data from websites.
***
title: Exa
description: Exa is a data scraping tool that allows you to scrape data from websites.
--------------------------------------------------------------------------------------
Exa is a data scraping tool that allows you to scrape data from websites.
## Using as a custom tool
Install the [exa-js](https://github.com/exa-labs/exa-js) SDK
```typescript
import Exa from 'exa-js';
import { agent, subAgent } from "@inkeep/agents-sdk";
const exaAgent = subAgent({
id: 'exa-agent',
tenantId,
name: 'exa',
description:
'This agent is used to search and retrieve information from the web using Exa',
prompt: 'Use the tools at your disposal to search and retrieve information from the web.',
tools: {
web_search_exa: tool({
name: 'web_search_exa',
description: 'Search the web and retrieve relevant results with optional content and highlights',
parameters: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'The search query string'
},
numResults: {
type: 'number',
description: 'Number of search results to return (default: 10)',
optional: true
},
includeDomains: {
type: 'array',
items: { type: 'string' },
description: 'List of domains to include in the search',
optional: true
},
excludeDomains: {
type: 'array',
items: { type: 'string' },
description: 'List of domains to exclude from the search',
optional: true
},
includeContent: {
type: 'boolean',
description: 'Whether to include the full text content of results',
optional: true
},
includeHighlights: {
type: 'boolean',
description: 'Whether to include relevant highlights from the content',
optional: true
}
},
required: ['query']
},
execute: async ({ query, numResults = 10, includeDomains, excludeDomains, includeContent = false, includeHighlights = false }) => {
try {
const exa = new Exa(process.env.EXA_API_KEY);
if (includeContent || includeHighlights) {
const results = await exa.searchAndContents(query, {
numResults,
includeDomains,
excludeDomains,
text: includeContent,
highlights: includeHighlights
});
return results;
} else {
const results = await exa.search(query, {
numResults,
includeDomains,
excludeDomains
});
return results;
}
} catch (error) {
console.error('Error executing Exa search:', error);
throw new Error(`Failed to execute Exa search: ${error.message}`);
}
}
})
}
});
```
## Using as an MCP tool
Get your API key
Before you begin, you’ll need an Exa API key: [https://dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
Connect directly to Exa’s hosted MCP server using this URL:
[https://mcp.exa.ai/mcp?exaApiKey=your-exa-api-key](https://mcp.exa.ai/mcp?exaApiKey=your-exa-api-key)
```typescript
import { mcpTool } from "@inkeep/agents-sdk";
const exaTool = mcpTool({
id: "exa-tool",
name: "exa",
description: "Exa MCP tool for data scraping",
serverUrl: "https://mcp.exa.ai/mcp?exaApiKey=your-exa-api-key"
});
```
This will give you access to the following tools:
web\_search\_exa
company\_research\_exa
crawling\_exa
linkedin\_search\_exa
deep\_researcher\_start
deep\_researcher\_check
# Datadog
URL: /self-hosting/add-other-services/datadog-apm
Add Datadog APM to your Inkeep Agent Framework services
***
title: Datadog
sidebarTitle: Add Datadog
description: Add Datadog APM to your Inkeep Agent Framework services
icon: "brand/DatadogIcon"
keywords: Datadog, monitoring, distributed tracing
--------------------------------------------------
## Overview
Learn how to add Datadog APM to your Inkeep Agent Framework services.
## Step 1: Install Datadog APM
From the root of your workspace, run the following command:
```bash
pnpm install dd-trace
```
## Step 2: Set up tracer.ts
In `apps/run-api` and `apps/manage-api` create a new file called `tracer.ts` and add the following code:
```typescript
import tracer from "dd-trace";
tracer.init(); // initialized in a different file to avoid hoisting.
export default tracer;
```
In `apps/run-api/src/index.ts` and `apps/manage-api/src/index.ts` add the following code to the top of the file before all other imports:
```typescript
import "./tracer";
```
## Additional Resources
For more information on how to configure APM, you can consult the official Datadog Node.js [documentation](https://app.datadoghq.com/apm/service-setup?architecture=host-based\&framework=typescript\&language=node\&product=apm).
# Sentry
URL: /self-hosting/add-other-services/sentry
Add Sentry monitoring to your agent services
***
title: Sentry
sidebarTitle: Add Sentry
description: Add Sentry monitoring to your agent services
icon: "brand/SentryIcon"
keywords: Sentry, error tracking, monitoring, distributed tracing
-----------------------------------------------------------------
## Overview
Learn how to add Sentry monitoring to your Inkeep Agent Framework services.
## Step 1: Install Sentry
```bash
pnpm install @sentry/node
```
## Step 2: Update your `.env` file
Add your Sentry DSN to the `.env` file in the root of your workspace.
```bash
SENTRY_DSN=https://Try asking:
Try asking:
## Example Flow
Here's a complete example with inline artifact component definition:
```typescript
import { agent } from '@inkeep/agents-sdk';
import { z } from 'zod';
import { preview } from '@inkeep/agents-core';
const searchAgent = subAgent({
id: "search",
canUse: () => [searchTool],
prompt: "Search for information and cite sources using artifacts.",
artifactComponents: [
{
id: "citation",
name: "citation",
description: "Search result document",
props: z.object({
title: preview(z.string().describe("Document title")),
url: preview(z.string().describe("Document URL")),
content: z.string().describe("Document content"),
}),
},
],
});
```
## No Schema Example
```typescript
const rawDataAgent = subAgent({
id: "raw-data",
canUse: () => [apiTool],
prompt: "Fetch data and save complete responses.",
artifactComponents: [
{
id: "api-response",
name: "API Response",
description: "Complete API response data",
// No props - saves entire tool result
},
],
});
```
Example flow:
1. Agent uses search tool and gets results
2. **Agent decides** to create an artifact citing the source document
3. Artifact is stored with preview fields (title, url) shown to other agents
4. Other agents can reference this artifact or get full content when needed
# Create Rich UI Blocks with Data Components
URL: /typescript-sdk/structured-outputs/data-components
Learn how to create and use data components for rich, interactive Agent messages.
***
title: Create Rich UI Blocks with Data Components
sidebarTitle: Custom UI Blocks
description: Learn how to create and use data components for rich, interactive Agent messages.
icon: "LuBlocks"
----------------
<>
## What are Data Components?
Data Components allow your agents to return rich, interactive content instead of just text. Think of them as reusable UI building blocks that your agent can populate with data.
For example, instead of returning "You have 3 tasks: Task #123 (shipped), Task #124 (processing)...", your agent can return a properly formatted task list component.
## Defining Data Components
Data components are defined using the `dataComponent` builder function. **We recommend using Zod schemas** for type safety and better developer experience.
```typescript
import { dataComponent } from '@inkeep/agents-sdk';
import { z } from 'zod';
export const taskList = dataComponent({
id: "task-list",
name: "TaskList",
description: "Display user tasks with status",
props: z.object({
tasks: z
.array(
z.object({
id: z.string().describe("Unique task identifier"),
title: z.string().describe("Task title"),
completed: z.boolean().describe("Whether the task is completed"),
priority: z.enum(["low", "medium", "high"]).describe("Task priority"),
})
)
.describe("Array of user tasks"),
totalCount: z.number().describe("Total number of tasks"),
completedCount: z.number().describe("Number of completed tasks"),
}),
});
```
## Artifact Name & Description Generation
**Important**: Artifact names and descriptions are automatically generated at the **agent level** using that specific agent's configured **summarizer model**.
### How It Works
When an agent creates an artifact during tool execution or data processing:
1. **Agent Creates Artifact**: During tool execution or data processing
2. **Summarizer Analysis**: The agent's summarizer model analyzes:
* The artifact content and structure
* Recent conversation context
* The user's original question or request
3. **Name Generation**: Creates a concise, descriptive name (max 50 characters)
4. **Description Generation**: Provides context about relevance and content (max 150 characters)
### Model Settings for Artifacts
Each agent uses its configured summarizer model for artifact generation:
```typescript
// Agent with custom summarizer for artifact generation
const researchAgent = subAgent({
id: "research-agent",
name: "Research Agent",
prompt: "You are a research agent that can generate artifact names and descriptions",
models: {
base: { model: "claude-sonnet-4-0" },
summarizer: {
model: "gpt-4.1-mini", // This model generates artifact names/descriptions
providerOptions: {
temperature: 0.2, // Lower temperature for consistent naming
maxTokens: 512,
},
},
},
});
```
### Inheritance and Fallback
Artifact generation follows the same model inheritance rules:
* **Default**: Sub Agent uses the Agent's summarizer model (if configured)
* **Fallback**: If no summarizer configured at project/agent level, falls back to Sub Agent's base model
* **Override**: Agent can specify its own summarizer model
### Best Practices
* **Consistent Models**: Use the same summarizer model across related agents for consistent artifact naming
* **Appropriate Models**: Choose models good at summarization (GPT-4o-mini, claude-3.5-haiku work well)
* **Temperature Settings**: Lower temperatures (0.1-0.3) provide more consistent naming patterns
# Create Rich UI Blocks with Data Components
URL: /visual-builder/structured-outputs/data-components
Learn how to create and use data components for rich, interactive Agent messages.
***
title: Create Rich UI Blocks with Data Components
sidebarTitle: Custom UI Blocks
description: Learn how to create and use data components for rich, interactive Agent messages.
icon: "LuBlocks"
----------------
<>
## What are Data Components?
Data Components allow your agents to return rich, interactive content instead of just text. Think of them as reusable UI building blocks that your agent can populate with data.
For example, instead of returning "You have 3 tasks: Task #123 (shipped), Task #124 (processing)...", your agent can return a properly formatted task list component.
## How to create a data component
1. Go to the Data Components tab in the left sidebar. Then select "New data component".
2. Add in an id, name, and description. These are required fields.
3. Enter a JSON schema defining the structure of your data component.
4. Click "Submit".
To visually add the data component to the Agent, see the [Sub Agents](/visual-builder/sub-agents#adding-data-components) page for details.
### Example JSON Schema
```json
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"description": "Array of user tasks",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "description": "Task ID" },
"title": { "type": "string", "description": "Task title" },
"completed": { "type": "boolean", "description": "Task status" }
}
}
},
"totalCount": { "type": "number", "description": "Total tasks" }
}
}
```
## Frontend Integration
Create a React component matching your data component name:
```tsx
const TaskList = ({ tasks, totalCount }) => (
### Function Code
Write your JavaScript function in the Code editor. The function receives arguments based on your Input Schema and should return a result:
```javascript
// Example: BMI calculator
function calculateBMI({ weight, height }) {
const bmi = weight / (height * height);
let category = "Normal";
if (bmi < 18.5) category = "Underweight";
else if (bmi >= 30) category = "Obese";
return { bmi: Math.round(bmi * 10) / 10, category };
}
return calculateBMI(args);
```
## Authentication setup
If your MCP server requires authentication, you have two options: either use the **"Click to Login"** button to authenticate or manually create a credential to use with the MCP server.
### OAuth 2.1/PKCE authentication
1. Create your MCP server without selecting a credential
2. Go to the server details page and click the **"Click to Login"** button
3. Complete the OAuth authentication flow in your browser
4. The credential will be automatically created and saved to your [Nango Store](/typescript-sdk/tools/credentials#nango-store) (follow steps to [setup Nango](/get-started/credentials)). If Nango is not set up, the framework will use the [Keychain Store](/typescript-sdk/tools/credentials#keychain-store) if available.
#### 1-click Install MCP servers
<>
Here's an example list of popular service-maintained MCP Servers that support **1-click** install via the OAuth 2.1/PKCE authentication flow.
| Name | URL |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Atlassian (SSE)](https://support.atlassian.com/rovo/docs/getting-started-with-the-atlassian-remote-mcp-server/) | [https://mcp.atlassian.com/v1/sse](https://mcp.atlassian.com/v1/sse) |
| [Canva](https://www.canva.dev/docs/connect/canva-mcp-server-setup/) | [https://mcp.canva.com/mcp](https://mcp.canva.com/mcp) |
| [Hugging Face](https://huggingface.co/mcp) | [https://huggingface.co/mcp?login](https://huggingface.co/mcp?login) |
| [Intercom](https://developers.intercom.com/docs/guides/mcp) | [https://mcp.intercom.com/mcp](https://mcp.intercom.com/mcp) |
| [Linear](https://linear.app/docs/mcp) | [https://mcp.linear.app/mcp](https://mcp.linear.app/mcp) |
| [Neon](https://neon.com/docs/ai/neon-mcp-server) | [https://mcp.neon.tech/mcp](https://mcp.neon.tech/mcp) |
| [Notion](https://developers.notion.com/docs/get-started-with-mcp) | [https://mcp.notion.com/mcp](https://mcp.notion.com/mcp) |
| [Prisma](https://www.prisma.io/docs/postgres/integrations/mcp-server#remote-mcp-server) | [https://mcp.prisma.io/mcp](https://mcp.prisma.io/mcp) |
| [Sentry](https://docs.sentry.io/product/sentry-mcp/) | [https://mcp.sentry.dev/mcp](https://mcp.sentry.dev/mcp) |
| [Vercel](https://vercel.com/docs/mcp/vercel-mcp) | [https://mcp.vercel.com](https://mcp.vercel.com) |
To add them to your project:
1. navigate to **MCP Servers** in the Inkeep Visual Builder.
2. Click on **New MCP Server**
3. Choose from the preset list under **Popular Services** or register any under **Custom Server**
When you register the server, an authentication pop-up will appear and allow you to sign in. Your credentials will automatically be saved to your [Nango Store](/typescript-sdk/tools/credentials#nango-store) or [Keychain](/typescript-sdk/tools/credentials#keychain-store) credential store.
### Manual credential setup
1. Create a credential in the [Credentials](/visual-builder/tools/credentials) section. The credential can be API Key, Bearer Token, Basic, OAuth 2.0, etc.
2. When creating or editing your MCP server, select the credential from the dropdown
3. The credential will be automatically used when connecting to the server
## Finding more remote MCP servers
For additional remote MCP servers you can connect to:
* **[Anthropic's Remote MCP Servers](https://docs.anthropic.com/en/docs/agents-and-tools/remote-mcp-servers)** - Official documentation with curated third-party remote servers
* **[Awesome Remote MCP Servers](https://github.com/jaw9c/awesome-remote-mcp-servers)** - Community-curated list of high-quality remote MCP servers
## Using stdio-based MCP servers
The Visual Builder requires **Streamable HTTP or SSE transport** to connect to MCP servers. If you have an MCP server that runs in **stdio mode** locally, you can use the following setup to connect to it.
### Setup outline
1. **Deploy your stdio -> Streamable HTTP/SSE bridge** (locally or cloud)
2. **Set environment variables** (API tokens, etc.)
3. **Verify it's running** (i.e. on port `4000`, `4001`, etc.)
4. **Add to Visual Builder**:
* **URL**: `http://localhost:4000/mcp` (or your server URL)
* **Transport Type**: `Streamable HTTP` or `SSE`
### Example using `mcp-proxy`
1. Get familiar with [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) - proxy for MCP servers that use stdio transport
2. [Supabase MCP server](https://github.com/supabase-community/supabase-mcp)
3. Run the server locally:
```bash
SUPABASE_ACCESS_TOKEN=YOUR_SUPABASE_ACCESS_TOKEN mcp-proxy --port 4444 --shell "npx -y @supabase/mcp-server-supabase@latest --read-only"
```
4. Add to Visual Builder with the following settings:
* **URL**: `http://localhost:4444/mcp`
* **Transport Type**: `Streamable HTTP`
## Adding servers to agents
Once you have created an MCP server, you can add it to your agents:
1. Go to the [Sub Agents](/visual-builder/sub-agents) page
2. Drag and drop an MCP server into your agent
3. Connect the MCP server to a Sub Agent by dragging from the server's connector to the Sub Agent
4. Your Sub Agent can now use the tools provided by that MCP server
For detailed instructions on working with MCP servers in agents, see the [Sub Agents](/visual-builder/sub-agents#adding-tools) page.