### Run jvagent Application

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/SETUP.md

Provides instructions on how to run the jvagent application from different directories and with various command-line flags for updates and debugging.

```bash
# From the jvagent repository root
jvagent examples/jvagent_app

# From within the app directory
cd examples/jvagent_app
jvagent

# With flags
jvagent examples/jvagent_app --update
jvagent examples/jvagent_app --debug
jvagent examples/jvagent_app --update --debug
```

--------------------------------

### Python: Complete Respond Example

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/interact/README.md

A comprehensive example demonstrating the use of various options with the respond method, including history configuration, directives, and parameters.

```python
response = await self.respond(
    visitor,
    use_history=True,
    history_limit=10,
    with_interpretation=True,
    with_event=True,
    directives=[
        "Use the provided context to answer the question",
        "Be concise and accurate"
    ],
    parameters=[
        {
            "condition": "No relevant context found",
            "response": "Inform the user that no relevant information was found"
        }
    ]
)
```

--------------------------------

### User Onboarding Flow with Branches (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/interview/README.md

This Python example demonstrates a user onboarding flow using conditional branching. The 'account_type' question branches to either 'business_details' or 'personal_details' based on the user's input. Subsequent questions like 'business_details' and 'personal_details' use `default_next` to guide the user to 'contact_info', creating a structured conversation.

```python
question_index = [
    {
        "name": "account_type",
        "question": "What type of account do you want? (personal/business)",
        "branches": [
            {"condition": {"op": "equals", "value": "business"}, "target": "business_details"},
            {"condition": {"op": "equals", "value": "personal"}, "target": "personal_details"}
        ]
    },
    {
        "name": "business_details",
        "question": "What's your company name?",
        "default_next": "contact_info"
    },
    {
        "name": "personal_details",
        "question": "What's your full name?",
        "default_next": "contact_info"
    },
    {
        "name": "contact_info",
        "question": "What's your email address?"
    }
]
```

--------------------------------

### WhatsApp Adapter Example

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/response/README.md

Provides an example implementation of a WhatsAppAdapter, showing how to extend ChannelAdapter for a specific service.

```APIDOC
## Example: WhatsApp Adapter

See `jvagent/action/whatsapp/whatsapp_adapter.py` for a complete implementation example.

### WhatsAppAction Integration

```python
class WhatsAppAction(Action):
    api_url: Optional[str] = attribute(default=None)
    api_key: Optional[str] = attribute(default=None)

    async def on_register(self) -> None:
        adapter = WhatsAppAdapter(
            channel="whatsapp",
            action=self,
        )
        await adapter.initialize()
        self._channel_adapter = adapter
```

### WhatsAppAdapter Implementation

```python
class WhatsAppAdapter(ChannelAdapter):
    def __init__(self, channel: str = "whatsapp", action: Any = None, ...):
        super().__init__(channel, response_bus)
        self.action = action
    
    async def handle_message(self, message: ResponseMessage) -> None:
        if not self.should_handle(message):
            return
        
        if message.message_type in ("adhoc", "final"):
            success = await self.send_to_destination(message)
            if success:
                message.mark_delivered()
    
    async def send_to_destination(self, message: ResponseMessage) -> bool:
        # Use self.action.api_url and self.action.api_key
        # Send to WhatsApp API
        ...
```
```

--------------------------------

### Configure Environment Variables for jvagent

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/SETUP.md

Copies the example environment file and instructs users to add their OpenAI API key. This is a crucial step for authenticating with OpenAI services.

```bash
cp .env.example .env
OPENAI_API_KEY=sk-your-actual-openai-api-key-here
```

--------------------------------

### Action Integration Example (MyChannel)

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/response/README.md

Example of how to integrate a custom channel adapter within an Action class.

```APIDOC
### Step 2: Integrate with Your Action

In your Action class, create and initialize the adapter in `on_register()`:

```python
from jvagent.action.base import Action
from .my_channel_adapter import MyChannelAdapter

