From 871981cf27979dbd16dc1e122f1888a39accf3ae Mon Sep 17 00:00:00 2001 From: ym-han <21286812+ym-han@users.noreply.github.com> Date: Sat, 29 Nov 2025 14:27:16 +0000 Subject: [PATCH] docs: Add quickstart doc and link to it from README --- README.md | 2 + docs/index.md | 2 +- docs/quickstart.md | 138 +++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 7 +-- 4 files changed, 143 insertions(+), 6 deletions(-) create mode 100644 docs/quickstart.md diff --git a/README.md b/README.md index f8df86f5aa..578701eb82 100644 --- a/README.md +++ b/README.md @@ -238,6 +238,8 @@ yarn dev # you may need to run sudo if previously built via Docker ## Building +Get started in minutes with our [Quickstart](./docs/quickstart.md): build an agentic robot that can make greetings! + ### Simple DimOS Application (OUT OF DATE) ```python diff --git a/docs/index.md b/docs/index.md index 632febee23..0153e0bae2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,7 @@ The result: cross-embodied *"Dimensional Applications"* exceptional at generaliz Get up and running with DimOS in minutes. Install dependencies, configure your environment, and run your first agent. - [:octicons-arrow-right-24: Get started](quickstart/index.md) + [:octicons-arrow-right-24: Get started](quickstart.md) - :material-school: **Tutorials** diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000000..e94278f6f6 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,138 @@ +# Quickstart + +DimOS is a modular framework for building agentive robots. In this quickstart, you'll learn the basics of DimOS by building an LLM agent that can make greetings. + +## Installation + +### Requirements + +- Python 3.10+ +- OpenAI API key in environment + +### Install DimOS + +```python +# TODO: Ideally, when this is released, this should be as simple as +# pip install dimos +``` + + +## Define a skill + +Suppose you have a robot with a speaker. + +```python +from dimos.core.skill_module import SkillModule +from dimos.core.core import rpc +from dimos.protocol.skill.skill import skill + +# See the Skills concept guide for more on SkillModule +class Robot(SkillModule): + rpc_calls = [] + + # In a real setting, there would also be things like a ConnectionModule + # for the robot platform you are using + @rpc + def speak(self, text: str) -> str: + print(f"[Robot] {text}") + return f"SPEAK: {text}" +``` + +How can we wire up this `speak` capability to an LLM agent -- how can we go from this to an agentic robot that can make greetings by using that on-board speaker? + +Answer: make a *skill* -- a method on a `Module` that's decorated with `@skill`, so that it gets turned into *tools* that an agent can call. + +```python +class Greeter(SkillModule): + rpc_calls = ["Robot.speak"] # Declare dependency + + @skill() + def greet(self, name: str = "friend") -> str: + '''Greet someone by name.''' + self.get_rpc_calls("Robot.speak")(f"Hello, {name}!") + return f"Greeted {name}" +``` + +Notice that `Greeter` doesn't import `Robot` directly. Instead, it declares a dependency in `rpc_calls`, and the framework wires them together at runtime. + +## Wire up and build the modules + +Now we can call `llm_agent` to get an LLM agent module, combine it with our `Robot` and `Greeter` modules to get a [*blueprint*](concepts/blueprints.md) for the whole system, and then build it. + +```python +from dotenv import load_dotenv + +load_dotenv() + +from dimos.agents2.agent import LlmAgent, llm_agent +from dimos.core.blueprints import autoconnect + +dimos = ( + autoconnect( + Robot.blueprint(), + Greeter.blueprint(), + llm_agent(system_prompt="You're a friendly robot. Use greet when asked to say hello."), + ) + .global_config(n_dask_workers=1) + .build() +) + +print("System running!") +``` + +``` {title="Output"} +deployed: Robot-f970968e-... @ worker 0 +deployed: Greeter-fe23b94c-... @ worker 0 +deployed: LlmAgent-dc45564b-... @ worker 0 +System running! +``` + +As part of this process, the blueprint system matches dependencies (e.g., `Greeter`'s need for `Robot.speak`) and converts `Greeter`'s `greet` skill to a tool for the LLM agent. + +The system is now running. For long-running applications, you'd call `dimos.loop()` to keep it alive until Ctrl+C. + +## Say hi to our agent + +Time to say hi to our agent (in a real system, the robot's greetings would then be piped through the speakers): + +```python +agent = dimos.get_instance(LlmAgent) +print(agent.query("Hi there!")) +``` + +``` {title="Output"} +Hello! How are you doing today? +``` + +> [!NOTE] +> Exactly what greeting the LLM will make will, of course, differ across runs. + +```python +print(agent.query("Can you greet Alice as well?")) +``` + +``` {title="Output"} +[Robot] Hello, Alice! +Hello to Alice! +``` + +You now have a robot that you can ask -- in ordinary English -- for greetings! + +## What you learned + +You've seen the core DimOS pattern: define skills in modules, wire them together with the blueprint system, and let an LLM agent handle natural language requests. + +## Next steps + +### Tutorials + +- [Build your first skill](tutorials/skill_basics/tutorial.md): A tutorial that explains how to build a skill -- and how the blueprint system works -- in more detail +- [Equip an agent with skills](tutorials/skill_with_agent/tutorial.md) +- [Build a multi-agent RobotButler](tutorials/multi_agent/tutorial.md): Build a multi-agent RoboButler system, where a planner agent coordinates specialist subagents. + +### Concept guides + +- [Blueprints](concepts/blueprints.md) +- [Agents](concepts/agent.md) +- [Modules](concepts/modules.md) +- [Transport](concepts/transport.md) diff --git a/mkdocs.yml b/mkdocs.yml index 9c27be42e9..3b8f218ada 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,10 +72,7 @@ markdown_extensions: nav: - Home: index.md - - Quickstart: - - quickstart/index.md - - Installation: quickstart/installation.md - - Basic Usage: quickstart/basic-usage.md + - Quickstart: quickstart.md - Tutorials: - tutorials/index.md - Build your first skill: tutorials/skill_basics/tutorial.md @@ -119,7 +116,7 @@ plugins: Home: - index.md: Introduction to DimOS Quickstart: - - quickstart/*.md + - quickstart.md Tutorials: - tutorials/*.md Concepts: