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
`model`	No	The model this agent thinks with, as `vendor:name`. See Which model runs it.

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.

Choose the model

On the web app’s Agent page, click the agent’s name to open its panel, then pick a model from Model. The robot switches without a restart, and the next reply comes from the new model.

This is the robot’s model, shared by every agent that doesn’t pin its own. Settings → Agent → Model changes the same setting. A model whose vendor key is missing stays in the list and says so; add the key under Settings → Keys. To pin a model to one agent, set model on its class:

class Greeter(Agent):
    model = "anthropic:claude-sonnet-5"

Starting the agent switches the robot to that model, and the Model picker shows it instead of offering a change. Vendors, example names, and the key each needs are in Which model runs it.

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.
`intro_agent`	A friendly assistant that greets people, waves, and answers from spatial memory.
`roast_agent`	A sassy insult comic that roasts whoever is in front of it, and still does the work.
`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 a Policy

Go Deeper

Help

Write an agent

Write a good prompt

Choose the model

Start an agent

Built-in agents

Troubleshooting

​Write an agent

​Write a good prompt

​Choose the model

​Start an agent

​Built-in agents

​Troubleshooting

Write an agent

Write a good prompt

Choose the model

Start an agent

Built-in agents

Troubleshooting