Skip to main content

routes.configure

FastAPI routes for frontend configuration.

SandboxStatus Objects​

class SandboxStatus(BaseModel)

Code sandbox status.

For two-container setups (Kubernetes), the mcp_proxy_url enables the Jupyter kernel to call MCP tools via HTTP to the agent-runtimes container.

variant​

"eval" or "jupyter"

CodemodeStatus Objects​

class CodemodeStatus(BaseModel)

Codemode status response.

CodemodeToggleRequest Objects​

class CodemodeToggleRequest(BaseModel)

Request to toggle codemode.

get_tool_approvals_disabled​

def get_tool_approvals_disabled() -> bool

Return whether tool approvals are disabled for new agent launches.

This reflects process-local runtime state (a module-level flag mirrored to an env var); it does not propagate across multiple uvicorn workers or pods unless backed by shared storage.

set_tool_approvals_disabled​

def set_tool_approvals_disabled(disabled: bool) -> bool

Update runtime tool approvals disable flag (process-local) and mirror to env.

The flag is stored in process-local state and an env var, so it does not propagate across multiple uvicorn workers or pods unless backed by shared storage.

get_inference_provider_override​

def get_inference_provider_override() -> InferenceProvider | None

Return explicit runtime override (if user changed provider at runtime).

get_effective_inference_provider​

def get_effective_inference_provider() -> InferenceProvider

Resolve effective inference provider from override/env/defaults.

get_node_mode​

@router.get("/node")
async def get_node_mode() -> dict[str, Any]

Return whether Agent Node mode is enabled for this server process.

set_node_mode​

@router.put("/node")
async def set_node_mode(body: NodeModeRequest) -> dict[str, Any]

Set Agent Node mode flag in env (applies fully after server restart).

get_inference_provider​

@router.get("/inference/provider")
async def get_inference_provider() -> dict[str, Any]

Return the effective runtime inference provider.

get_tool_approvals​

@router.get("/tool-approvals")
async def get_tool_approvals() -> dict[str, Any]

Return whether tool approvals are disabled for subsequent agent launches.

set_tool_approvals​

@router.put("/tool-approvals")
async def set_tool_approvals(body: ToolApprovalsRequest) -> dict[str, Any]

Enable or disable tool approval flows for subsequent agent launches.

set_inference_provider​

@router.put("/inference/provider")
async def set_inference_provider(
        body: InferenceProviderRequest) -> dict[str, Any]

Update runtime inference provider used for subsequent agent launches.

list_inference_models​

@router.get("/inference/models")
async def list_inference_models() -> dict[str, Any]

List available models for the current inference provider.

get_configuration​

@router.get("", response_model=FrontendConfig)
async def get_configuration(
        mcp_url: str | None = Query(
            None,
            description="MCP server URL to fetch tools from",
        ),
        mcp_token: str | None = Query(
            None,
            description="Authentication token for MCP server",
        ),
        agent_id: str | None = Query(
            None,
            description="Agent ID to resolve agent-specific default model",
        )) -> Any

Get frontend configuration.

Returns configuration information for the frontend:

  • Available models
  • Builtin tools (fetched from MCP server if URL provided)
  • MCP servers

get_toolsets_info​

@router.get("/mcp-toolsets-info")
async def get_toolsets_info() -> list[dict[str, Any]]

Get information about running config MCP toolsets.

Returns:

List of running MCP server information (sensitive data redacted).

get_agent_context_details​

@router.get("/agents/{agent_id:path}/context-details")
async def get_agent_context_details(agent_id: str = Path(
    ...,
    description="Agent ID to get context details for",
)) -> dict[str, Any]

Get context usage details for a specific agent.

Returns context information including:

  • Total tokens available (context window)
  • Used tokens
  • Breakdown by category (messages, tools, system, cache)

Arguments:

  • agent_id - The unique identifier of the agent.

Returns:

Context usage details for the agent.

get_agent_cost_usage_endpoint​

@router.get("/agents/{agent_id:path}/cost-usage")
async def get_agent_cost_usage_endpoint(agent_id: str = Path(
    ...,
    description="Agent ID to get cost usage for",
)) -> dict[str, Any]

