Developer Guide

About 283 wordsLess than 1 minute

2025-02-04

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`	✅

Decision Tree

Need warmup or Session?
    │
    ├── No -> Lightweight API Tool
    │        └── @register_api_tool
    │
    └── Yes -> Heavyweight Backend
             │
             │ Need globally shared resources?
             │
             ├── Yes -> Implement warmup() / shutdown()
             │
             └── Need worker-independent resources?
                  │
                  └── Yes -> Implement initialize() / cleanup()