goose/docs/errors.md

# Errors

Error handling is a key performance-driving part of `goose`. There are many ways that the non-determinism
in the LLM can introduce an error that it can in turn recover from. In a typical goose session, its expected for there
to be several agent errors that the model can see directly and correct, perhaps entirely behind the scenes.

## Traditional Errors

While the agent is operating, there can be intermittent issues in the network, availability of the
foundational model, etc. These are raised as errors in the agent API to the caller, who can decide
how to handle that. We generally handle these with anyhow::Error. 

## Agent Errors

There are several types of errors where everything is working correctly, but the model generations
themselves are somehow causing errors. Things like generating an unknown tool name, incorrect parameters, 
or a well formed tool call that results in an error in the tool itself. All of these can be surfaced to
the LLM to have it attempt to recover. 

The error messages are in some ways prompting - they give instructions to the LLM on how it might go
about recovering. We handle these with thiserror::Error and carefully maintain a collection.

To cover all these cases, both ToolUse and ToolResult are typically passed through the api as part of a
`Result<T, AgentError>`. An error in a ToolUse will immediately become an error in a ToolResult and
passed back to the LLM. A valid ToolUse might still end up in an error ToolResult, which is also passed
back to the LLM. 

The `provider`s then handle translating the agent errors into the various API specs as
valid messages..