class MyChannelAction(Action):
    """Action for MyChannel integration."""
    
    api_url: Optional[str] = attribute(default=None)
    api_key: Optional[str] = attribute(default=None)
    
    async def on_register(self) -> None:
        """Called when action is registered. 
        
        Creates and initializes the channel adapter for automatic
        message delivery via the response bus.
        """
        # Create adapter instance with action reference
        adapter = MyChannelAdapter(
            channel="mychannel",
            action=self,  # Pass action instance for config access
        )
        
        # Initialize the adapter (gets ResponseBus and registers itself)
        await adapter.initialize()
        
        # Store adapter instance for reference (optional)
        self._channel_adapter = adapter
```
```

--------------------------------

### Run Example Application (Bash)

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/README.md

Demonstrates how to execute the jvagent example application from the command line, either from the repository root or after changing into the example directory.

```bash
# From the jvagent repository root
jvagent examples/jvagent_app

# Or change to the example directory first
cd examples/jvagent_app
jvagent
```

--------------------------------

### Run Bundled Example Application (Bash)

Source: https://github.com/tharickv75/jvagent_/blob/dev/README.md

Executes the example jvagent application. This demonstrates how to run jvagent with a specific application directory and includes options for debug logging and update mode.

```bash
# From the jvagent repository root
jvagent examples/jvagent_app

# With flags:
jvagent examples/jvagent_app --debug
jvagent examples/jvagent_app --update
```

--------------------------------

### Example Action

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/agents/jvagent/example_agent/README.md

Details about the Example Action, which demonstrates custom action development with property configuration, custom endpoints, and lifecycle hooks.

```APIDOC
## Example Action

### Description
Demonstrates custom action development with property configuration, custom endpoints, and lifecycle hooks.
```

--------------------------------

### Agent Action and Channel Management Example (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Illustrates how to manage actions and communication channels for an individual Agent. It shows examples of retrieving specific actions by type (e.g., STTModelAction, TTSModelAction), adding, removing, and checking for the existence of communication channels.

```python
# Memory Management
async def get_memory() -> Optional[Memory]

# Action Management
async def get_actions() -> Optional[List[Action]]
async def get_action(filter: Union[str, Dict], only_enabled: bool = True) -> Optional[Action]
async def get_action_by_type(action_type: type, only_enabled: bool = True) -> Optional[Action]
# Examples:
# await agent.get_action_by_type(STTModelAction)  # Get STT action
# await agent.get_action_by_type(TTSModelAction)  # Get TTS action
# await agent.get_action_by_type(VectorstoreAction)  # Get vectorstore action

# Channel Management
def add_channel(channel: str) -> bool
def remove_channel(channel: str) -> bool
def has_channel(channel: str) -> bool
def validate_channels() -> List[str]

# Configuration
async def update_agent(data: Dict[str, Any], with_actions: bool = False) -> Agent
async def get_descriptor(as_yaml: bool = False, clean: bool = False) -> Union[str, Dict]

# Health & Analytics
async def healthcheck() -> Dict[str, Any]  # Core agent configuration check
async def get_healthcheck_report() -> Dict[str, Any]  # Full health including actions and memory
async def get_metrics() -> Dict[str, Any]  # Agent-specific metrics
async def get_performance_stats() -> Dict[str, Any]  # Performance statistics
```

--------------------------------

### Bootstrap Application Graph (CLI)

Source: https://context7.com/tharickv75/jvagent_/llms.txt

Bootstraps the application graph without starting the server, useful for CI/CD pipelines and initial setup. Supports specifying the app directory and update mode.

```bash
jvagent /path/to/my_jvagent_app bootstrap
jvagent /path/to/my_jvagent_app bootstrap --update
```

--------------------------------

### App Entity Example Usage (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Provides a practical example of how to initialize and use the 'App' entity in Python. It demonstrates creating an App instance and calling its methods to retrieve the agents manager and perform a health check.

```python
# Initialize application
app = await App.create(
    name="Production Agent System",
    version="1.0.0",
    description="Multi-tenant agent platform"
)

# Get agents manager
agents_manager = await app.get_agents_manager()

# System health check
health = await app.healthcheck()
```

