Agents

An agent is a prompt plus a list of skills, written as one Python class. New to agents? Start with Your first agent and skill. The same robot becomes a security guard or a tour guide depending on which agent runs.

Write an agent

The quickest way is the web app: Agent page, agent picker, Create agent. It saves a Python file like the one below. To write it by hand, save this as ~/innate-os/workspace/custom_agents/greeter.py:

from innate import Agent, InputRef, SkillRef
from innate_skills.navigate_to_position import NavigateToPosition
from innate_skills.wave import Wave
from inputs.micro_input import MicroInput


class Greeter(Agent):
    @property
    def id(self) -> str:
        return "greeter"

    @property
    def display_name(self) -> str:
        return "Greeter"

    def get_skills(self) -> list[SkillRef]:
        return [NavigateToPosition, Wave]

    def get_inputs(self) -> list[InputRef]:
        return [MicroInput]  # lets you talk to it

    def get_prompt(self) -> str:
        return """
You are a friendly robot who greets people.
- When you see a person, wave and say hello.
- If you see nobody, turn around to look for them.
- Keep replies short and warm.
"""

    def uses_gaze(self) -> bool:
        return True  # look at the person you're talking to

It loads within a second or two of saving. Import skills as classes, as above, so your editor catches typos and renames.

Method	Required	Purpose
`id`	Yes	Unique snake_case identifier
`display_name`	Yes	Name shown in the apps
`get_skills()`	Yes	Skill classes the agent may call
`get_prompt()`	Yes	Personality, goals, and rules
`get_inputs()`	No	Input devices to open. Add `MicroInput` to hear speech.
`uses_gaze()`	No	Return `True` to track faces with the head
`display_icon`	No	Path to a 32×32 icon

Every agent can already talk, wait, and stop a running skill. You don’t list those.

Write a good prompt

Skills decide what the robot can do. The prompt decides what it does. The model follows it literally, so be specific:

Say who the robot is and how it speaks.
Give the goal as concrete steps.
Say what to do in edge cases, like when nobody is there or a skill fails.

Example: security guard

You are a security guard robot. Stay calm and professional.

Patrol route: living room, kitchen, bedroom, back door, then repeat.
Look carefully in each room before moving on.

If you see someone who shouldn't be there:
- Do not approach them.
- Raise the alarm out loud right away.
- Say where you are and describe what you saw.

Example: sock collector

You are a tidying robot. Find socks on the floor and put them in the
white laundry basket by the bedroom door.

1. Scan the room for socks.
2. Drive to one and pick it up.
3. Drive to the basket and drop it in.
4. Repeat until none are left, then do one final sweep.

If a sock is out of reach, skip it.

Example: quiet observer

You are a calm, observant robot.
Stay quiet unless someone talks to you, then answer briefly.
Slowly turn in place to watch the room. Don't drive away unless asked.

Start an agent

Web app: open the Agent page, pick your agent, and press Start. Reset clears the conversation.
Phone app: tap the agent’s card on the Home screen. Pull down to refresh the list.
On boot: in the phone app, long-press a card and choose Set as default.

Starting a different agent stops the current one and cancels its running skill.

Built-in agents

These ship in workspace/innate_agents/. Read them for working examples.

Agent	What it does
`demo_agent`	The default. Chats, navigates, waves, picks things up, and follows your gaze.
`basic_agent`	Navigation only, with an empty prompt.
`j3so_directive`	A character that chats and navigates.
`security_guard_agent`	Patrols and warns out loud when it sees someone.

Troubleshooting

Problem	Fix
Agent doesn’t appear	Check the file is in `custom_agents/` and imports without errors. The web app marks broken files with their error.
Agent won’t start	Check that every skill in `get_skills()` exists. Read the logs.
Agent ignores you	Add `MicroInput` to `get_inputs()`, and tighten the prompt.
Agent never uses a skill	Trigger the skill by hand. If it works, improve its `guidelines()` or the prompt.

Get Started

Simulator

Build Agents and Skills

MARS

Train the Arm

Go Deeper

Help

Hackathon

Write an agent

Write a good prompt

Start an agent

Built-in agents

Troubleshooting

​Write an agent

​Write a good prompt

​Start an agent

​Built-in agents

​Troubleshooting

Write an agent

Write a good prompt

Start an agent

Built-in agents

Troubleshooting