# Agent Module Documentation

This document provides an overview of the public functions available in the agent module, based on the header `include/agent.h` and implementation in `src/agent.c`.

---

## Public Function Signatures and Descriptions

### `agent_handle agent_create(const char *goal, messages_handle messages)`
- **Purpose:** Creates a new agent instance with a specified goal and message history.
- **Details:** Initializes the agent's state, loads message history, and sets up necessary resources.

### `void agent_destroy(agent_handle agent)`
- **Purpose:** Cleans up and frees resources associated with an agent.
- **Details:** Destroys HTTP client, message history, and frees memory.

### `void agent_set_max_iterations(agent_handle agent, int max)`
- **Purpose:** Sets the maximum number of iterations for the agent's run loop.
- **Details:** Limits the number of recursive or iterative steps.

### `void agent_set_verbose(agent_handle agent, bool verbose)`
- **Purpose:** Enables or disables verbose logging.
- **Details:** Controls detailed output during agent execution.

### `void agent_set_is_subagent(agent_handle agent, bool is_subagent)`
- **Purpose:** Marks the agent as a sub-agent.
- **Details:** Influences behavior such as output verbosity.

### `void agent_set_tool_registry(agent_handle agent, tool_registry_t *registry)`
- **Purpose:** Assigns a specific tool registry to the agent.
- **Details:** Customizes available tools for the agent.

### `agent_state_t agent_get_state(agent_handle agent)`
- **Purpose:** Retrieves the current state of the agent.
- **Details:** States include idle, running, error, completed, etc.

### `const char *agent_get_error(agent_handle agent)`
- **Purpose:** Gets the last error message.
- **Details:** Useful for debugging and error handling.

### `int agent_get_iteration_count(agent_handle agent)`
- **Purpose:** Returns the number of iterations performed.
- **Details:** Useful for monitoring progress.

### `char *agent_chat(const char *user_message, messages_handle messages)`
- **Purpose:** Runs the agent with a user message and returns the response.
- **Details:** Executes the main loop, handling response processing, tool calls, and recursion.

### `char *agent_chat_with_limit(const char *user_message, int max_iterations, messages_handle messages)`
- **Purpose:** Runs the agent with a user message, limiting iterations.
- **Details:** Useful for bounded execution.

---

This documentation summarizes the core public API of the agent module, facilitating integration and understanding of its capabilities.