--------------------------------

### Python Actions Manager Discovery Example

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Shows a practical example of how to obtain the actions manager instance from an agent and then use it to discover action packages from a specified directory. This is a common pattern for loading custom actions into the agent.

```python
# Get actions manager
actions = await agent.get_actions()

# Discover and register actions
discovered = await actions.discover_action_packages(["/actions"])
```

--------------------------------

### Python Agent Creation and Action Retrieval Example

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Demonstrates how to create an agent from a YAML descriptor and retrieve various components like memory, specific actions by label or type, and health/performance metrics. This example showcases the agent's core functionalities for interaction and monitoring.

```python
# Create agent from YAML descriptor
agent = await Agent.create(
    name="CustomerSupport",
    description="24/7 customer support agent",
    published=True,
    flood_threshold=5
)

# Get memory system
memory = await agent.get_memory()

# Get specific action by label
llm_action = await agent.get_action("OpenAIAction")

# Get action by type (replaces get_tts_action, get_stt_action, etc.)
stt_action = await agent.get_action_by_type(STTModelAction)
tts_action = await agent.get_action_by_type(TTSModelAction)

# Agent-level health check and metrics
health = await agent.get_healthcheck_report()
metrics = await agent.get_metrics()
perf_stats = await agent.get_performance_stats()
```

--------------------------------

### Example Interaction Creation and Usage in Python

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Demonstrates example usage of the Interaction entity in Python. It shows how to create an interaction, add intents and trail information, set a response, and then close and save the interaction.

```python
# Create interaction
interaction = await Interaction.create(
    agent_id=agent.id,
    conversation_id=conversation.id,
    utterance="What's the weather?",
    channel="web"
)

# Process through actions
interaction.add_intent("weather_query")
interaction.trail.append("IntentAction")
interaction.trail.append("WeatherAction")

# Set response
interaction.set_response("The weather is sunny, 72°F")

# Close
interaction.close_interaction()
await interaction.save()
```

--------------------------------

### Install Action via ZIP Archive (API)

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

This endpoint allows for the installation of new actions by uploading a ZIP archive. It is part of the runtime management features of the agent.

```HTTP
POST /v1/actions/install
Content-Type: multipart/form-data

form-data: file (zip)
```

--------------------------------

### jvagent/retrieval_interact_action Configuration Examples

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/retrieval/README.md

Examples demonstrating how to configure the retrieval interact action with score thresholds and custom templates.

```APIDOC
## jvagent/retrieval_interact_action Configuration Examples

### Example 1: With Score Threshold

This example shows how to configure the action to only include results with a minimum score threshold.

```yaml
actions:
  - action: jvagent/retrieval_interact_action
    context:
      enabled: true
      vectorstore_action_type: "TypesenseVectorStore"
      collection: "knowledge_base"
      k: 5
      min_score_threshold: 0.75  # Only include highly relevant results
```

### Example 2: Custom Template

This example demonstrates using a custom template to format the retrieved results.

```yaml
actions:
  - action: jvagent/retrieval_interact_action
    context:
      enabled: true
      vectorstore_action_type: "TypesenseVectorStore"
      collection: "faq"
      k: 3
      directive_template: |
        FAQ Context:
        {results}
        Use these FAQ entries to answer the user's question accurately.
```
```

--------------------------------

### InteractRouter Configuration Example (YAML)

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/router/README.md

Example configuration for the InteractRouter in YAML format. It shows how to enable the action, specify the language model action type, and set the history limit for conversation context.

```yaml
actions:
  - action: jvagent/interact_router
    context:
      enabled: true
      model_action_type: "OpenAILanguageModelAction"
      history_limit: 15
      # Optional static exceptions (dynamic ones come from always_execute=True)
      # exceptions:
      #   - "SomeInteractAction"
```

--------------------------------

### Start jvagent Server (CLI)

Source: https://context7.com/tharickv75/jvagent_/llms.txt

