Wabee Agent Core API (v2.8.0)

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.

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: every SSE frame carries a v1 stream event (see docs/api/streaming_events.md and docs/api/streaming_events.v1.schema.json) Note: the stream ends with exactly one terminal frame of type "done" or "error" Note: All headers starting with stix will be sent as context for tools.

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

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.

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:

{
    "configuration": {
        "description": "Updated agent description"
    },
    "validate_only": false
}

Update a specific LLM model:

{
    "configuration": {
        "llms": {
            "primary": {
                "model": "gpt-4-turbo"
            }
        }
    },
    "validate_only": false
}

Add a new tool to the existing tools list:

{
    "configuration": {
        "tools": [
            {
                "name": "new_tool",
                "config": {...}
            }
        ]
    },
    "validate_only": false
}

In-memory only update (for read-only config files):

{
    "configuration": {
        "max_execution_time": 2000
    },
    "validate_only": false,
    "in_memory_only": true
}

Returns metadata information about the agent configuration, including its description, capabilities and conversation starters.

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.

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.

Returns quantitative information about agent runs for monitoring. The following metrics are provided:

• status_value_counts (histogram)
• total_requests
• total_errors
• total_tokens
• mean_tokens
• mean_latency
• max_latency
• min_latency
• total_prompt_tokens
• mean_prompt_tokens
• total_completion_tokens
• mean_completion_tokens

Returns run execution logs in stringify format. The logs contain the following fields:

• name: run name
• id: run unique identifier
• model: model name
• error: run error if exists, else null
• status: run status
• latency: run latency
• end_time: terminated run timestamp
• completion_tokens: number of tokens returned by the model when the run is finished
• total_tokens: total number of tokens associated with the run

The results are paginated. Use offset and limit parameters to navigate through pages.

Returns the health status of the API

Returns a hierarchical, step-based execution trace for a session.

This endpoint transforms flat streaming events into a structured format ideal for auditing, transparency, and debugging.

Key features:

• Groups events by execution steps (agent phases)
• Extracts tool call information with inputs/outputs
• Provides timing information for each step
• Supports filtering by specific request_id

Response structure:

• execution_summary: Overall statistics (duration, step count, tool calls)
• requests: List of request traces (a session may have multiple requests)
• user_messages: The user inputs that triggered execution
• errors: Any errors encountered

Each request contains:

• steps: Hierarchical execution steps
• status: Request status (completed, error, streaming)
• duration_ms: Total request duration
• total_tool_calls: Number of tools invoked

Each step contains:

• step_name: The agent phase (PLANNING, REASONING, TOOL_EXECUTION, etc.)
• type: Step type (generation, tool_call, flow-status-update)
• content: Full concatenated content generated in this step
• tool: Tool call details if applicable
• duration_ms: Step duration

Query parameters:

• request_id: Filter to a specific request within the session
• max_content_length: Optional max length to truncate content (default: full content)

Retrieves the complete session data including user messages and streaming events from agent execution.

The response includes the same schema as the live streaming endpoint (/chain_streaming), allowing you to replay the agent's execution flow with all intermediate steps.

The session data includes:

• User input messages that triggered the agent execution
• Streaming events from agent execution (same as live stream)
• Total event count
• Session metadata with timestamp

User messages contain:

• role: 'human' (user input)
• content: The user's input message
• timestamp: When the message was sent (Unix timestamp in seconds)

Each streaming event is a v1 wire event payload (see docs/api/streaming_events.md):

• v: Contract version (1)
• type: Semantic event type (text-delta, reasoning-delta, plan-delta, ...)
• ts: Milliseconds since Unix epoch
• source: {type, id, name} of the producing agent
• step: Display phase (PLANNING, REASONING, ...)
• request_id: The request the event belongs to
• plus the type-specific payload field (text, message, plan, ...)

Note: This endpoint returns events in the same format as the /chain_streaming endpoint, making historical and live data consistent. Legacy sessions recorded before the v1 contract are reduced to text-delta events carrying the conversational text only.

Returns a paginated list of all available chat sessions.

The response includes:

• List of session summaries
• Pagination information
• Total count of returned sessions

Each session summary contains:

• session_id: Unique identifier for the session
• checkpoint_id: Internal reference ID
• short_name: Brief description based on first message

Use the query parameters to navigate through pages:

• before: Get sessions before this session ID
• limit: Number of sessions per page (1-50)

