> ## Documentation Index
> Fetch the complete documentation index at: https://innateinc-docs-skills-0-7-interface.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Anatomy of an Agent

export const AgentOptionalMethodsTable = () => {
  const rows = [{
    method: "display_icon",
    returns: "str",
    purpose: "Path to a 32x32 pixel icon."
  }, {
    method: "get_inputs()",
    returns: "list[InputRef]",
    purpose: "Input devices to activate — the InputDevice class, or its name string (for example: [\"micro\"])."
  }, {
    method: "uses_gaze()",
    returns: "bool",
    purpose: "Enable person-tracking eye movement."
  }];
  return <div className="interface-methods-table-wrap">
      <table className="interface-methods-table">
        <thead>
          <tr>
            <th>Method</th>
            <th>Returns</th>
            <th>Purpose</th>
          </tr>
        </thead>
        <tbody>
          {rows.map(row => <tr key={row.method}>
              <td>
                <span className="interface-method-pill">{row.method}</span>
              </td>
              <td>
                <span className="interface-param-badge">
                  {row.returns}
                </span>
              </td>
              <td>{row.purpose}</td>
            </tr>)}
        </tbody>
      </table>
    </div>;
};

export const AgentCoreMethodsTable = () => {
  const rows = [{
    method: "id",
    returns: "str",
    purpose: "Unique identifier (snake_case)."
  }, {
    method: "display_name",
    returns: "str",
    purpose: "Human-readable name shown in the app."
  }, {
    method: "get_skills()",
    returns: "list[SkillRef]",
    purpose: "Skills this agent can use — the Skill class, a generated policy ref, or a full ID string."
  }, {
    method: "get_prompt()",
    returns: "str",
    purpose: "Personality and behavioral instructions."
  }];
  return <div className="interface-methods-table-wrap">
      <table className="interface-methods-table">
        <thead>
          <tr>
            <th>Method</th>
            <th>Returns</th>
            <th>Purpose</th>
          </tr>
        </thead>
        <tbody>
          {rows.map(row => <tr key={row.method}>
              <td>
                <span className="interface-method-pill">{row.method}</span>
              </td>
              <td>
                <span className="interface-param-badge">
                  {row.returns}
                </span>
              </td>
              <td>{row.purpose}</td>
            </tr>)}
        </tbody>
      </table>
    </div>;
};

Every agent follows the same structure. Once you understand it, you can create any agent you need.

## File Location

Your agents are stored in `~/innate-os/workspace/custom_agents/` on the robot (shipped agents live next door in `workspace/innate_agents/`). The system automatically discovers Python files in these directories—no registration or configuration required.