Starts the jvagent server, automatically discovering agents and actions from YAML configuration files. Supports specifying the app directory, enabling update mode, debug logging, and database purging.

```bash
jvagent
jvagent /path/to/my_jvagent_app
jvagent /path/to/my_jvagent_app --update
jvagent /path/to/my_jvagent_app --debug
jvagent /path/to/my_jvagent_app --purge
```

--------------------------------

### Install jvagent Dependencies

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/SETUP.md

Installs the necessary Python dependencies for the jvagent application using pip. It assumes a requirements.txt file exists or lists the core dependencies.

```bash
cd /path/to/jvagent_app
pip install -r requirements.txt
```

--------------------------------

### Agent Registration and Discovery Example (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Demonstrates how to interact with the Agents manager to register a new agent and discover existing agents by name. It shows obtaining the agents manager instance, creating an Agent object, registering it, and then retrieving it using its name.

```python
# Get agents manager
agents = await app.get_agents_manager()

# Register a new agent
agent = await Agent.create(name="CustomerSupport")
await agents.register_agent(agent)

# Find agent by name
support_agent = await agents.get_agent_by_name("CustomerSupport")

# List all active agents
active = await agents.list_agents({"context.published": True})  # Use context. prefix for field queries
```

--------------------------------

### Get Action Metrics

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/SETUP.md

Retrieves performance metrics for a specific action, including request counts, token usage, and estimated costs.

```APIDOC
## GET /actions/{action_id}/metrics

### Description
Retrieves performance metrics for a specific action identified by `action_id`. This includes the total number of requests, total tokens processed, and the estimated cost incurred.

### Method
GET

### Endpoint
`/actions/{action_id}/metrics`

### Parameters
#### Path Parameters
- **action_id** (string) - Required - The unique identifier for the action.

### Request Example
```bash
curl http://localhost:8000/actions/{action_id}/metrics
```

### Response
#### Success Response (200)
- **total_requests** (integer) - The total number of requests made for the action.
- **total_tokens** (integer) - The total number of tokens processed by the action.
- **total_cost** (float) - The estimated total cost in USD.
- **model** (string) - The AI model used for the action.

#### Response Example
```json
{
  "total_requests": 150,
  "total_tokens": 45000,
  "total_cost": 0.675,
  "model": "gpt-4o"
}
```
```

--------------------------------

### Get Available Models API Endpoint (JSON)

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/tts_action/README.md

Example JSON response for the GET /actions/{action_id}/tts/models endpoint, detailing the available speech synthesis models.

```json
{
  "models": [
    {
      "name": "Eleven Turbo v2",
      "model_id": "eleven_turbo_v2",
      "description": "Fast, high-quality model"
    }
  ],
  "provider": "elevenlabs",
  "current_model": "eleven_turbo_v2"
}
```

--------------------------------

### Get Available Voices API Endpoint (JSON)

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/tts_action/README.md

Example JSON response for the GET /actions/{action_id}/tts/voices endpoint, listing available voices for the configured TTS provider.

```json
{
  "voices": [
    {
      "name": "Sarah",
      "voice_id": "abc123",
      "category": "premade"
    }
  ],
  "provider": "elevenlabs",
  "current_voice": "Sarah"
}
```

--------------------------------

### Top-Level Action Routing Example

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/interact/README.md

Illustrates how top-level InteractActions must explicitly route the walker to child actions.

```APIDOC
## Top-Level Action Routing

While interact actions may have branches of other interact actions, **top-level interact actions** (that is, the actions directly connected to the Actions branch node) **must employ logic to further route the interact walker to its children** (since this may always be done conditionally) instead of having it done automatically.

This means that if your top-level InteractAction has child InteractActions connected to it, you must explicitly route the walker to those children within your `execute()` method:

```python
class MyTopLevelAction(InteractAction):
    async def execute(self, visitor: InteractWalker) -> None:
        # Perform action logic
        # ...
        
        # Explicitly route to child actions conditionally
        if some_condition:
            child_action = await self.node(node="ChildInteractAction")
            if child_action:
                await visitor.visit(child_action)