Sessions are ordered by most recent first. Empty sessions (no messages) are automatically filtered out.

Set an HttpOnly authentication cookie for WebSocket connections.

This endpoint receives a JWT token via the Authorization header and sets it as an HttpOnly cookie. This is necessary because the browser's WebSocket API doesn't support custom headers, but cookies are automatically sent with the WebSocket handshake request.

The cookie is configured with security best practices:

• HttpOnly: Prevents JavaScript access (XSS protection)
• Secure: Only sent over HTTPS
• SameSite=Strict: CSRF protection
• Domain selected by Origin header:
  • .wabee.ai for https://*.wabee.ai origins
  • .usuro.ai for https://*.usuro.ai origins
  • fallback to .wabee.ai for other origins
• Path=/: Available for all paths

Args: authorization: The Authorization header containing "Bearer " origin: Optional request Origin used to select cookie domain

Returns: JSONResponse with Set-Cookie header

Lists all sub-agents that have been created by the parent agent.

Creates a new specialized sub-agent that can handle specific tasks. The sub-agent will have access to the specified tools and can be assigned tasks.

Retrieves information about a specific sub-agent, including its status and basic information.

Terminates a specific sub-agent and cleans up its resources.

Returns a list of all available tools that the agent has access to.

Each tool entry includes:

• Name: Unique identifier for the tool
• Description: What the tool does and how it can be used
• Status: Current initialization status (ready, initializing, error)
• Schema: JSON schema defining the input parameters for the tool

Use this endpoint to discover available tools and their required parameters before using the /tool/execute endpoint.

Authentication

Requires API key via x-wabee-access header.

This endpoint allows direct execution of a specific tool with given parameters.

The tool is executed outside the normal agent conversation flow, allowing users to:

• Invoke tools programmatically
• Test tool functionality independently
• Access tool capabilities without engaging the full agent

Each tool has different input parameters. Refer to tool documentation for specific input schemas.

Authentication

Requires API key via x-wabee-access header.

Example Tool Inputs

Web Search:

{
    "tool_name": "web_search",
    "tool_input": {
        "query": "Latest market trends in AI"
    }
}

CSV Search:

{
    "tool_name": "csv_search",
    "tool_input": {
        "file_path": "data/sales.csv",
        "query": "Find total sales in Q1"
    }
}

Upload a Google Service Account JSON credential for an MCP tool.

Remove a Google Service Account credential for an MCP tool.

Remove an OAuth token and credential file for an MCP tool.

Subscribe to events from an existing streaming session.

This endpoint allows multiple clients to receive the same SSE events that were sent to the original client who initiated the request. Use cases include:

• Live monitoring: Watch an ongoing agent execution from the frontend
• Replay: Retrieve all events from a completed session
• Late join: Start receiving events mid-stream with optional catch-up

Parameters

• session_id (path): The session identifier
• request_id (query, optional): Specific request to subscribe to. If not provided, subscribes to the latest request for the session
• from_sequence (query, optional): Start from a specific event sequence number. 0 = from beginning, -1 = live only (no history)

Event Stream Behavior

1. Historical events: If from_sequence >= 0, sends all past events first
2. Live events: Then streams real-time events via MongoDB Change Streams
3. Completion: Stream ends when the session completes or errors

Example Usage

const eventSource = new EventSource('/api/v1/sessions/abc123/stream?from_sequence=0');
eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data.replace('data: ', ''));
    if (data.type === 'text-delta') console.log('Text:', data.text);
};

Note: Requires MongoDB replica set configuration for Change Streams support. Events are retained for 1 day before automatic cleanup.

Returns a list of all currently running streaming sessions.

This endpoint is useful for:

• Monitoring active agent executions
• Building dashboards to show running jobs
• Finding streams to subscribe to

Each active stream includes:

• Session and request identifiers
• Current status (streaming, initializing)
• Start time and duration
• Number of events published so far

Retrieves the history of streaming sessions for a given session ID.

Returns metadata about past streams including:

• Stream status (completed, error, streaming)
• Start and completion times
• Total number of events
• Any error messages

Useful for:

• Auditing past executions
• Debugging failed streams
• Understanding session activity patterns

List all currently active skills.

Add or replace a skill at runtime. Takes effect immediately — no agent restart needed.

Remove a skill at runtime. Takes effect immediately — no agent restart needed.

Get a specific skill definition.