Inkeep Agents SDK Best Practices
Comprehensive guide for building effective multi-agent systems with the Inkeep Agents SDK. Contains best practices across 7 categories, prioritized by impact to guide agent design, tool configuration, and context management.
When to Apply
Reference these guidelines when:
- Creating new Agents or Sub Agents
- Configuring MCP servers or function tools
- Deciding between transfer vs delegate patterns
- Implementing structured outputs (data/artifact/status components)
- Managing context via headers and context fetchers
- Organizing projects and credentials
- Using the CLI for push/pull workflows
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Sub Agent Design | CRITICAL | subagent- |
| 2 | Multi-Agent Relationships | HIGH | relationship- |
| 3 | Tools & MCP Servers | HIGH | tools- |
| 4 | Context Management | MEDIUM-HIGH | context- |
| 5 | Structured Outputs | MEDIUM | outputs- |
| 6 | Project Organization | MEDIUM | project- |
| 7 | Development Workflow | LOW-MEDIUM | workflow- |
Quick Reference
1. Sub Agent Design (CRITICAL)
subagent-focused-scope- Keep sub agents focused on narrow, well-defined taskssubagent-tool-limit- Limit sub agents to 5-7 related toolssubagent-clear-instructions- Write clear, specific instructions in promptssubagent-stable-ids- Use explicit stable IDs for agents across deployments
2. Multi-Agent Relationships (HIGH)
relationship-transfer-vs-delegate- Use transfer for handoff, delegate for subtasksrelationship-delegate-no-user-response- Delegates cannot respond directly to usersrelationship-transfer-control- Transfers make receiving agent the primary driverrelationship-minimal-complexity- Avoid multi-agent when single agent suffices
3. Tools & MCP Servers (HIGH)
tools-mcp-server-config- Configure MCP servers with proper credentialstools-selected-tools- Use selectedTools to limit exposed toolstools-function-tools- Use function tools for custom sandboxed logictools-credential-references- Reference credentials by ID, resolve at push time
4. Context Management (MEDIUM-HIGH)
context-headers- Pass request-time context via headerscontext-fetchers- Auto-fetch external data at conversation startcontext-variables- Reference headers/context as {{variables}} in promptscontext-artifacts- Save tool call results as artifacts for sharing
5. Structured Outputs (MEDIUM)
outputs-data-components- Use data components for rich UI renderingoutputs-artifact-components- Define artifact structure with props schemaoutputs-status-updates- Provide real-time progress during long operationsoutputs-zod-schemas- Use Zod schemas for type-safe component props
6. Project Organization (MEDIUM)
project-logical-grouping- Group related agents/tools in projectsproject-model-inheritance- Configure models at project level for inheritanceproject-credential-management- Manage credentials per environmentproject-stop-conditions- Set stopWhen limits at project/agent level
7. Development Workflow (LOW-MEDIUM)
workflow-push-pull- Use CLI push/pull to sync code with Visual Builderworkflow-environment-settings- Use createEnvironmentSettings for env-specific configworkflow-minimal-config- Don't add unnecessary properties or fake MCPs
How to Use
Read individual rule files for detailed explanations and code examples:
rules/subagent-focused-scope.md
rules/relationship-transfer-vs-delegate.md
rules/tools-mcp-server-config.mdEach rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references