```

**Important:** The walker will NOT automatically traverse child InteractActions from top-level actions. This design allows for conditional routing based on the action's internal logic and state.
```

--------------------------------

### Example API Calls for Action Management (Bash)

Source: https://github.com/tharickv75/jvagent_/blob/dev/README.md

Demonstrates how to interact with the jvagent API to manage actions. These examples cover listing all actions, retrieving a specific action, enabling an action, and updating an action's properties. They require an authorization token and specify the content type and data for PUT requests.

```bash
# List all actions
curl -X GET "http://localhost:8000/actions" \
  -H "Authorization: Bearer {token}"

# Get specific action
curl -X GET "http://localhost:8000/actions/{action_id}" \
  -H "Authorization: Bearer {token}"

# Enable action
curl -X POST "http://localhost:8000/actions/{action_id}/enable" \
  -H "Authorization: Bearer {token}"

# Update action
curl -X PUT "http://localhost:8000/actions/{action_id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Updated description"
  }'
```

--------------------------------

### Health Check API Endpoint (JSON)

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/tts_action/README.md

Example JSON response for the GET /actions/{action_id}/tts/health endpoint, indicating the health status of the TTS service.

```json
{
  "healthy": true,
  "provider": "elevenlabs",
  "model": "eleven_turbo_v2",
  "voice": "Sarah"
}
```

--------------------------------

### POST /actions/{action_id}/query (Model Action API)

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/SETUP.md

This endpoint allows you to query the model action, supporting both text-only and multimodal (text with image) prompts.

```APIDOC
## POST /actions/{action_id}/query

### Description
Query the model action with text or multimodal prompts.

### Method
POST

### Endpoint
`/actions/{action_id}/query`

### Parameters
#### Path Parameters
- **action_id** (string) - Required - The ID of the model action to query.

#### Query Parameters
None

#### Request Body
- **prompt** (string | array) - Required - The prompt for the model. Can be a string for text-only or an array of objects for multimodal prompts (e.g., `[{'type': 'text', 'text': '...'}, {'type': 'image_url', 'image_url': {'url': '...'}}]`).
- **temperature** (number) - Optional - Controls randomness. Lower values make output more focused and deterministic.

### Request Example
```json
{
  "prompt": "Explain quantum computing in simple terms",
  "temperature": 0.7
}
```

```json
{
  "prompt": [
    {"type": "text", "text": "What is in this image?"},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
  ]
}
```

### Response
#### Success Response (200)
- **response** (string | object) - The model's response to the query.

#### Response Example
```json
{
  "response": "Quantum computing harnesses quantum mechanics principles like superposition and entanglement to perform calculations."
}
```
```

--------------------------------

### Example Usage of jvagent User Model

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Illustrates how to create or retrieve a user, initiate a new conversation with that user, and record their activity using the jvagent User model's methods.

```python
# Create or get user
user = await User.create(
    user_id="ext_user_123",
    username="johndoe",
    email="john@example.com",
    preferred_channel="whatsapp"
)

# Create conversation
conversation = await user.create_conversation()

# Track activity
await user.record_activity()
```

--------------------------------

### Example: Initializing the Interact Walker (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

This Python code snippet illustrates how to initialize the Interact walker, which serves as the main entry point for processing user interactions within the agent system. It shows the instantiation of the walker with necessary parameters like agent ID, session ID, and the user's utterance.

```python
# Create walker
walker = Interact(
    agent_id=agent.id,
    session_id="user_123_session",
    utterance="What's the weather today?",
    channel="web",
    verbose=True
)
```

--------------------------------

### Query OpenAI Model Action from Python

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/SETUP.md

Shows how to interact with the OpenAI language model action from within another Python action in jvagent. It covers both text and vision queries using the `OpenAILanguageModelAction` class.