The directory is watched while the robot runs: new files and edits hot-reload automatically within a second or two — no restart required. (`innate service restart` remains the fallback if something doesn't get picked up.)

## Core Interface

Every agent implements four methods:

<AgentCoreMethodsTable />

Optional methods:

<AgentOptionalMethodsTable />

## Minimal Example

The simplest possible agent:

```python theme={null}
from innate import Agent, SkillRef

class MyAgent(Agent):
    @property
    def id(self) -> str:
        return "my_agent"

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

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

    def get_prompt(self) -> str:
        return "You are a robot."
```

This agent loads and runs, but does very little—it has no skills and a minimal prompt.

## Complete Example

A functional agent with skills, inputs, and a detailed prompt:

```python theme={null}
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 HelloWorld(Agent):
    """Greets visitors with a friendly wave."""

    @property
    def id(self) -> str:
        return "hello_world"

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

    @property
    def display_icon(self) -> str:
        return "assets/hello_world.png"

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

    def get_inputs(self) -> list[InputRef]:
        return [MicroInput]  # enables the microphone — see below

    def get_prompt(self) -> str:
        return """
You are a friendly robot who greets people.

- Speak in a casual, warm tone
- If you don't see anyone, turn around to look for them
- When you see a person, wave and say hello
- Respond to what people say to you
"""

    def uses_gaze(self) -> bool:
        return True
```

This agent combines navigation and waving skills, microphone input, a friendly prompt, and gaze tracking for more natural interaction.

## Naming skills

Prefer the **class** — an import is checked by your editor, so a rename or a typo fails
before it reaches the robot:

```python theme={null}
from custom_skills.my_skill import MySkill                          # yours
from innate_skills.navigate_to_position import NavigateToPosition   # shipped code skill
from physical_skills import PickSocks                               # trained policy

def get_skills(self) -> list[SkillRef]:
    return [NavigateToPosition, PickSocks, MySkill]
```

Full ID strings still work and are the escape hatch when the ID is only known at runtime.
They're namespaced by the package the skill comes from:

| Prefix       | Source                                                                            |
| ------------ | --------------------------------------------------------------------------------- |
| `innate-os/` | skills shipped with the OS                                                        |
| `local/`     | your own skills in `~/innate-os/workspace/custom_skills/`                         |
| `<folder>/`  | a [skill pack](/software/skills#skill-packages-and-ids) dropped into `workspace/` |

IDs are matched exactly — a custom skill named `victory_spin` must be listed as
`"local/victory_spin"`, not bare.

<Tip>
  An agent whose file fails to import no longer disappears from the picker. It shows up as a
  disabled option with its error, and clears when you fix it.
</Tip>

## Enabling the Microphone

If you want to **talk to your agent**, you must enable the microphone input — it is not on by default. Return the microphone device from `get_inputs()`:

```python theme={null}
from inputs.micro_input import MicroInput

def get_inputs(self) -> list[InputRef]:
    return [MicroInput]      # or the name string, "micro"
```

That's all: when the agent starts, the runtime opens MARS's built-in microphone and everything you say is streamed into the agent's context as chat input. Without this, the agent only reacts to what it sees and to messages typed in the app.

The same mechanism works for any [input device](/software/inputs) (added sensors, network events, ...) — `"micro"` is just the built-in one. See [Example: Microphone](/software/inputs/example-microphone) for how it works under the hood.

## Writing Effective Prompts

The prompt determines how the robot behaves. Skills define what's *possible*; the prompt defines what *actually happens*.

A good prompt defines personality, goals, constraints, and strategy in plain language. Be specific. The AI interprets your prompt literally, and vague instructions produce inconsistent behavior.

## Template

Copy and modify this template for new agents:

```python theme={null}
from innate import Agent, InputRef, SkillRef
from innate_skills.head_emotion import HeadEmotion
from innate_skills.move_straight import MoveStraight
from innate_skills.navigate_to_position import NavigateToPosition
from inputs.micro_input import MicroInput

class MyCustomAgent(Agent):
    """One-line description of what this agent does."""

    @property
    def id(self) -> str:
        return "my_custom_agent"

    @property
    def display_name(self) -> str:
        return "My Custom Agent"

    @property
    def display_icon(self) -> str:
        return "assets/my_icon.png"  # Optional

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

    def get_inputs(self) -> list[InputRef]:
        return [MicroInput]

    def get_prompt(self) -> str:
        return """
Describe who the robot is and what it should do.
Be explicit about personality, goals, strategy, and constraints.
"""

    def uses_gaze(self) -> bool:
        return True
```

## Deploy your agent

<Steps>
  <Step title="Save the file in the right place">
    Save your agent as `my_agent.py` in **`~/innate-os/workspace/custom_agents/`** on the robot. This is the one directory the system scans for your agents — anywhere else and it won't load.
  </Step>

  <Step title="Let hot reload pick it up">
    The runtime watches `custom_agents/` — your new agent loads automatically within a second or two of saving, and so does every later edit. If it ever fails to appear, restart the runtime as a fallback:

    ```bash theme={null}
    innate service restart
    ```
  </Step>

  <Step title="Check it appears in the app">
    Your agent shows up as a card on the app **Home** screen — pull down to refresh if needed. From there, tap to start it.
  </Step>
</Steps>