Agents & Sub Agents
Copy page
Learn how to customize your Agents.
Agents and Sub Agents are the core building blocks of the Inkeep Agent framework.
An Agent is made up of one or more Sub Agents that can delegate or transfer control with each other, share context, use tools to respond to a user or complete a task.
Creating an Agent
An Agent is your top-level entity that you as a user interact with or can trigger programmatically.
An Agent is made up of sub-agents, like so:
The prompt is automatically put into context and added into each Sub Agent's system prompt. This provides consistent behavior and tone to all Sub Agents so they can act and respond as one cohesive unit to the end-user.
Creating a Sub Agent
Like an Agent, a Sub Agent needs an id, name, and clear prompt that define its behavior:
Configuring Models
Configure models at either the Agent or Sub Agent level. Sub Agents inherit from their parent Agent when not explicitly set, and Agents inherit from project defaults.
The models object allows you to configure different models for different tasks, each with their own provider options:
Model types
base: Primary model used for conversational text generation and reasoningstructuredOutput: Model used for structured JSON output only (falls back to base if not configured and nothing to inherit)summarizer: Model used for summaries and status updates (falls back to base if not configured and nothing to inherit)
Supported providers
The framework supports a wide range of models from major AI providers:
- Anthropic: For example
anthropic/claude-opus-4-1,anthropic/claude-sonnet-4-5,anthropic/claude-sonnet-4,anthropic/claude-haiku-4-5,anthropic/claude-3-5-haiku-latest, and more - OpenAI: For example
openai/gpt-5,openai/gpt-4.1-mini,openai/gpt-4.1-nano, and more - Google: For example
google/gemini-2.5-pro,google/gemini-2.5-flash,google/gemini-2.5-flash-lite, and more - Additional providers via OpenRouter and gateway routing
Provider options
All models support providerOptions to customize their behavior. These include both generic parameters that work across all providers and provider-specific features like reasoning.
Generic parameters
These parameters work with all supported providers and go directly in providerOptions:
Provider-specific features
Advanced features like reasoning require provider-specific configuration wrapped in the provider name:
OpenAI reasoning
openai/gpt-5, openai/gpt-5-mini, and openai/gpt-5-nano require a verified OpenAI organization. If your organization is not yet verified, these models will not be available.Anthropic thinking
Google Gemini thinking
Accessing other models
For models not directly supported, use these proxy providers:
- OpenRouter: Access any model via
openrouter/model-idformat (e.g.,openrouter/anthropic/claude-sonnet-4-0,openrouter/meta-llama/llama-3.1-405b) - Vercel AI SDK Gateway: Access models through your gateway via
gateway/model-idformat (e.g.,gateway/anthropic/claude-sonnet-4-0)
Required API keys
You need the appropriate API key for your chosen provider to be defined in your environment variables:
ANTHROPIC_API_KEYfor Anthropic modelsOPENAI_API_KEYfor OpenAI modelsGOOGLE_GENERATIVE_AI_API_KEYfor Google modelsOPENROUTER_API_KEYfor OpenRouter modelsAI_GATEWAY_API_KEYfor Vercel AI SDK Gateway models
Default models
When using the Inkeep CLI, the following defaults are applied based on your chosen provider:
Anthropic:
base:anthropic/claude-sonnet-4-5structuredOutput:anthropic/claude-sonnet-4-5summarizer:anthropic/claude-sonnet-4-5
OpenAI:
base:openai/gpt-4.1structuredOutput:openai/gpt-4.1summarizer:openai/gpt-4.1-nano
Google:
base:google/gemini-2.5-flashstructuredOutput:google/gemini-2.5-flash-litesummarizer:google/gemini-2.5-flash-lite
Configuring StopWhen
Control stopping conditions to prevent infinite loops:
Configuration levels:
transferCountIs: Project or Agent levelstepCountIs: Project or Sub Agent level
Settings inherit from Project → Agent → Sub Agent.
Sub Agent overview
Beyond model configuration, Sub Agents define tools, structured outputs, and agent-to-agent relationships available to the Sub Agent.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable Sub Agent identifier used for consistency and persistence |
name | string | Yes | Human-readable name for the Sub Agent |
prompt | string | Yes | Detailed behavior guidelines and system prompt for the Sub Agent |
description | string | No | Brief description of the Sub Agent's purpose and capabilities |
models | object | No | Model configuration for this Sub Agent. See Configuring Models |
stopWhen | object | No | Stop conditions (stepCountIs). See Configuring StopWhen |
canUse | function | No | Returns the list of MCP/tools the Sub Agent can use. See MCP Servers |
dataComponents | array | No | Structured output components for rich, interactive responses. See Data Components |
artifactComponents | array | No | Components for handling tool or Sub Agent outputs. See Artifact Components |
canTransferTo | function | No | Function returning array of Sub Agents this Sub Agent can transfer to. See Transfer Relationships |
canDelegateTo | function | No | Function returning array of Sub Agents this Sub Agent can delegate to. See Delegation Relationships |
Tools & MCPs
Enable tools for a Sub Agent to perform actions like looking up information or calling external APIs.
Tools can be:
- MCP Servers - Connect to external services and APIs using the Model Context Protocol
- Function Tools - Custom JavaScript functions that execute directly in secure sandboxes
Data components
Structured output components for rich, interactive responses. See Data Components.
Artifact components
Components for handling tool or Sub Agent outputs. See Artifact Components.
Sub Agent relationships
Define other Sub Agents this Sub Agent can transfer control to or delegate tasks to.
As a next step, see Sub Agent Relationships to learn how to design transfer and delegation relationships between Sub Agents.