```python
from jvagent.action.model.language.openai import OpenAILanguageModelAction

class MyAction(Action):
    async def my_method(self):
        # Get the model action (use actual ID or find by label)
        model = await OpenAILanguageModelAction.find_one({"context.label": "openai_lm"})
        
        # Text query
        result = await model.query_sync("Hello, how are you?")
        response = await result.get_response()
        
        # Vision query
        content = model.create_image_content(
            text="What's in this image?",
            image_url="https://example.com/image.jpg"
        )
        result = await model.query_sync(content)
        response = await result.get_response()
```

--------------------------------

### Configure jvagent OpenAI LM Action in YAML

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/SETUP.md

Illustrates the YAML configuration for the `jvagent/openai_lm` core action within the `agent.yaml` file. It specifies parameters like model, temperature, max tokens, and API key.

```yaml
actions:
  # Core action from jvagent library
  - action: jvagent/openai_lm
    context:
      enabled: true
      model: gpt-4o  # Change model here
      temperature: 0.7  # Adjust temperature
      max_tokens: 2000  # Adjust max tokens
      api_key: ${OPENAI_API_KEY}  # From .env file
```

--------------------------------

### Conditional Routing in Top-Level InteractAction (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/interact/README.md

Demonstrates how top-level InteractActions must explicitly route the InteractWalker to child actions. This example shows conditional routing based on 'some_condition' and ensures the walker visits child actions when necessary.

```python
class MyTopLevelAction(InteractAction):
    async def execute(self, visitor: InteractWalker) -> None:
        # Perform action logic
        # ...
        
        # Explicitly route to child actions conditionally
        if some_condition:
            child_action = await self.node(node="ChildInteractAction")
            if child_action:
                await visitor.visit(child_action)
```

--------------------------------

### Install Agent Action at Runtime (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Installs an agent action at runtime via a POST request. It validates the agent, discovers the action package, checks dependencies, and registers the action. Dependencies: Agent class, discover_action_package, check_action_dependencies, create_action_from_package. Input: agent_id, action_package, config, enable. Output: JSON response indicating success or failure with action details.

```python
@endpoint("/api/agents/{agent_id}/actions/install", methods=["POST"])
async def install_action(
    agent_id: str,
    action_package: str,
    config: Dict[str, Any] = None,
    enable: bool = True,
    endpoint = None
) -> Any:
    """Install an action at runtime."""
    
    # Validate agent exists
    agent = await Agent.get(agent_id)
    if not agent:
        return endpoint.not_found(message="Agent not found")
    
    # Get actions manager
    actions = await agent.get_actions()
    
    # Discover action from package
    action_info = await discover_action_package(action_package)
    if not action_info:
        return endpoint.not_found(message="Action package not found")
    
    # Check dependencies
    deps_met = await check_action_dependencies(action_info)
    if not deps_met:
        return endpoint.unprocessable_entity(
            message="Action dependencies not met",
            details={"missing": deps_met.get("missing", [])}
        )
    
    # Install action
    action = await create_action_from_package(action_info, config)
    
    # Register
    if await actions.register_action(action):
        # Enable if requested
        if enable:
            await actions.enable_action(action.label)
        
        return endpoint.created(
            data={
                "label": action.label,
                "class": await action.get_type(),
                "enabled": action.enabled
            },
            message="Action installed successfully"
        )
    
    return endpoint.error(
        message="Failed to register action",
        status_code=500
    )
```

--------------------------------

### Query Logs by Agent ID (HTTP API)

Source: https://github.com/tharickv75/jvagent_/blob/dev/docs/error-logging.md

An HTTP GET endpoint to query logs, primarily filtered by agent ID. Supports pagination and filtering by category, start date, and end date. Authentication is required.

```http
GET /api/logs?agent_id=agent_123&page=1&page_size=50
```

--------------------------------

### Query OpenAI Model Action via API

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/SETUP.md

Demonstrates how to send text and vision queries to the jvagent OpenAI model action endpoint using cURL. It shows the expected JSON payload structure for each query type.

```bash
# Text query
curl -X POST http://localhost:8000/actions/{action_id}/query \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain quantum computing in simple terms",
    "temperature": 0.7
  }'

# Vision query
curl -X POST http://localhost:8000/actions/{action_id}/query \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": [
      {"type": "text", "text": "What is in this image?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
    ]
  }'
```

