> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.meetluno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Learn how to build and run agents.

An agent is an LLM-powered worker that can reason about a request, choose tools, use memory, read files, and keep going until it has an answer or has completed the task.

Use an agent when the path must vary at runtime: answering a support question, researching an issue, drafting a reply, or deciding which tool to call next. If the work follows a known sequence, prefer a [workflow](https://docs.os.meetluno.ai/learn/workflows/overview.md); it can still use an agent or `promptLlm()` for the steps that need judgment.

## Example requests

Ask your coding agent to build an agent, the tools it should use, and where people should interact with it.

> "Build a support agent that answers product questions from our docs, checks customer details, and drafts replies in our support tone."

> "Create an agent that watches for tagged Slack messages, investigates the topic, and replies with a sourced summary."

> "Build a data agent that can query our warehouse and answer questions from a #data Slack channel."

## How agents are defined

In Luno OS, agents live in your project code under `src/agents/`. Each file default-exports a `defineAgent()` definition, and the runtime discovers it when you run or deploy the project.

```ts theme={null}
import { defineAgent } from "@meetluno/luno/agent";
import { defineSandbox } from "@meetluno/luno/sandbox";

export default defineAgent({
  slug: "support",
  name: "Support",
  description: "Answers product questions using bundled docs and a support skill.",
  systemPrompt:
    "You are helpful support. Read /workspace/agent/support-instructions.md before answering.",
  model: "openai/gpt-5.6-sol",
  skills: ["support"],
  sandbox: defineSandbox({ files: "support" }),
});
```

## What agents can use

Agents are useful when a task needs judgment, language understanding, tool use, or multi-turn context.

| Capability | How it works |
| - | - |
| **Instructions** | `systemPrompt` tells the model how to behave |
| **Models** | `model` is an exact catalog id (`vendor/model-id`); optional `thinkingLevel`. See [Models](https://docs.os.meetluno.ai/learn/agents/build-agents.md#models). |
| **File system** | Each session gets a `/workspace` with a built-in file system and bash (code execution) tools |
| **Web search** | Built-in `web_search` and `web_fetch` tools when a web provider is configured |
| **Browser use** | Coming soon — native browser automation for clicking, forms, and multi-step web flows |
| **Tools** | Attach custom tools, MCP tools, subagents, and workflows as tools |
| **Skills and files** | Attach project skills from `src/skills/` and static files from `src/files/` |
| **Company Brains** | Search and read shared organization knowledge on demand. See [Company Brain](https://docs.os.meetluno.ai/learn/settings/company-brain.md). |
| **Memory** | Sessions and persistent memory are enabled by default unless disabled |
| **Sandbox** | A built-in sandbox environment for using CLIs and more advanced code execution |
| **Self-scheduling** | Built-in tools let an agent schedule its own future or recurring runs (ephemeral triggers) |

Agents are one of the main primitives in a project, alongside [workflows](https://docs.os.meetluno.ai/learn/workflows/overview.md), [actions](https://docs.os.meetluno.ai/learn/actions/overview.md), and [triggers](https://docs.os.meetluno.ai/learn/triggers/overview.md). Actions are the usual way to give an agent reliable capabilities. Workflows are the usual way to orchestrate several deterministic steps around one or more agent calls.

## How to run agents

You can use an agent from the CLI, API, a workflow, another agent, or an external gateway like Slack. You can also run an agent automatically by attaching a [trigger](https://docs.os.meetluno.ai/learn/triggers/overview.md) (a schedule, webhook, or poll), and agents can even schedule their own runs with [ephemeral triggers](https://docs.os.meetluno.ai/learn/agents/build-agents.md#ephemeral-triggers).

```bash theme={null}
luno agents prompt support --message "What is Luno OS?"
```

Open **Agents** in Studio to see the agents across your Spaces. Open **Runs** (`/history`) and filter to **Agent** when you want to inspect sessions after they run.

## Running deployed agents

Deploy your project, then prompt the agent against the deployed project:

```bash theme={null}
luno deploy --project <slug>   # or --filter agents/support
luno agents prompt support --message "Hi"
```

## Next steps

> **[Build agents](https://docs.os.meetluno.ai/learn/agents/build-agents.md)**
>
> Define agents with tools, models, skills, files, and runtime options.

> **[Run agents](https://docs.os.meetluno.ai/learn/agents/run-agents.md)**
>
> Prompt agents from the CLI and inspect sessions.

> **[Triggers](https://docs.os.meetluno.ai/learn/triggers/overview.md)**
>
> Run agents on a schedule, webhook, or poll.

> **[Agent runs](https://docs.os.meetluno.ai/learn/logs/agent-runs.md)**
>
> Review conversation history, tool calls, traces, and errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.