This guide introduces how to develop and extend AgentFlow Sandbox.

Extension Methods

AgentFlow provides two extension methods:

1. Lightweight API Tools

Use @register_api_tool decorator to register simple API tools:

from sandbox.server.backends.tools import register_api_tool

@register_api_tool("my_tool", config_key="my_config")
async def my_tool(query: str, **config) -> Dict[str, Any]:
    api_key = config.get("api_key")
    # Call external API
    return {"result": "..."}

Features:

• ❌ No need to inherit any class
• ❌ No Session management needed
• ✅ Config auto-injected from apis.xxx
• ✅ Suitable for calling external APIs

2. Heavyweight Backend

Inherit Backend base class to create complex backends:

from sandbox.server.backends.base import Backend
from sandbox.server.core.decorators import tool

class MyBackend(Backend):
    name = "my"
    description = "My Custom Backend"
    
    async def warmup(self) -> None:
        # Warmup resources
        pass
    
    async def initialize(self, worker_id: str, config: Dict) -> Dict:
        # Create Session
        return {"resource": ...}
    
    @tool("my:action")
    async def action(self, param: str, session_info: Dict) -> Dict:
        return {"result": "..."}

Features:

• ✅ Supports lifecycle management
• ✅ Supports Session management
• ✅ Suitable for backends needing persistent state

Backend Types

Type	Methods	Use Case	Example
Shared Resource	warmup(), shutdown()	Global shared resources	RAG
Session Resource	initialize(), cleanup()	Worker-independent resources	VM, Bash
Hybrid	All four	Shared + Session	Browser

Quick Reference

I want to develop...	Choice	Decorator	Session
Call external API	Lightweight tool	@register_api_tool	❌
Shared model/pool	Backend + warmup	@tool	❌
Per-user instance	Backend + initialize	@tool	✅
Hybrid mode	Backend + all methods	@tool	✅