--------------------------------

### Basic Configuration Example

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/retrieval/README.md

Presents a minimal YAML configuration for RetrievalInteractAction, focusing on essential settings like the action path, enabling the action, specifying the vector store collection, and the number of results (k).

```yaml
actions:
  - action: jvagent/retrieval_interact_action
    context:
      enabled: true
      vectorstore_action_type: "TypesenseVectorStore"
      collection: "docs"
      k: 10
```

--------------------------------

### Configuration: Action-Level (info.yaml)

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/model/README.md

Example of action-level configuration in `info.yaml`. Specifies package name, archetype (e.g., OpenAILanguageModelAction), and version.

```yaml
package:
  name: jvagent/model_openai
  archetype: OpenAILanguageModelAction
  version: 0.0.1
```

--------------------------------

### Example Action Custom Endpoint

Source: https://github.com/tharickv75/jvagent_/blob/dev/examples/jvagent_app/agents/jvagent/example_agent/actions/jvagent/example_interact_action/README.md

Demonstrates how to define a custom POST endpoint for the Example Action using the @endpoint decorator.

```APIDOC
## POST /actions/{action_id}/my_endpoint

### Description
This is a custom endpoint for the Example Action that accepts an action ID and performs specific logic.

### Method
POST

### Endpoint
/actions/{action_id}/my_endpoint

### Parameters
#### Path Parameters
- **action_id** (string) - Required - The unique identifier of the action.

#### Query Parameters
None

#### Request Body
None explicitly defined in the example, but can be added as needed.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the endpoint was reached.

#### Response Example
```json
{
  "message": "Endpoint reached successfully"
}
```
```

--------------------------------

### Install jvagent from Distribution (Bash)

Source: https://github.com/tharickv75/jvagent_/blob/dev/README.md

Installs jvagent from a pre-built Python wheel distribution file. This is a simpler installation method if you have a compiled package.

```bash
pip install dist/jvagent-*.whl
```

--------------------------------

### App Entity Key Methods (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Illustrates the key asynchronous methods available for interacting with the 'App' entity. These methods allow for retrieving related managers, configuration, and system status information.

```python
async def get_agents_manager() -> Agents
async def get_configuration() -> Dict[str, Any]
async def set_maintenance_mode(enabled: bool) -> bool
async def healthcheck() -> Dict[str, Any]  # System-wide health aggregation
async def get_metrics() -> Dict[str, Any]  # System-wide metrics aggregation
async def get_agent_health_summary() -> Dict[str, Any]  # Per-agent health status
```

--------------------------------

### OpenTelemetry Distributed Tracing Setup (Python)

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Demonstrates the integration of OpenTelemetry for distributed tracing. It shows how to initialize a tracer and create spans to track the execution flow of the `process_interaction` function, including nested operations.

```python
from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer("jvagent")

async def process_interaction(agent_id: str, utterance: str):
    """Process interaction with distributed tracing."""
    
    with tracer.start_as_current_span("interaction.process") as span:
        # Add attributes
        span.set_attribute("agent.id", agent_id)
        span.set_attribute("utterance.length", len(utterance))
        
        try:
            # Get agent
            with tracer.start_as_current_span("agent.get"):
                agent = await Agent.get(agent_id)
            
            # Process through actions
            with tracer.start_as_current_span("actions.execute") as action_span:
                actions = await agent.get_actions()
                action_span.set_attribute("action.count", len(actions))
                
                for action in actions:
                    with tracer.start_as_current_span(
                        f"action.{action.label}",
                        attributes={
                            "action.label": action.label,
                            "action.type": await action.get_type()
                        }
                    ):
                        await action.execute(interaction, {{}})
            
            # Success
            span.set_status(Status(StatusCode.OK))
            
        except Exception as e:
            # Error tracking
            span.set_status(Status(StatusCode.ERROR))
            span.record_exception(e)
            raise
```

