[WIP] Docs

Author: sirwolfgang

docs/docs.md

@@ -43,7 +43,7 @@ Messages are rendered by the Agent's actions when `prompt` is called. This `prom
 <FeatureCards :cards="$frontmatter.view" />
 
 ## Controller: Agents
-Agents are the core of the Active Agent framework and control the prompt and response cycle. Agents are controllers for AI-driven interactions, managing prompts, actions, and responses. Agents are responsible for managing context, handling user input, generating content, and interacting with generation providers.
+Agents are the core of the Active Agent framework and control the prompt and response cycle. Agents are controllers for AI-driven interactions, managing prompts, actions, and responses. Agents are responsible for managing context, handling user input, generating content, and interacting with providers.
 
 <FeatureCards :cards="$frontmatter.controller" />
 

docs/docs/action-prompt.md

@@ -6,6 +6,6 @@ Action Prompt is a core component of Active Agent that provides a structured way
 
 Active Agent implements base methods that can be used by any agent that inherits from `ActiveAgent::Base`. 
 
-The primary method is `Agent.prompt(...)` which provides a direct interface to create prompts with messages, and custom actions which use view templates for more complex formatting.
+For production applications, **custom actions** are the recommended approach for organizing agent behaviors. For testing and quick prototyping, `Agent.prompt(...)` provides a direct interface to create prompts with messages. Both actions and `Agent.prompt(...)` can work without view templates when passing messages directly.
 
 Action Prompt leverages Action View templates to render messages and provides a consistent interface for generating content.

docs/docs/action-prompt/actions.md

@@ -1,18 +1,18 @@
 # Actions
-Active Agent uses Action View to render Message content for [Prompt](./prompts.md) context objects.
+Actions are the recommended way to organize agent behaviors in production applications. Active Agent can optionally use Action View to render Message content for [Prompt](./prompts.md) context objects when complex formatting is needed.
 
 ## Prompt
-The `prompt` method is used to render the action's content as a message in a prompt. The `prompt` method is similar to `mail` in Action Mailer or `render` in Action Controller, it allows you to specify the content type and view template for the action's response.
+The `prompt` method is used to render the action's content as a message in a prompt. The `prompt` method is similar to `mail` in Action Mailer or `render` in Action Controller. It can render view templates for complex formatting, or work without templates by passing message content directly.
 
 ```ruby
 # The prompt method is typically called within an action
 class MyAgent < ApplicationAgent
   def my_action
     prompt(
       content_type: :text, # or :json, :html, etc.
-      message: "Hello, world!", # The message content to be rendered
+      message: "Hello, world!", # The message content (can be passed directly without a template)
       messages: [], # Additional messages to include in the prompt context
-      template_name: "action_template", # The name of the view template to be used
+      template_name: "action_template", # Optional: The name of the view template to use
       instructions: { template: "instructions" }, # Optional instructions for the prompt generation
       actions: [], # Available actions for the agent to use
       output_schema: :schema_name # Optional schema for structured output
@@ -88,13 +88,22 @@ When using the `with` method, it's important to understand the distinction:
 
 Example:
 ```ruby