Get current cost usage for a specific agent.

Returns per-run and cumulative costs, token totals, model breakdown, and recent per-run trace records.

get_agent_context_table_endpoint​

@router.get("/agents/{agent_id:path}/context-table")
async def get_agent_context_table_endpoint(agent_id: str = Path(
    ...,
    description="Agent ID to get context table for",
),
                                           show_context: bool = True
                                           ) -> dict[str, Any]

Render the context snapshot table as plain text.

Arguments:

  • agent_id - The unique identifier of the agent.
  • show_context - Whether to include the CONTEXT section.

Returns:

A dict containing the rendered table text.

reset_agent_context​

@router.post("/agents/{agent_id:path}/context-details/reset")
async def reset_agent_context(agent_id: str = Path(
    ...,
    description="Agent ID to reset context for",
)) -> dict[str, str]

Reset context usage statistics for an agent.

Arguments:

  • agent_id - The unique identifier of the agent.

Returns:

Confirmation message.

export_agent_context_csv​

@router.get("/agents/{agent_id:path}/context-export")
async def export_agent_context_csv(agent_id: str = Path(
    ...,
    description="Agent ID to export context for",
),
                                   truncate_message_chars: int = 200
                                   ) -> dict[str, Any]

Export per-step usage data as CSV text.

Each row represents one model request/response cycle (step) with the tool that was called, token counts, and timestamp.

Arguments:

  • agent_id - The unique identifier of the agent.
  • truncate_message_chars - Unused, kept for backward compatibility.

Returns:

Dict containing filename and CSV content.

get_agent_spec_endpoint​

@router.get("/agents/{agent_id:path}/spec")
async def get_agent_spec_endpoint(agent_id: str = Path(
    ...,
    description="Agent ID to get the creation spec for",
)) -> dict[str, Any]

Get the original creation spec for a specific agent.

Returns the spec as provided at agent creation time, including separated system_prompt and system_prompt_codemode_addons fields (which are merged at runtime and lost in the running agent).

This endpoint also includes the sandbox status when codemode is enabled.

Arguments:

  • agent_id - The unique identifier of the agent.

Returns:

The original agent creation spec with sandbox status.

Raises:

  • HTTPException - If agent spec not found.

interrupt_sandbox​

@router.post("/sandbox/interrupt")
async def interrupt_sandbox(agent_id: str | None = None) -> dict[str, Any]

Interrupt the currently running code in the sandbox.

Returns:

Result of the interrupt request.

notify_sandbox_status_change​

async def notify_sandbox_status_change(agent_id: str | None = None) -> None

Notify websocket listeners that sandbox status may have changed.

sandbox_status_ws​

@router.websocket("/sandbox/ws")
async def sandbox_status_ws(websocket: WebSocket,
                            agent_id: str | None = None) -> None

WebSocket endpoint that streams sandbox status updates.

Sends a JSON message every time the status changes (or at most every 500 ms). The client can also send {"action": "interrupt"} to request a sandbox interrupt.

Message format (server → client)::

{
    "variant": "eval" | "jupyter" | "unavailable",
    "sandbox_running": true/false,
    "is_executing": true/false,
    "jupyter_url": "..." | null
}

toggle_codemode​

@router.post("/codemode/toggle")
async def toggle_codemode(request: CodemodeToggleRequest) -> dict[str, Any]

Toggle codemode on/off and optionally update skills.

This updates the runtime state AND updates the agent adapters' toolsets so codemode is enabled/disabled immediately without requiring a restart.

Arguments:

  • request - Toggle request with enabled state and optional skills list.

Returns:

Updated codemode status.

get_codemode_status​

@router.get("/codemode/status")
async def get_codemode_status(agent_id: str | None = Query(
    default=None,
    description=
    "Optional agent id to resolve codemode status for a specific running agent",
)) -> dict[str, Any]

Return current codemode status from the running server process.

This endpoint is intended for interactive clients (e.g. TUX slash commands) so they can query a single source of truth instead of relying on in-process state from a separate CLI process.