# Agent

Endpoints for interacting with the AI agent

## Demand from the agent and get a full response when it finishes

 - [POST /core/v1/chain](https://api.docs.wabee.ai/openapi/agent/chain_core_v1_chain_post.md): Executes a chain of AI-powered reasoning and actions to respond to a given query or task.
    
    The agent leverages its configured tools and knowledge to:
    - Analyze the input query
    - Plan necessary steps
    - Execute relevant tools
    - Synthesize a comprehensive response
    
    ## Image Support
    Include images in your request using the images field:
    - Base64 Format: Set type="base64" with base64-encoded image data
    - File Path: Set type="file_path" with path to existing image
    
    Maximum 5 images per request. Invalid images will trigger a 400 response.
    
    ## Authentication
    Requires API key via x-wabee-access header.
    
    ## Session Management
    Use session-id header to maintain conversation context across requests.

## Demand from the agent and get a streamed response until it finishes

 - [POST /core/v1/chain_streaming](https://api.docs.wabee.ai/openapi/agent/chain_core_v1_chain_streaming_post.md): Requests Wabee AI Agent to answer a question regarding the mission that the agent was given to upon creation.
    
    The agent can make use of any of the available tools along with its own reasoning to complete the given task, depending on its complexity, the response might take some time to be returned to the user.
    
    Note: session_id field on request body is kept for compatibility purposes, it will be overwritten with the header value during request processing
    Note: stream filed on request body is kept for compatibility purposes, it will be ignored during request processing
    Note: this is pretty much the same as in /chain, the only difference is that this endpoint returns a streaming response instead of a JSON object
    Note: the id on the streamming response refers to the current request
    Note: the streamming response ends when finish_reason is different than null
    Note: All headers starting with stix will be sent as context for tools.

## Demand from the agent and get a fast ack response, use callback to receive the completion response

 - [POST /core/v1/chain_async](https://api.docs.wabee.ai/openapi/agent/async_chain_core_v1_chain_async_post.md): Requests Wabee AI Agent to answer a question asynchronously.
    If a callback_url is provided, the agent will send the response to the given URL.
    
    The agent can make use of any of the available tools along with its own reasoning to complete the given task, depending on its complexity, the response might take some time to be returned to the user.
    
    Note: session_id field on request body is kept for compatibility purposes, it will be overwritten with the header value during request processing
    Note: stream filed on request body is kept for compatibility purposes, it will be ignored during request processing

## Get agent configuration

 - [GET /core/v1/agent/config](https://api.docs.wabee.ai/openapi/agent/get_agent_config_core_v1_agent_config_get.md): Returns the current agent configuration.
    
    This endpoint allows you to retrieve the complete agent configuration 
    that is currently loaded in memory. This includes all settings such as:
    - Agent description and metadata
    - LLM configurations
    - Tool definitions
    - Memory settings
    - Other agent-specific parameters
    
    The configuration returned is the actual configuration being used by the agent,
    including any updates that have been applied via the PUT /agent/config endpoint.

## Update agent configuration

 - [PUT /core/v1/agent/config](https://api.docs.wabee.ai/openapi/agent/update_agent_config_core_v1_agent_config_put.md): Updates the agent configuration dynamically without restarting the service.
    
    This endpoint allows you to:
    - Partially update the agent configuration (merges with existing config)
    - Update complete configuration sections or individual fields
    - Validate configuration before applying (using validate_only=true)
    - Automatically trigger agent re-initialization with new config
    
    The provided configuration is merged with the existing configuration, so you only 
    need to specify the fields you want to change. The configuration is written to the 
    mounted volume and the agent is re-initialized.
    
    ## Important Notes:
    - Only specify the fields you want to update - they will be merged with existing config
    - Nested objects are deep-merged (e.g., updating llms.primary.model preserves other llm settings)
    - The JSON file on the mounted volume will be updated with the merged configuration
    - The agent will be re-initialized, which may take a few seconds
    - In-flight requests will complete with the old configuration
    - New requests will use the updated configuration
    - A backup of the previous configuration is automatically created
    
    ## Example Partial Updates:
    
    Update just the agent description:
    json
    {
        "configuration": {
            "description": "Updated agent description"
        },
        "validate_only": false
    }
    
    
    Update a specific LLM model:
    json
    {
        "configuration": {
            "llms": {
                "primary": {
                    "model": "gpt-4-turbo"
                }
            }
        },
        "validate_only": false
    }
    
    
    Add a new tool to the existing tools list:
    json
    {
        "configuration": {
            "tools": [
                {
                    "name": "new_tool",
                    "config": {...}
                }
            ]
        },
        "validate_only": false
    }
    
    
    In-memory only update (for read-only config files):
    json
    {
        "configuration": {
            "max_execution_time": 2000
        },
        "validate_only": false,
        "in_memory_only": true
    }

## Get wabee AI agent metadata

 - [GET /core/v1/metadata](https://api.docs.wabee.ai/openapi/agent/get_metadata_core_v1_metadata_get.md): Returns metadata information about the agent configuration, including its description,
    capabilities and conversation starters.

## Share an artifact generated by the agent

 - [POST /core/v1/share_agent_artifact](https://api.docs.wabee.ai/openapi/agent/share_agent_artifact_core_v1_share_agent_artifact_post.md): Copies a file artifact generated by the agent to a shared location.
    
    This endpoint:
    1. Retrieves the session state using the provided session ID
    2. Gets the specified message by its index in the messages array
    3. Retrieves the generated_artifacts field from the message response_metadata
    4. Copies the file at the specified artifact index to /tmp/share
    
    Returns the path to the copied file or an error if the file cannot be found/copied.

## Generate a downloadable link for an artifact

 - [GET /core/v1/download_artifact/{message_index}/{artifact_index}](https://api.docs.wabee.ai/openapi/agent/download_artifact_core_v1_download_artifact__message_index___artifact_index__get.md): Generates a downloadable link for a file artifact created by the agent.
    
    This endpoint:
    1. Retrieves the session state using the provided session ID (from the 'session-id' header)
    2. Gets the specified message by its index in the messages array
    3. Retrieves the generated_artifacts field from the message response_metadata
    4. Generates a presigned URL for the file at the specified artifact index
    
    Returns the presigned URL that can be used to download the file directly.