-# Regular parameters and runtime options
+**Explanation:**
+
+- **Action parameters** (e.g., `destination`, `user_id`) should be passed via the `:params` hash and accessed with `params[:key]`
+- **Runtime options** (like `model`, `temperature`, etc.) should be passed via the `:options` key to configure the provider
+- This separation provides clarity between business logic parameters and AI configuration
+
+```ruby
+# In the agent class:
+generate_with :openai, model: "gpt-4o-mini"
+
+# When calling with runtime options:
 TravelAgent.with(
-  destination: "Paris",        # Regular parameter
-  user_id: 123,               # Regular parameter
-  options: {                  # Runtime options
-    model: "gpt-4o",
-    temperature: 0.7
+  destination: "Paris",    # Business logic params
+  user_id: 123,           # Business logic params
+  options: {
+    temperature: 0.9      # Provider configuration
   }
 ).search
 
@@ -182,12 +191,11 @@ Available runtime options include:
 5. The action method returns a response, which can be a rendered view, JSON data, or any other content type specified in the `prompt` method.
 6. The agent updates the context with the action's result and prepares the response to be sent back to the user.
 
-## How Agents handle responses
-1. The agent receives a response from the generation provider, which includes the generated content and any actions that need to be performed.
-2. The agent processes the response
-3. If there are no `requested_actions` then response is sent back to the user.
-4. If the response includes actions, then agent executes them and updates the context accordingly.
-5. If the resulting context `requested_actions` includes `reiterate`, then context is updated with the new messages, actions, and parameters, and the cycle continues.
+## Tool Execution Flow
+
+When an agent calls an action:
+
+1. The agent receives a response from the provider, which includes the generated content and any actions that need to be performed.
 
 ### Respond to User
 1. You provide the model with a prompt or conversation history, along with a set of tools.

docs/docs/action-prompt/messages.md

@@ -9,7 +9,7 @@ Messages can be structured as a Message object or hash with the following attrib
 - `content`: The content of the message, which can be plain text or formatted content.
 - `requested_actions`: An array of actions that the agent requested to be performed in response to the message. This is used to handle tool use requests from the agent.
 
-<<< @/../test/agents/messages_examples_test.rb#messages_structure{ruby:line-numbers}
+<<< @/../test/agents/support_agent_test.rb#messages_structure{ruby:line-numbers}
 
 
 ## Instructions as system messages to the agent
@@ -36,15 +36,15 @@ An `:assistant` message is used to represent the agent's response to the user. T
 
 ### Messages with Requested Actions
 
-<<< @/../test/agents/messages_examples_test.rb#messages_with_actions{ruby:line-numbers}
+<<< @/../test/agents/support_agent_test.rb#messages_with_actions{ruby:line-numbers}
 
 ## The system responds to agent requested actions with :tool messages
 Agent performed actions result in `:tool` message. These messages are used to represent the response to a tool call made by the agent. This message is used to provide additional information about the tool call, such as the name of the tool and any arguments that were passed to the tool. The system can use this message to provide a response message containing the result of the tool call and can also include links or other interactive elements.
 
-<<< @/../test/agents/messages_examples_test.rb#tool_messages{ruby:line-numbers}
+<<< @/../test/agents/support_agent_test.rb#tool_messages{ruby:line-numbers}
 
 ## Building Message Context
 
 Messages form the conversation history that provides context for the agent. [Learn how messages flow through generation →](/docs/active-agent/generation)
 
-<<< @/../test/agents/messages_examples_test.rb#message_context{ruby:line-numbers}
+<<< @/../test/agents/support_agent_test.rb#message_context{ruby:line-numbers}

docs/docs/action-prompt/prompts.md

@@ -1,10 +1,7 @@
-# Prompt
-
-The Prompt is the container for runtime context messages and options passed to the generation provider. 
-
-Prompts are responsible for managing the contextual history and providing the necessary information to the generation provider for a meaningful prompt and response cycles.
-
+# Prompts
+The Prompt is the container for runtime context messages and options passed to the provider.
 
+Prompts are responsible for managing the contextual history and providing the necessary information to the provider for a meaningful prompt and response cycles.
 ## Prompt Structure
 The Prompt is structured to include the following components:
 - **Messages**: An array of messages that represent the contextual information or conversational chat history. Each message includes content, role (user or assistant), and metadata.
@@ -13,9 +10,9 @@ The Prompt is structured to include the following components:
 - **Options**: Runtime configuration options that control the generation behavior (e.g., model, temperature, max_tokens). See [Runtime options](actions.md#runtime-options) for details.
 
 ## Example Prompt
-Prompts are built and rendered in the agent's action methods, typically using the `prompt` method. This is an example of creating a prompt by manually building the context; assigning `actions`, the prompt `message` and context `messages`.
+Prompts are built and rendered in the agent's action methods, typically using the `prompt` method. This is an example of creating a prompt by manually building the context; assigning the prompt `message` and context `messages`.
 
-<<< @/../test/action_prompt/prompt_test.rb#support_agent_prompt_initialization{ruby:line-numbers} [support_agent.rb]
+<<< @/../test/agents/application_agent_test.rb#application_agent_loaded_context_message_generation{ruby:line-numbers}
 
 
 ## Rendering Prompts
@@ -30,4 +27,4 @@ Prompts can be rendered using the `prompt` method inside an Agent's action metho
 
 ::: code-group
 <<< @/../test/agents/translation_agent_test.rb#translation_agent_render_translate_prompt{ruby} [test/agents/translation_agent_test.rb:6..8]
-:::
+:::

docs/docs/active-agent/generation.md

@@ -30,10 +30,10 @@ Loading a context from an existing prompt context:
 ## Prompt Generation Request-Response Cycle
 The prompt generation cycle is similar to the request-response cycle of Action Controller and is at the core of the Active Agent framework. It involves the following steps:
 1. **Prompt Context**: The Prompt object is created with the necessary context, including messages, actions, and parameters.
-2. **Generation Request**: The agent sends a request to the generation provider with the prompt context, including the messages and actions.
-3. **Generation Response**: The generation provider processes the request and returns a response, which is then passed back to the agent.
+2. **Generation Request**: The agent sends a request to the provider with the prompt context, including the messages and actions.
+3. **Generation Response**: The provider processes the request and returns a response, which is then passed back to the agent.
 4. **Response Handling**: The agent processes the response, which can be sent back to the user or used for further processing.
 5. **Action Execution**: If the response includes actions, the agent executes them and updates the context accordingly.
 6. **Updated Context**: The context is updated with the new messages, actions, and parameters, and the cycle continues. [Customize generation behavior with callbacks →](/docs/active-agent/callbacks)
 ## Prompt Context
-Action Prompt renders prompt context objects that represent the contextual data and runtime parameters for the generation process. Prompt context objects contain messages, actions, and params that are passed in the request to the agent's generation provider. The context object is responsible for managing the contextual history and providing the necessary information for prompt and response cycles.
+Action Prompt renders prompt context objects that represent the contextual data and runtime parameters for the generation process. Prompt context objects contain messages, actions, and params that are passed in the request to the agent's provider. The context object is responsible for managing the contextual history and providing the necessary information for prompt and response cycles.

docs/docs/active-agent/structured-output.md

@@ -110,10 +110,10 @@ Handle JSON parsing errors gracefully:
 
 Different AI providers have varying levels of structured output support:
 
-- **[OpenAI](/docs/generation-providers/openai-provider#structured-output)** - Native JSON mode with strict schema validation
-- **[OpenRouter](/docs/generation-providers/open-router-provider#structured-output-support)** - Support through compatible models, ideal for multimodal tasks
-- **[Anthropic](/docs/generation-providers/anthropic-provider#structured-output)** - Instruction-based JSON generation
-- **[Ollama](/docs/generation-providers/ollama-provider#structured-output)** - Local model support with JSON mode
+- **[OpenAI](/docs/providers/openai-provider#structured-output)** - Native JSON mode with strict schema validation
+- **[OpenRouter](/docs/providers/open-router-provider#structured-output-support)** - Support through compatible models, ideal for multimodal tasks
+- **[Anthropic](/docs/providers/anthropic-provider#structured-output)** - Instruction-based JSON generation
+- **[Ollama](/docs/providers/ollama-provider#structured-output)** - Local model support with JSON mode
 
 ## Real-World Examples
 
@@ -137,7 +137,7 @@ Leverage ActiveRecord/ActiveModel for single source of truth:
 ```ruby
 class User < ApplicationRecord
   include ActiveAgent::SchemaGenerator
