> For the complete documentation index, see [llms.txt](https://agentic.gitbook.io/agentic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agentic.gitbook.io/agentic/api-reference.md).

# API Reference

This page provides a high-level overview of the main classes and types exported by `@obayd/agentic`. For detailed type signatures and JSDoc comments, please refer to the `.d.ts` declaration files included in the package within the `src/` directory (e.g., `src/Conversation.d.ts`, `src/Tool.d.ts`).

### Core Classes

* **`Conversation`**:
  * The main class for managing LLM interactions.
  * **Constructor:** `new Conversation(llmCallback, options?)`
  * **Methods:**
    * `.content(definition: ContentDefinitionItem[]): this` - Defines system prompt content and tools.
    * `.send(messageContent, ...args): AsyncGenerator<ConversationEvent>` - Sends a message and returns the event stream.
  * **Properties:**
    * `.messages: Message[]` - The conversation history.
    * `.enabledToolpacks: Set<string>` - Names of currently enabled toolpacks.
  * See: `src/Conversation.d.ts`
* **`Tool`**:
  * Used to define individual functions (tools) for the LLM.
  * **Static Methods:**
    * `Tool.make(name: string): Tool` - Starts building a tool.
  * **Instance Methods (Chainable):**
    * `.description(text: string): this` / `.desc(text: string): this`
    * `.param(name: string, description: string, options?): this`
    * `.raw(description?: string): this`
    * `.action(callback: ToolActionCallback): this`
  * See: `src/Tool.d.ts`
* **`Toolpack`**:
  * Used to group related `Tool` instances.
  * **Static Methods:**
    * `Toolpack.make(name: string): Toolpack` - Starts building a toolpack.
  * **Instance Methods (Chainable):**
    * `.description(text: string): this` / `.desc(text: string): this`
    * `.addTool(tool: Tool): this`
    * `.addTools(tools: Tool[]): this`
  * **Instance Methods (Other):**
    * `.getTools(): Tool[]` - Returns an array of tools in the pack.
  * See: `src/Toolpack.d.ts`

### Key Types & Interfaces

* **`LlmCallback`**:
  * Type signature for the required async generator function passed to the `Conversation` constructor.
  * `type LlmCallback = (messages: Message[], options: LlmCallbackOptions) => AsyncGenerator<string>;`
  * See: `src/Conversation.d.ts`
* **`Message`**:
  * Interface describing the structure of objects in the `conversation.messages` array.
  * Properties: `role`, `content`, `callId?`, `name?`, `params?`, `raw?`, `result?`, `error?`.
  * See: `src/Conversation.d.ts`
* **`ConversationEvent`**:
  * Union type representing the different event objects yielded by `conversation.send()`.
  * Types: `assistant`, `tool.generating`, `tool.calling`, `tool`, `error`.
  * See: `src/Conversation.d.ts`
* **`ContentDefinitionItem`**:
  * Union type representing items that can be passed in the array to `conversation.content()`.
  * Includes: `string`, `Tool`, `Toolpack`, `ContentPart`, and async functions resolving to these.
  * See: `src/Conversation.d.ts`
* **`ToolParamOptions`**:
  * Interface for options passed to `Tool.param()`.
  * Properties: `type?`, `required?`, `enum?`.
  * See: `src/Tool.d.ts`
* **`ContentPart`**:
  * Basic interface for structured content blocks (used in `Message.content` arrays and normalized tool results).
  * Properties: `type: string`, `[key: string]: any`.
  * See: `src/lib/utils.d.ts`
* **`NormalizedToolResult`**:
  * Interface for the object returned by the internal `normalizeToolResult` utility.
  * Properties: `content: ContentPart[]`, `error?`, `[key: string]: any`.
  * See: `src/lib/utils.d.ts`

### Utility Functions

* **`fetchResponseToStream(response: Response): AsyncGenerator<string>`**:
  * Helper function to convert a Fetch API `Response` object (expected to contain Server-Sent Events) into an async generator yielding text chunks. Useful for implementing the `llmCallback`.
  * See: `src/lib/utils.d.ts` and Utilities.

Refer to the source `.d.ts` files for the most detailed and up-to-date type information and documentation comments.