External Tasks
Multi-machine coordinator/worker pattern using external task handlers
External Tasks
External task handling enables a coordinator/worker pattern where tasks are dispatched to remote workers instead of executing locally. This is the foundation for multi-machine A3S Code deployments.
For the full multi-machine architecture guide, see Multi-Machine Distribution.
Handler Modes
Prop
Type
Basic External Handler
const session = agent.session('/my-project', {
permissive: true,
queueConfig: { enableAllFeatures: true },
});
// Register external task handler
session.setExternalTaskHandler(async (task) => {
console.log(`Worker received task: ${task.id}`);
return { success: true, result: { output: 'task completed' } };
});Run: node examples/test_external_task_handler.ts
Source: sdk/node/examples/test_external_task_handler.ts
from a3s_code import SessionQueueConfig
queue_config = SessionQueueConfig()
queue_config.enable_all_features = True
session = agent.session("/my-project",
permissive=True,
queue_config=queue_config,
)
# Register external task handler
def handle_task(task):
print(f"Worker received task: {task['id']}")
return {"success": True, "result": {"output": "task completed"}}
session.set_external_task_handler(handle_task)Run: python examples/test_external_task_handler.py
Source: sdk/python/examples/test_external_task_handler.py
Parallel Processing
Distribute work across multiple sessions in parallel:
const files = ['auth.rs', 'db.rs', 'handler.rs', 'config.rs'];
const results = await Promise.all(
files.map(async (file) => {
const session = agent.session('/my-project', { permissive: true });
return await session.send(`Review ${file} for issues`);
})
);
results.forEach((r) => console.log(r.text));Run: node examples/test_parallel_processing.ts
Source: sdk/node/examples/test_parallel_processing.ts
from concurrent.futures import ThreadPoolExecutor
files = ["auth.rs", "db.rs", "handler.rs", "config.rs"]
def review_file(file):
session = agent.session("/my-project", permissive=True)
return session.send(f"Review {file} for issues")
with ThreadPoolExecutor() as executor:
results = list(executor.map(review_file, files))
for r in results:
print(r.text)Run: python examples/test_parallel_processing.py
Source: sdk/python/examples/test_parallel_processing.py
API Reference
LaneHandlerConfig
Prop
Type
ExternalTaskResult fields
Prop
Type