-  
+
   validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
   validates :age, numericality: { greater_than: 18 }
 end
@@ -160,7 +160,7 @@ Always test structured output with real providers:
 test "extracts data with correct schema" do
   VCR.use_cassette("structured_extraction") do
     response = agent.extract_data.generate_now
-    
+
     assert_equal "application/json", response.message.content_type
     assert response.message.content.is_a?(Hash)
     assert_valid_schema response.message.content, expected_schema
@@ -205,7 +205,7 @@ After:
 class ExtractedUser
   include ActiveModel::Model
   include ActiveAgent::SchemaGenerator
-  
+
   attribute :name, :string
   attribute :age, :integer
 end
@@ -235,5 +235,5 @@ schema = ExtractedUser.to_json_schema(strict: true)
 ## See Also
 
 - [Data Extraction Agent](/docs/agents/data-extraction-agent) - Complete extraction examples
-- [OpenAI Structured Output](/docs/generation-providers/openai-provider#structured-output) - OpenAI implementation details
-- [OpenRouter Structured Output](/docs/generation-providers/open-router-provider#structured-output-support) - Multimodal extraction
+- [OpenAI Structured Output](/docs/providers/openai-provider#structured-output) - OpenAI implementation details
+- [OpenRouter Structured Output](/docs/providers/open-router-provider#structured-output-support) - Multimodal extraction

docs/docs/agents/data-extraction-agent.md

@@ -98,7 +98,7 @@ Structured output requires a generation provider that supports JSON schemas. Cur
 - **OpenAI** - GPT-4o, GPT-4o-mini, GPT-3.5-turbo variants
 - **OpenRouter** - When using compatible models like OpenAI models through OpenRouter
 
-See the [OpenRouter Provider documentation](/docs/generation-providers/open-router-provider#structured-output-support) for details on using structured output with multiple model providers.
+See the [OpenRouter Provider documentation](/docs/providers/open-router-provider#structured-output-support) for details on using structured output with multiple model providers.
 :::
 
 
@@ -164,7 +164,7 @@ Extract resume data with a predefined `resume_schema`:
 
 For extracting data from receipts and invoices, you can use OpenRouter's multimodal capabilities combined with structured output. OpenRouter provides access to models that support both vision and structured output, making it ideal for document processing tasks.
 
-See the [OpenRouter Receipt Extraction example](/docs/generation-providers/open-router-provider#receipt-data-extraction-with-structured-output) for a complete implementation that extracts:
+See the [OpenRouter Receipt Extraction example](/docs/providers/open-router-provider#receipt-data-extraction-with-structured-output) for a complete implementation that extracts:
 - Merchant information (name, address)
 - Line items with prices
 - Tax and total amounts
@@ -186,5 +186,5 @@ Choose your provider based on your specific needs:
 - **Anthropic**: Strong reasoning capabilities with Claude models
 - **Ollama**: Local model deployment for privacy-sensitive data
 
-Learn more about configuring providers in the [Generation Provider Overview](/docs/framework/generation-provider).
-:::
+Learn more about configuring providers in the [Provider Overview](/docs/framework/provider).
+:::