Usage¶

Thea is a provider-neutral Harness for embodied agents. It owns the Agentic Loop, context lifetimes, Tool execution, post-execution Evaluation, and the boundaries through which a deployment supplies physical-world evidence.

The public release can be used in five ways:

Deployment	What you provide	What Thea provides
Local terminal	A configured model credential	The complete Agentic Loop and terminal-backed user interaction without Lark or a robot
Feishu/Lark channel	App credentials, authorized users, and a configured model	Per-user Harness sessions, cards, images, clarification, and notifications
Harness library	A model and model-visible Tools	Agentic Loop, Context, Tool Protocol, Memory, Skills, hooks, and logs
Simulator	A LIBERO or RoboTwin 2.0 environment and primitive policy	Observation projection, policy-backed Tool integration, and evaluator wiring
Physical robot	Robot SDK adapters, sensing, policies, Scene Graph, and post-execution evidence	The same runtime and public interfaces used in simulation

The root launcher maps these paths to four modes:

Command mode	Process started	Additional requirement
`--mode cli`	Interactive terminal, or one instruction with `--instruction`	Model configuration and credential
`--mode channel`	Feishu/Lark channel with the default Harness	Model and Lark credentials
`--mode simulation`	Feishu/Lark channel with a simulator Harness factory	Lark credentials, importable factory, and `thea-simulation`
`--mode robot`	Feishu/Lark channel with a robot Harness factory	Lark credentials and importable factory

simulation and robot are channel-hosted deployment modes, not standalone simulator or hardware executables. Applications without Lark compose Harness in Python and call run_stream() directly. Run ./run.sh --help for the complete launcher options.

Choose a starting point¶

Run the Harness in a terminal¶

Install the repository, configure a real model in .env and config.yaml, then start the interactive terminal:

./install.sh
./run.sh --mode cli --check
./run.sh --mode cli

This path requires no Lark credential and no simulator or physical robot. It also supports a single instruction:

./run.sh --mode cli --instruction \
  "Notify the user that the Harness is ready, then explain what ran."

Run the complete channel¶

Install all public packages, configure a model and Feishu/Lark credentials, then start the channel:

./install.sh
./run.sh --mode channel --check
./run.sh --mode channel

The channel creates one Harness session per authorized user and registers query_user and notify_user as model-visible Tools.

Connect a simulator¶

Install the selected benchmark environment separately, build a factory that returns one Harness, configure the Lark credentials described above, and run the preflight before starting the channel:

my_runtime.sim:create_harness is an example import path. Implement it using the simulation guide before running this command:

./run.sh --mode simulation --check \
  --harness-factory my_runtime.sim:create_harness

./run.sh --mode simulation \
  --harness-factory my_runtime.sim:create_harness

The factory connects the benchmark episode, primitive policy Tools, Observation provider, and evaluator. See Simulation for the LIBERO and RoboTwin 2.0 adapter boundaries.

Connect a physical robot¶

Keep hardware SDKs and deployment-specific code outside the Harness package. Expose them through the public interfaces, configure the Lark credentials, and validate the factory before starting the channel:

my_runtime.robot:create_harness is an example import path and must resolve to the factory in your deployment package:

./run.sh --mode robot --check \
  --harness-factory my_runtime.robot:create_harness

./run.sh --mode robot \
  --harness-factory my_runtime.robot:create_harness

The factory owns the robot connection and must return one configured Harness. Start from Port to Your Robot, then connect Scene Graph and Evaluation when physical execution is ready.

Extend an Existing Harness¶

Use the smallest public boundary that matches the new capability:

Goal	First step	Detailed guide
Change the model	Configure `llm` or implement `ModelProtocol`.	Models and Tools
Add a Tool	Register an annotated callable, `BuiltinTool`, or MCP capability with `ToolRegistry`.	Models and Tools
Add current evidence	Implement `ObservationProvider` and, when needed, `BaseClearanceProvider`.	Observation and Safety
Add reusable task guidance	Create a directory-backed `SKILL.md` and select `skills.dir`.	Memory, Skills, and Embodiment
Add persistent world state	Implement `SceneGraphProtocol` and its ref-keyed queries.	Scene Graph
Add physical outcome checks	Connect post-execution evidence and `EvaluatorProtocol`.	Evaluation

How one task runs¶

One user instruction starts one Task. Each Turn follows the same reactive cycle:

refresh evidence
  -> model decision
  -> execute at most one selected Tool
  -> run configured hooks
  -> record the result
  -> refresh again

The model may return text together with one Tool Call. A Task ends when the model returns no Tool Call or when the Harness terminates the run. The final text becomes the task report.