Skip to main content
One of the easiest ways to get confused in TerminalUse is to mix up the product surfaces.

​
The Four Main Surfaces

​
1. Agent Runtime Surface

Use this when you are writing the agent itself.
  • Python only today
  • terminaluse.lib
  • AgentServer
  • TaskContext
  • adk
This is the surface for @server.on_create, @server.on_event, @server.on_cancel, runtime filesystem sync, and task-scoped state.

​
2. App SDK Surface

Use this when your backend or application needs to call deployed agents.
  • Python SDK: terminaluse
  • TypeScript SDK: @terminaluse/sdk
This is the surface for creating filesystems, creating tasks, sending events, listing messages, and downloading outputs.

​
3. CLI Surface

Use this for local workflows and operations.
  • tu init
  • tu deploy
  • tu tasks ...
  • tu fs ...
  • tu env ...
The CLI is not a perfect wrapper around every HTTP endpoint. If a CLI command does not exist, the docs should not invent one.

​
4. HTTP API / OpenAPI Surface

Use this when you are integrating directly at the API level or when you need the generated endpoint reference. This is the most literal surface. It is not the best place to learn the product model first.

​
A Good Default Mental Map

Write agent code          -> terminaluse.lib
Call deployed agents      -> Python SDK / TypeScript SDK
Operate locally           -> tu CLI
Inspect raw endpoints     -> API reference

​
Common Mistakes

  • Treating the ADK as if it were the app SDK
  • Assuming every SDK method also has a CLI command
  • Learning the product from raw endpoint pages instead of the concept pages