charmbracelet/crush · error

task agent not configured

Error message

task agent not configured

What it means

coordinator.agentTool builds the 'agent' sub-agent tool and requires that an agent definition named config.AgentTask ("task") exists in the configured Agents map. If the user's crush config defines no 'task' agent, the tool cannot know which prompt/model to run for sub-agent spawns, so buildTools fails with this error.

Source

Thrown at internal/agent/agent_tool.go:29

	"github.com/charmbracelet/crush/internal/agent/tools"
	"github.com/charmbracelet/crush/internal/config"
)

//go:embed templates/agent_tool.md
var agentToolDescription string

type AgentParams struct {
	Prompt string `json:"prompt" description:"The task for the agent to perform"`
}

const (
	AgentToolName = "agent"
)

func (c *coordinator) agentTool(ctx context.Context) (fantasy.AgentTool, error) {
	agentCfg, ok := c.cfg.Config().Agents[config.AgentTask]
	if !ok {
		return nil, errors.New("task agent not configured")
	}
	prompt, err := taskPrompt(prompt.WithWorkingDir(c.cfg.WorkingDir()))
	if err != nil {
		return nil, err
	}

	agent, err := c.buildAgent(ctx, prompt, agentCfg, true)
	if err != nil {
		return nil, err
	}
	return fantasy.NewParallelAgentTool(
		AgentToolName,
		agentToolDescription,
		func(ctx context.Context, params AgentParams, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
			if params.Prompt == "" {
				return fantasy.NewTextErrorResponse("prompt is required"), nil
			}

View on GitHub (pinned to 7944b8e522)

Solutions

1. Add a 'task' agent definition to your crushrc/crush.json (agents.task with model and prompt settings).
2. Restore the default config (remove a custom config that omits the task agent) so the built-in task agent is used.
3. If building Config programmatically, populate Agents[config.AgentTask] before constructing the coordinator.

Example fix

// before (crushrc)
# no task agent defined
// after
task {
  model anthropic/claude-sonnet-4
  prompt "You are a task agent"
}

if _, ok := cfg.Agents[config.AgentTask]; !ok {
    return errors.New("config must define a 'task' agent before building tools")
}

coord, err := NewCoordinator(ctx, opts)
if errors.Is(err, errTaskNotConfigured) || strings.Contains(err.Error(), "task agent not configured") {
    // reload default config or inject Agents[config.AgentTask], then retry
}

When it happens

Trigger: Calling buildTools (during coordinator setup) when cfg.Config().Agents does not contain the key config.AgentTask — i.e. the 'task' agent block was removed, renamed, or never defined in crushrc/crush.json.

Common situations: Users hand-editing their crush config and deleting or renaming the [agents.task] section; configs copied from older versions before the task agent was mandatory; programmatic Config objects built without Agents entries.

Related errors

• coder agent not configured
• agent configuration not found
• coder agent configuration is missing
• failed to initialize agent: %w
• small model provider not configured

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/626f9cb766e8c51a. Report an issue: GitHub.