* The `service-info` tab displays the health of each running service.
* The `manage-api` tab contains logs for all database operations. This is useful primarily for debugging issues with [`inkeep push`](/typescript-sdk/cli-reference#inkeep-push).
* The `run-api` tab contains logs for all agent execution and tool calls. This is useful for debugging issues with your agent's behavior.
* The `mcp` tab contains logs for your [custom MCP servers](/guides/mcp-servers/custom-mcp-servers).
* The `dashboard` tab displays logs for the [Visual Builder](/visual-builder/sub-agents) dashboard.
To terminate the running services, click press `q` or `esc` in the terminal.
## CLI Issues
### Login fails or browser shows "connection refused"
* Verify the dashboard is running (`inkeep dev` or check Docker services)
* Check the manage UI URL in your profile: `inkeep profile current`
* Common cause: profile has a wrong port — re-create with `inkeep profile add`
### "Device code expired" during login
This usually means the manage UI was unreachable when you tried to approve the device code.
* Check: `inkeep profile current` — verify the **Manage UI** URL is correct and accessible in your browser
* For local development, the default manage UI runs on `http://localhost:3000`
### Push fails with authentication errors
* Ensure you've logged in for the active profile: `inkeep login`
* Local profiles with `credential: none` don't require login — the local server accepts unauthenticated requests
* Check which profile is active: `inkeep profile current`
## Authentication Issues (Local Development)
If auto-login isn't working when you open `http://localhost:3000`:
* **You recently logged out**: After clicking "Log out", a `dev-logged-out` cookie prevents auto-login so you can test login flows. To restore auto-login, clear your cookies or restart your browser.
* **`pnpm db:auth:init` not run**: The admin user must exist in the database. Run `pnpm db:auth:init` to create it.
* **API not running**: The auto-login proxy calls `POST /api/auth/dev-session` on the API server. Make sure the API is running on `localhost:3002`.
* **Bypass secret missing from `.env`**: Ensure `INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET` is set in your `.env` file. The proxy uses this to authenticate with the API. Check the server console for `[proxy]` warnings.
* **Credentials missing from `.env`**: Ensure `INKEEP_AGENTS_MANAGE_UI_USERNAME` is set in your `.env` file. The password env var is only used by `pnpm db:auth:init` to create the admin user, not for auto-login.
## 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
## Error Retry Behavior
When calling agents the system automatically retries certain errors using exponential backoff.
The following errors are automatically retried:
| Status Code | Meaning |
| ----------- | -------------------------------- |
| `429` | Too Many Requests (rate limited) |
| `500` | Internal Server Error |
| `502` | Bad Gateway |
| `503` | Service Unavailable |
| `504` | Gateway Timeout |
These transient network issues are also automatically retried:
* Network connectivity failures
* Connection timeouts
* `ECONNRESET` — Connection reset by peer
* `ECONNREFUSED` — Connection refused (network level)
* `ENOTFOUND` — DNS lookup failures
* Fetch/request failures
# Inkeep API (/api-reference)
Explore the Inkeep Agents API endpoints for managing, running, and evaluating agents.
import { source } from '@/lib/source';
-
file_name: The name of the file containing the snippet -
pages: The page numbers where the snippet appears (for PDFs and DOCX files) -
content: The actual text content of the snippet
-
file_name: The name of the file containing the snippet -
pages: The page numbers where the snippet appears (for PDFs and DOCX files) -
content: The actual text content of the snippet
- This occurs when you're not in a Vercel environment or you don't provide a Vercel access token
- Solution: Use a Vercel access token from vercel.com/account/tokens
-
Increase the
timeoutvalue in sandbox configuration -
Consider allocating more
vcpusfor resource-intensive functions - Check Vercel Sandbox limits for your plan
- Ensure dependencies are compatible with Node.js 22
- Check that package versions are specified correctly
- Verify network access to npm registry
-
Reduce
vcpusallocation if functions don't need maximum resources - Optimize function code to execute faster
- Consider caching results when possible
- Use environment variables – Never hardcode credentials
- Start with fewer vCPUs – Scale up only if needed
- Set reasonable timeouts – Prevent runaway executions
- Monitor usage – Track sandbox execution metrics in Vercel dashboard
- Test thoroughly – Verify functions work in sandbox environment before deploying
- Choose the right provider – Use native for VMs/Docker/K8s, Vercel Sandbox for serverless only
For more information on function tools, see:
-
Ensure the workflow file exists at
.github/workflows/deployment-health-check.yml - Verify the workflow is enabled in your repository's Actions settings
- Verify your project is connected to GitHub via Vercel for GitHub
- Ensure the check is selected in Project Settings > Deployment Checks
-
The
/readyendpoint checks database connectivity - Ensure database connection strings are correct in the deployment
- Check database accessibility from the Vercel deployment region
- Increase the cold start wait time if needed
- Use Force Promote from the deployment details page in Vercel
### Next steps
* Set up [AI coding for Inkeep](https://docs.inkeep.com/get-started/ai-coding-setup-for-ide) with skills and MCP.
* Learn about [inkeep push / pull](https://docs.inkeep.com/get-started/push-pull) so you can go from `SDK -> Visual Builder` and `Visual Builder -> SDK`.
* Follow our [meeting prep agent tutorial](https://docs.inkeep.com/tutorials/agents/meeting-prep-assistant) to create an agent using the Visual Builder.
* Follow our [fact finder agent tutorial](https://docs.inkeep.com/tutorials/agents/fact-finder) to create an agent using the TypeScript SDK.
# Live Debugger, Traces, and OTEL Telemetry (/get-started/traces)
Set up SigNoz to enable full observability with traces and live debugging capabilities for your agents.
## Overview
The Inkeep Agent Framework provides powerful **traces** and **live debugging** capabilities powered by SigNoz. Setting up SigNoz gives you:
* **Real-time trace visualization** - See exactly how your agents execute step-by-step
* **Live debugging** - Debug agent conversations as they happen
* **Export traces as JSON** - Copy complete traces for offline analysis and debugging
* **Full observability** - Complete OpenTelemetry instrumentation for monitoring
* **Performance insights** - Identify bottlenecks and optimize agent performance
`anthropic/claude-sonnet-4-5`
`anthropic/claude-haiku-4-5`
`anthropic/claude-opus-4-6` | `ANTHROPIC_API_KEY` | | **OpenAI** | `openai/gpt-5.4-pro`
`openai/gpt-5.4`
`openai/gpt-5.4-mini`
`openai/gpt-5.4-nano`
`openai/gpt-5.2`
`openai/gpt-5.1`
`openai/gpt-4.1`
`openai/gpt-4.1-mini`
`openai/gpt-4.1-nano`
`openai/gpt-5`\* | `OPENAI_API_KEY` | | **Azure OpenAI** | `azure/my-gpt4-deployment`
`azure/my-gpt35-deployment` | `AZURE_API_KEY` | | **Google** | `google/gemini-3.1-pro-preview`
`google/gemini-2.5-flash`
`google/gemini-2.5-flash-lite` | `GOOGLE_GENERATIVE_AI_API_KEY` | | **OpenRouter** | `openrouter/anthropic/claude-sonnet-4-0`
`openrouter/meta-llama/llama-3.1-405b` | `OPENROUTER_API_KEY` | | **Gateway** | `gateway/openai/gpt-4.1-mini` | `AI_GATEWAY_API_KEY` | | **NVIDIA NIM** | `nim/nvidia/llama-3.3-nemotron-super-49b-v1.5`
`nim/nvidia/nemotron-4-340b-instruct` | `NIM_API_KEY` | | **Custom OpenAI-compatible** | `custom/my-custom-model`
`custom/llama-3-custom` | `CUSTOM_LLM_API_KEY` | | **Mock** | `mock/default` | None required |
## Agents
You can **link agents to a test suite** so you can filter or scope which agents are associated with that suite (for example when choosing who runs the items). Run configurations still declare which agents actually execute a given run.
## Run configurations and runs
A **run configuration** ties a test suite to:
* One or more **agents** that will each process every item (each item × agent produces a run invocation).
* Optional **evaluators** to run on the resulting conversations.
Create a run configuration from the test suite detail page (**Runs** tab). When you **start a run**, the platform creates a **test suite run** and processes items. You need at least one item and at least one agent on the configuration before a run can start.
Open a run to see per-item invocations, conversation links, and evaluation output when evaluators are configured.
## Programmatic access
| Surface | Use for |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [Evaluations API reference](/api-reference/evaluations) | CRUD test suites and items, agent links, run configs, trigger runs (`POST .../dataset-run-configs/{id}/run`), list runs and results |
| [TypeScript SDK: Evaluations](/typescript-sdk/evaluations) | `EvaluationClient` helpers (`listDatasets`, `createDataset`, `createDatasetItem`, `createDatasetItems`, etc.) |
Listing test suites supports an optional `agentId` query parameter on the list endpoint to restrict results to suites linked to that agent.
## Related
* [Evaluations in Visual Builder](/visual-builder/evaluations) — Evaluators, batch evaluations over conversations, and continuous tests
* [Evaluations API reference](/api-reference/evaluations)
* [TypeScript SDK: Evaluations](/typescript-sdk/evaluations)
# Environment Configuration (/community/contributing/environment-configuration)
How to configure the environment variables for the Inkeep Agent Framework
## Overview
The Inkeep Agents framework uses a **centralized environment configuration**. This approach provides a single source of truth for all environment variables across the monorepo, eliminating duplication and simplifying configuration management.
## Configuration Structure
### Single Root Configuration
All packages in the monorepo reference a **single `.env` file** at the repository root. This is different from the typical approach of having separate `.env` files per package.
```
agents-4/
├── .env # Main configuration (gitignored)
├── .env.example # Template with all variables
└── packages/
└── agents-core/
└── src/env.ts # Centralized env loader
```
### Loading Priority
Environment variables are loaded in the following order (highest priority first):
1. **`/package-name/.env`** Package specific configuration
2. **`.env`** - Main configuration file
3. **`~/.inkeep/config`** - User-global settings (shared across all repo copies)
4. **`.env.example`** - Default values
This hierarchy allows for flexible configuration management across different scenarios. If you have .env or .env.local in a package directory, they will override the root .env or .env.local for that package.
## Use Cases
### 1. Basic Local Development
For local development, `pnpm setup-dev` creates your `.env` and initializes databases. You only need to add your AI provider API keys:
```bash
# Run setup (creates .env, starts databases, runs migrations)
pnpm setup-dev
# Add your API keys to .env
vim .env
# Start development
pnpm dev
```
## Troubleshooting
### Auto-login not working
The Manage UI auto-logs you in during local development via a server-side proxy (`proxy.ts`). If you're redirected to the login page instead, your `.env` is likely missing the required variables. Ensure these are set:
```bash
INKEEP_AGENTS_MANAGE_UI_USERNAME=admin@example.com
INKEEP_AGENTS_MANAGE_UI_PASSWORD=
### Step 2: Enter a project
Once you're logged in, you'll be redirected to the Inkeep Enterprise project overview page. If you are part of a team, you might see a list of existing projects like this:
If you are part of a team, click into the project your team has created. If you are not part of a team, you can create a new project by clicking the "Create Project" button.
### Step 3: Inspect the project
Once you're in the project, you'll see the project overview page. You can see the list of agents that are part of the project.
In the MCP Servers section, you can see the list of MCP servers that are part of the project:
### Step 5: Try the agent
Once Inkeep has built your agent, try it out by clicking the "Try it" button.
### Step 6: Edit the agent
You can edit your agent by dragging and dropping new sub agents and tools onto the canvas. Here, we'll extend our knowledge agent to use a web search agent if it needs to find more information.
### Next Steps
### Step 3: Retrieve Your API Key
Copy your Composio API key from the Settings tab.
### Step 4: Add API Key to Environment
Add your Composio API key to your root `.env` file:
```
COMPOSIO_API_KEY=your-composio-api-key
```
### Step 5: Restart and Verify
Restart your development servers by pressing Control + C and running `pnpm dev` again (pressing `r` will not work).
Open the Visual Builder and navigate to the MCP Servers tab. Click **+New MCP Server**, then select the **Popular MCP Servers** tab and search for "composio" to see your configured Composio MCP servers.
# Build Custom MCP Servers (/guides/mcp-servers/custom-mcp-servers)
Build your own custom MCP servers
## When to Build Custom MCP Servers
Build custom MCP servers when:
* Native servers don't exist for your specific APIs
* You need custom business logic beyond what existing servers provide
* You have proprietary systems that require custom integration
If pre-built servers meet your needs, consider [Native MCP servers](/guides/mcp-servers/native-mcp-servers), [Composio's platform](/guides/mcp-servers/composio-mcp-servers), or [Gram](/guides/mcp-servers/gram) instead.
## Getting Started
The Quick Start workspace includes a Next.js app in the `apps/mcp/app/` directory that you can use to expose your MCP servers.
Each MCP server you create will be exposed on a separate route on this app.
#### Creating from a template
You can add a custom MCP server template from our [template library](https://github.com/inkeep/agents/tree/main/agents-cookbook/template-mcps) for common use cases using the [CLI](/typescript-sdk/cli-reference#inkeep-add).
```bash
inkeep add --mcp [server-name]
```
This will automatically add a custom MCP server template to your Quick Start workspace. After customizing and deploying it, you can register it.
#### Using Vercel's Template
If you want to create a custom MCP server, you can use Vercel's [Next.js MCP template](https://vercel.com/templates/next.js/model-context-protocol-mcp-with-next-js) as a starting point:
{messages.map((message) => (
))}
{message.role === "user" ? "👤 User" : "🤖 Assistant"}
{message.parts.map((part, partIndex) => {
const partKey = `${message.id}-${part.type}-${partIndex}`;
if (part.type === "text") {
return (
{part.text}
);
}
return null;
})}
Try asking:
- "What's the weather in New York?"
- "Can you get my location?"
- "Ask me to confirm something"
{messages.map((message) => (
))}
{message.role === "user" ? "👤 User" : "🤖 Assistant"}
{message.parts.map((part, partIndex) => {
const partKey = `${message.id}-${part.type}-${partIndex}`;
if (part.type === "text") {
return (
);
}
return null;
})}
{part.text}
);
}
if (part.type?.startsWith("data-")) {
return (
Data: {JSON.stringify(part, null, 2)}
Try asking:
- "What's the weather in New York?"
- "Can you get my location?"
- "Ask me to confirm something"
Your Tasks ({completedCount}/{totalCount} completed)
{tasks.map((task) => (
{task.title}
))}
{message.parts.map((part) => {
if (part.type === "tool-getWeather") {
switch (part.state) {
case "approval-requested":
return (
);
case "output-available":
return (
))}
);
}
```
Get weather for {part.input.city}?
Weather in {part.input.city}: {String(part.output)}
);
}
}
return null;
})}
Your Tasks ({totalCount} total)
{tasks.map((task) => (
{task.title}
))}
### Benefits
* **Personal accounts**: Team members can use their own accounts (e.g., their personal Notion workspace, Google Drive, etc.)
* **Better security**: Credentials are not shared across the team
* **Flexible access**: Each team member can connect to different resources based on their own permissions
### Considerations
* **Individual authentication required**: Each team member must authenticate their own credentials before using an agent that relies on user-level MCPs
* **Setup overhead**: New team members need to complete authentication before they can use shared agents
* **Not compatible with triggers**: User-level MCPs cannot be used with [webhook triggers](/visual-builder/triggers/webhooks) or scheduled jobs because these invocation methods don't have user context
## Project-Level MCP Servers
Project-level MCP servers use shared credentials that are configured at the project level. All team members in the project can use these servers without individual authentication.
### Benefits
* **Shared access**: All team members can immediately use agents without additional setup
* **Simplified onboarding**: New team members can start using agents right away
* **Centralized management**: Credentials are managed in one place
### Considerations
* **Shared credentials**: All team members use the same account, which may have security implications
* **Limited flexibility**: Team members cannot use their own accounts or personal resources
### When Sharing an Agent
When sharing an agent with your team, they'll need to authenticate their own credentials for any user-level MCPs before being able to use the agent. Make sure to communicate this requirement to your team members.
# Scheduled Triggers (/visual-builder/triggers/scheduled)
Run your Agents automatically on a recurring schedule or at a specific future time
Scheduled triggers run agents automatically on a recurring schedule (cron) or at a specific future time (one-time). Use them for daily reports, hourly health checks, periodic data syncs, or deferred tasks.