sigoden/aichat · error

Unknown agent

Error message

Unknown agent `{name}`

What it means

Guard in Agent::init: the requested agent name has no corresponding definition, because <agent-functions-dir>/<name>/index.yaml does not exist. The input at fault is the agent name passed on the command line or from config — it was never installed/created, is misspelled, or lives in a different functions directory.

Solutions

1. List installed agents to see which names are actually available and correct the typo
2. Create the agent with its scaffold command so the index.yaml definition file is generated
3. Check that AGENT_FUNCTIONS_DIR or the equivalent setting points at the directory containing the agent
4. Add a fuzzy-match suggestion ('did you mean X?') when a similarly named agent exists

When it happens

Trigger: Thrown at src/config/agent.rs:41 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of sigoden/aichat@82976d349a (2026-09-09). Data as JSON: /api/errors/cca043b1943e24fc. Report an issue: GitHub.

Appendix: source

Thrown at src/config/agent.rs:41

    shared_variables: AgentVariables,
    session_variables: Option<AgentVariables>,
    shared_dynamic_instructions: Option<String>,
    session_dynamic_instructions: Option<String>,
    functions: Functions,
    rag: Option<Arc<Rag>>,
    model: Model,
}

impl Agent {
    pub async fn init(
        config: &GlobalConfig,
        name: &str,
        abort_signal: AbortSignal,
    ) -> Result<Self> {
        let functions_dir = Config::agent_functions_dir(name);
        let definition_file_path = functions_dir.join("index.yaml");
        if !definition_file_path.exists() {
            bail!("Unknown agent `{name}`");
        }
        let functions_file_path = functions_dir.join("functions.json");
        let rag_path = Config::agent_rag_file(name, DEFAULT_AGENT_NAME);
        let config_path = Config::agent_config_file(name);
        let mut agent_config = if config_path.exists() {
            AgentConfig::load(&config_path)?
        } else {
            AgentConfig::new(&config.read())
        };
        let mut definition = AgentDefinition::load(&definition_file_path)?;
        let functions = if functions_file_path.exists() {
            Functions::init(&functions_file_path)?
        } else {
            Functions::default()
        };
        definition.replace_tools_placeholder(&functions);

        agent_config.load_envs(&definition.name);

View on GitHub (pinned to 82976d349a)