# Agent Module API Documentation

This document provides an overview of the public functions available in the Agent module, which facilitates creating, configuring, and running AI agents.

## Functions

### `agent_create`
- **Description:** Creates a new agent instance with a specified goal and optional message history.
- **Signature:** `agent_handle agent_create(const char *goal, messages_handle messages)`

### `agent_destroy`
- **Description:** Destroys an agent instance, freeing associated resources.
- **Signature:** `void agent_destroy(agent_handle agent)`

### `agent_set_max_iterations`
- **Description:** Sets the maximum number of iterations the agent will perform.
- **Signature:** `void agent_set_max_iterations(agent_handle agent, int max)`

### `agent_set_verbose`
- **Description:** Enables or disables verbose output for debugging.
- **Signature:** `void agent_set_verbose(agent_handle agent, bool verbose)`

### `agent_set_is_subagent`
- **Description:** Marks the agent as a sub-agent, affecting its logging and behavior.
- **Signature:** `void agent_set_is_subagent(agent_handle agent, bool is_subagent)`

### `agent_set_tool_registry`
- **Description:** Sets the tool registry for the agent, allowing it to use external tools.
- **Signature:** `void agent_set_tool_registry(agent_handle agent, tool_registry_t *registry)`

### `agent_get_state`
- **Description:** Retrieves the current state of the agent.
- **Signature:** `agent_state_t agent_get_state(agent_handle agent)`

### `agent_get_error`
- **Description:** Gets the last error message from the agent.
- **Signature:** `const char *agent_get_error(agent_handle agent)`

### `agent_get_iteration_count`
- **Description:** Returns the number of iterations the agent has performed.
- **Signature:** `int agent_get_iteration_count(agent_handle agent)`

### `agent_run`
- **Description:** Runs the agent with a user message, returning the generated response.
- **Signature:** `char *agent_run(agent_handle agent, const char *user_message)`

### `agent_chat`
- **Description:** Convenience function to create an agent, run it, and destroy it.
- **Signature:** `char *agent_chat(const char *user_message, messages_handle messages)`

### `agent_chat_with_limit`
- **Description:** Runs the agent with a maximum iteration limit.
- **Signature:** `char *agent_chat_with_limit(const char *user_message, int max_iterations, messages_handle messages)`

---

This API provides the core functions needed to manage AI agents within your application, including creation, configuration, execution, and cleanup.