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​

"local-eval" or "local-jupyter"

CodemodeStatus Objects​

class CodemodeStatus(BaseModel)

Codemode status response.

CodemodeToggleRequest Objects​

class CodemodeToggleRequest(BaseModel)

Request to toggle codemode.

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.

get_sandbox_status_endpoint​

@router.get("/sandbox-status")
async def get_sandbox_status_endpoint() -> dict[str, Any]

Get the current sandbox execution status.

Returns:

Sandbox status including whether code is executing.

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": "local-eval" | "local-jupyter" | "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.