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

# Standalone agents and Agent Library

> Run an agent on its own without building a full workflow, and save reusable copies to your Agent Library

## Purpose

Most agents run as a node inside a [workflow](/workflows/agent-node). But sometimes you just want to run one agent directly, with no surrounding process, to test a persona, answer a one-off request, or process a single document.

A **standalone agent** does exactly that: it runs an agent on its own and records the result as a normal execution you can inspect later. The **Agent Library** is where you keep reusable agents. When you bookmark a workflow agent, MagOneAI saves an independent library copy that you can run standalone or drop into other work, without touching the original.

Behind the scenes a standalone run still goes through the same durable engine a full workflow uses, so it gets the same input handling, logging, and observability. You get the convenience of running one agent with none of the reliability trade-offs.

## How it works

A standalone run wraps your agent in a minimal, three-step workflow and executes it on the shared engine.

<Steps>
  <Step title="You trigger a run">
    You run a library agent directly and provide its inputs. The agent must be active.
  </Step>

  <Step title="A synthetic workflow is built">
    MagOneAI assembles a small `start -> agent -> end` workflow around your agent. Its persona, tools, knowledge bases, model, and model parameters all carry over from the agent's saved configuration.
  </Step>

  <Step title="Inputs are resolved">
    The agent's standalone input schema becomes both the START node's input contract and the agent's input fields, so every input runs through the same per-type resolver a real workflow uses (text stays text, a file is extracted, an image is read with vision, an array of files becomes a query tool).
  </Step>

  <Step title="The agent runs on the engine">
    The synthetic workflow is started as a durable execution. It is recorded with no parent use case, and it remembers which library agent ran so the executions view can label it and link back.
  </Step>

  <Step title="You get an execution to track">
    The run returns an execution ID and starts asynchronously. You follow its progress and read its output in the executions view, exactly like any workflow run.
  </Step>
</Steps>

<Note>
  A standalone run is not a lesser execution. It is a real, durable run on the same engine, with the same activity logging and monitoring as a multi-node workflow.
</Note>

## How to use

### Save an agent to your library

An agent belongs to the Agent Library when it is marked as a library agent. Library agents are standalone by nature: unlike workflow agents, they are not tied to a use case, so they can be run on their own.

You add to the library in two ways:

* **Bookmark a workflow agent.** Bookmarking creates an independent library copy of an existing workflow agent. The copy carries its own configuration and records which agent it came from, so its origin stays traceable.
* **Create a library agent directly.** Build an agent as a library agent from the start, give it a persona and model, and attach tools or knowledge bases as needed.

<Info>
  A bookmarked copy is independent. Editing the library copy does not change the original workflow agent, and editing the original does not change the copy. The link between them is provenance only, used to show that a copy exists and to link back to its source.
</Info>

### Define the input schema

A standalone agent declares what inputs it accepts through its **standalone input schema**, a simple map of field names to types:

```json theme={null}
{
  "customer_name": { "type": "string", "description": "Full name of the customer" },
  "contract": { "type": "file", "description": "The contract to review" },
  "screenshots": {
    "type": "array",
    "description": "Supporting screenshots",
    "items": { "type": "image" }
  }
}
```

Each field has a `type` and an optional `description`. Array fields also take an `items` shape. Fields are optional, so a run with a blank input still passes validation. If an agent declares no schema, it simply runs with no inputs.

Supported input types match the workflow resolvers: text passes straight through, a `file` is extracted to text, an `image` is read with vision, and an `array` of files is exposed to the agent as a query tool.

### Run the agent

Provide values for the declared fields and start the run. Text values are passed inline. File and image inputs are passed by their uploaded file ID rather than as raw uploads.

```json theme={null}
{
  "input": {
    "customer_name": "Acme Corp",
    "contract": "file_9f2a1c..."
  }
}
```

The run responds immediately with an execution ID and a started status, then continues in the background.

<Note>
  The in-app run form uploads files for you: pick a file for a `file`, `image`, or `array` input and it is uploaded and its file ID substituted into the input automatically, with the Run button disabled until the upload finishes. If you call the run API directly, upload the file first and pass its file ID in the input yourself.
</Note>

## Use cases

### Test a persona before wiring it into a workflow

**Scenario:** You are drafting a new "Contract Analyst" agent and want to see how it reasons before committing it to a multi-node process.

Save the agent to your library, run it standalone against a sample contract, read the output, then refine the persona and instructions. Once it behaves the way you want, use it as a [workflow agent node](/workflows/agent-node).

### Reuse a proven agent across your work

**Scenario:** A workflow agent has been tuned over many runs and you want the same behavior elsewhere without disturbing the original.

Bookmark it to your Agent Library. You now have an independent copy you can run standalone or evolve separately, while the source workflow keeps running unchanged.

### Handle a one-off request

**Scenario:** Someone needs a single document summarized and there is no standing workflow for it.

Run a summarization agent standalone with the document as a file input. The result is captured as an execution you can share or audit later, with no workflow to build or maintain.

## Best practices

<AccordionGroup>
  <Accordion title="Keep the input schema minimal">
    Declare only the fields the agent actually reads. A smaller schema is easier to run against and less error-prone. Add a clear `description` to each field so anyone running the agent knows what to provide.
  </Accordion>

  <Accordion title="Match input types to the work">
    Use `string` for prose, `file` for documents you want extracted, `image` for anything the agent should read visually, and an `array` of files when the agent should query across several tabular sources. The type you pick decides which resolver runs.
  </Accordion>

  <Accordion title="Bookmark instead of rebuilding">
    When you want a proven workflow agent's behavior somewhere else, bookmark it to the library rather than recreating it by hand. The copy starts from the exact configuration and keeps a link back to its source.
  </Accordion>

  <Accordion title="Treat the copy as its own agent">
    A library copy is independent. If you want changes to flow to both, edit them both. Do not assume a bookmark stays in sync with its source.
  </Accordion>

  <Accordion title="Use standalone runs to iterate, workflows to operate">
    Standalone runs are ideal for testing and one-off tasks. When an agent needs to coordinate with other steps, tools, or approvals, move it into a workflow where you get branching, parallelism, and human-in-the-loop control.
  </Accordion>
</AccordionGroup>

<Tip>
  Standalone runs are the fastest way to close the loop on a persona: run, read the output, adjust the instructions, run again. Once the behavior is solid, promote the agent into a workflow so it can work alongside tools, conditions, and other agents.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Agent overview" icon="robot" href="/agents/overview">
    Understand how agents combine persona, model, tools, and knowledge bases
  </Card>

  <Card title="Personas and prompts" icon="user-pen" href="/agents/personas-and-prompts">
    Craft the persona and instructions a standalone agent runs on
  </Card>

  <Card title="Agent node" icon="diagram-project" href="/workflows/agent-node">
    Add an agent to a workflow when it needs to coordinate with other steps
  </Card>

  <Card title="Knowledge bases and RAG" icon="book-open" href="/agents/knowledge-bases">
    Ground your agent in your own documents with retrieval
  </Card>
</CardGroup>