SPAgent

SPAgent is a foundation agent for the physical & spatial world

A general-purpose foundation agent framework for multimodal tool calling, connecting vision-language models with an open-ended ecosystem of expert tools.

Get Started Models Dataset Research

Capabilities

Modular Tool System

Mix and match any combination of expert tools. Add or remove tools at runtime with a single function call.

Open Tool Integration

Integrate any tool into the ecosystem. Define a schema, plug it in, and the agent will use it automatically.

Spatial Reasoning

Purpose-built prompts for 3D spatial understanding. Grounded perception in complex physical environments.

RL Training

GRPO training with multi-turn tool calling and an offline Pi3X cache, powered by ms-swift.

Stateful Multimodal Memory

AgentMemory preserves text, images, tool calls, and results across multi-turn conversations.

Parallel & Multi-Model

Run expert tools concurrently with GPT, Qwen, or local OpenAI-compatible model backends.

Supported tools

26 registered tool integrations spanning perception, grounding, 3D understanding, document intelligence, and generation.

2D Perception

Depth Anything V2

High-accuracy monocular depth estimation for dense depth maps from a single image.

:20019

SAM 2 / OneFormer

Promptable and universal semantic, instance, and panoptic image segmentation.

:20020 / :20038

Grounding DINO

Open-vocabulary object detection driven by natural-language prompts and referring expressions.

:20022

YOLO26 / Face Detection

Fast local object detection plus lightweight CPU frontal-face detection.

local

YOLO-E / Supervision

Open-vocabulary detection, segmentation, annotation, and visualization.

local / :8000

FlowSeek

Dense optical flow estimation between image pairs with raw motion fields.

local / :20036

PaddleOCR-VL 1.5

OCR and structured recognition for text, tables, charts, formulas, and seals.

local / :20037
Vision-Language & Grounding

Moondream

Lightweight visual question answering, captioning, and point grounding.

:20024

Molmo2

Multimodal reasoning with QA, captioning, and annotated point outputs.

:20025

Qwen2.5-VL

Referring and reasoning-based object detection from image-text prompts.

API / local
3D Understanding

Pi3 / Pi3X

3D point cloud reconstruction from single or multiple images, with Pi3X adding smoother metric-scale outputs.

:20030 / :20031

VGGT

Feed-forward multi-view 3D reconstruction with camera pose, depth, and geometry prediction in one pass.

:20032

MapAnything

Universal metric 3D reconstruction for dense point clouds, depth, poses, and multi-view geometry.

:20033

OrientAnything V2

Object orientation, symmetry, and two-image relative rotation estimation.

:20034

WildDet3D

Promptable 3D object detection from a single RGB image using text, boxes, or points.

local / :20027
Image & Video Generation

Sana

Fast text-to-image generation through a local SGLang server.

:30000

Veo / Sora / Wan

Text-to-video and image-to-video generation across Google, OpenAI, and DashScope APIs.

API

VACE

Local first-frame video generation from a reference image and motion prompt.

local server
Tool Reference Deployment & Ports

Quick start

from spagent import SPAgent
from spagent.models import GPTModel
from spagent.tools import DepthEstimationTool, SegmentationTool

# Create model and tools
model = GPTModel(model_name="gpt-4o-mini")
tools = [
    DepthEstimationTool(use_mock=True),
    SegmentationTool(use_mock=True)
]

# Mock mode needs no expert servers
agent = SPAgent(model=model, tools=tools, max_workers=4)
result = agent.solve_problem(
    "image.jpg",
    "Analyze depth relationships and main objects"
)
print(result['answer'])

Use step() with AgentMemory for stateful multi-turn sessions, or connect real expert servers with use_mock=False.

Installation Advanced Examples Evaluation

Architecture

SPAgent Core

Agent loop, parallel execution, workflow routing, AgentMemory, and data collection.

Tool Contract

Standardized ToolResult envelopes, typed payloads, rendering, and contribution CI.

Expert Tools

26 catalog integrations using local, client/server, and cloud API deployments.

Model Backends

GPT, Qwen, and local OpenAI-compatible multimodal models.

GRPO Training

Multi-turn tool-calling rewards with offline Pi3X cache and ms-swift.

Evaluation

Unified quick evaluation across VLMEvalKit and spatial reasoning benchmarks.

Research

arXiv 2026

Think3D: Thinking with Space for Spatial Reasoning

Zaibin Zhang*, Yuhan Wu*, Lianjie Jia*, Yifan Wang, Zhongbo Zhang, Yijiang Li, Binghao Ran, Fuxi Zhang, Zhuohan Sun, Zhenfei Yin, Lijun Wang, Huchuan Lu.

* Equal contribution   ◆ Project leader   ✉ Corresponding author

Teaching agents to think in 3D space like humans, through drag-based spatial interaction.

Institutions

Dalian University of Technology
Dalian University of Technology
University of California, San Diego
University of California, San Diego
University of Oxford
University of Oxford
Get in touch
dlutzzb@gmail.com

Start building with SPAgent

Open-source and ready to use. Deploy expert tools, connect your model, and reason about the physical world.

View on GitHub Documentation Research