--------------------------------

### Install Development Dependencies (Bash)

Source: https://github.com/tharickv75/jvagent_/blob/dev/README.md

Command to install the development dependencies for the jvagent project. This command uses pip with the editable install option and specifies the development extras.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Example Configuration for RetrievalInteractAction

Source: https://github.com/tharickv75/jvagent_/blob/dev/jvagent/action/retrieval/README.md

Provides a sample YAML configuration for setting up RetrievalInteractAction, specifying the action type, enabling it, and configuring vector store details like action type, collection, number of results (k), weight, and minimum score threshold.

```yaml
actions:
  - action: jvagent/retrieval_interact_action
    context:
      enabled: true
      vectorstore_action_type: "TypesenseVectorStore"
      collection: "knowledge_base"
      k: 5
      weight: -50
      min_score_threshold: 0.7
```

--------------------------------

### Subscribe to System Events with Python Actions

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Demonstrates how an Action class can subscribe to system events like 'interaction_started' and 'interaction_completed' during its registration phase. It also shows how to handle incoming events in the on_event method, logging relevant information.

```python
class EventAwareAction(Action):
    """Action that responds to system events."""
    
    async def on_register(self):
        """Subscribe to events during registration."""
        
        # Subscribe to events
        await self.subscribe_event("interaction_started")
        await self.subscribe_event("interaction_completed")
    
    async def on_event(self, event_name: str, event_data: Dict):
        """Handle system events."""
        
        if event_name == "interaction_started":
            logger.info(
                "action_notified",
                action=self.label,
                event=event_name,
                interaction_id=event_data.get("interaction_id")
            )
```

--------------------------------

### Action Details API

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Endpoints for retrieving details of installed actions and listing all installed actions.

```APIDOC
## GET /v1/actions

### Description
List all installed actions.

### Method
GET

### Endpoint
/v1/actions

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter actions by type (e.g., `interact`).

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - Confirmation message.
- **data** (array) - An array of installed action objects.

#### Response Example
```json
{
  "success": true,
  "message": "Actions listed successfully",
  "data": [
    { ... action object ... }
  ]
}
```
```

```APIDOC
## GET /v1/actions/{action_id}

### Description
Get details of a specific installed action.

### Method
GET

### Endpoint
/v1/actions/{action_id}

### Parameters
#### Path Parameters
- **action_id** (string) - Required - The ID of the action to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - Confirmation message.
- **data** (object) - Contains the details of the action.

#### Response Example
```json
{
  "success": true,
  "message": "Action details retrieved successfully",
  "data": { ... action object ... }
}
```
```

--------------------------------

### POST /api/agents/{agent_id}/actions/install

Source: https://github.com/tharickv75/jvagent_/blob/dev/REF/README.md

Installs an action package for a specified agent at runtime. It handles validation, dependency checks, and registration of the action.

```APIDOC
## POST /api/agents/{agent_id}/actions/install

### Description
Installs an action package for a specified agent at runtime. It handles validation, dependency checks, and registration of the action.

### Method
POST

### Endpoint
/api/agents/{agent_id}/actions/install

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

#### Query Parameters
- **action_package** (string) - Required - The name or path of the action package to install.
- **config** (object) - Optional - Configuration settings for the action.
- **enable** (boolean) - Optional - Whether to enable the action after installation (defaults to true).

### Request Body
```json
{
  "action_package": "com.example.actions.my_action",
  "config": {
    "setting1": "value1"
  },
  "enable": true
}
```

### Response
#### Success Response (201 Created)
- **label** (string) - The registered label of the installed action.
- **class** (string) - The class name of the action.
- **enabled** (boolean) - The enabled status of the action.

#### Response Example
```json
{
  "data": {
    "label": "my_action",
    "class": "com.example.actions.MyAction",
    "enabled": true
  },
  "message": "Action installed successfully"
}
```

#### Error Responses
- **404 Not Found**: Agent or Action package not found.
- **422 Unprocessable Entity**: Action dependencies not met.
```