> For the complete documentation index, see [llms.txt](https://vibemx.gitbook.io/neuronai-studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vibemx.gitbook.io/neuronai-studio/agents/creating-agents.md).

# Creating Agents

The agent editor lets you configure provider, model, instructions, and tool bindings through a React form embedded in Livewire.

Studio is definition-driven: the package ships no domain Agent subclasses. Runtime uses `DynamicAgent` from each `AgentDefinition` (or JSON template); production PHP classes come from [export](/neuronai-studio/workflows/export-and-production.md).

## Create a new agent

1. Navigate to **Agents** → **Create Agent**
2. Fill in the form fields
3. Save

> **Screenshot pending:** Agent editor with provider, model, instructions, and tool bindings.
>
> Asset path: `docs/assets/screenshots/agents-form.png` Capture: `/neuronai-studio/agents/create` or edit page — dark theme, 1440×900

## Form fields

| Field            | Description                                            |
| ---------------- | ------------------------------------------------------ |
| **Name**         | Display name shown in lists and workflow nodes         |
| **Provider**     | LLM provider (OpenAI, Anthropic, Gemini, Ollama)       |
| **Model**        | Model ID for the selected provider                     |
| **Instructions** | System prompt — defines agent behavior and constraints |

Providers and models come from `config/neuronai-studio.php`. Credentials are read from `config/neuron.php`.

## Tool bindings

Bind tools to give your agent capabilities beyond text generation.

### Binding format

Each binding references a tool by `ref`:

```json
{
  "ref": "db:1",
  "only": ["search"],
  "exclude": []
}
```

| Prefix                | Meaning                                | Example                                 |
| --------------------- | -------------------------------------- | --------------------------------------- |
| `db:{id}`             | Database tool definition               | `db:3`                                  |
| `toolkit:{key}`       | Built-in Neuron toolkit                | `toolkit:calculator`                    |
| `class:{fqn}`         | Scanned PHP Tool class                 | `class:App\\Neuron\\Tools\\WeatherTool` |
| `mcp:{server}:{tool}` | MCP-exposed tool                       | `mcp:filesystem:read_file`              |
| `provider:{name}`     | Provider-native tool (e.g. web search) | `provider:web_search`                   |
| `node:{id}`           | Tool Mode specialist (`NodeAsTool`)    | `node:agent-specialist-1`               |

`node:{id}` is not chosen in the agent form picker — the workflow canvas creates it when a specialist’s **toolset** handle connects to a supervisor’s **tools** handle. See [Tool Mode](/neuronai-studio/workflows/ai-nodes.md#tool-mode-agent-as-tool).

### Filter tools

* **only** — expose only listed tool names from a toolkit or MCP server
* **exclude** — hide specific tool names

Browse available tools in the [Tool Registry](/neuronai-studio/tools/registry-and-codegen.md).

## Tool approval

Enable **Require tool approval** on an agent to gate its tool calls behind a human decision. When on, an agent running inside a workflow pauses before executing any tool and waits for an approve/reject decision in the workflow test harness.

| Field                   | Description                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| `require_tool_approval` | Boolean flag on the agent definition. When `true`, all tool calls require approval          |
| `tool_max_runs`         | Optional int (≥ 1). Caps Neuron tool rounds per node visit (default Neuron = 10 when unset) |
| `parallel_tool_calls`   | Optional bool. When true, Neuron uses parallel tool execution for a single model round      |

* The approval flag applies wherever the agent runs inside a workflow Agent node. A workflow Agent node can override it per node with `require_tool_approval` in the node data.
* Agent nodes can also override `tool_max_runs` / `parallel_tool_calls` in the inspector.
* Approval currently gates **all** tools the agent calls (no per-tool allowlist yet).
* Interrupts are serialized into the trace checkpoint for resume, so bind **class-based tools** — tools with inline `Closure` callbacks cannot be serialized across the pause.

See [Human-in-the-Loop → Tool approval](/neuronai-studio/workflows/human-in-the-loop.md#tool-approval), [AI Nodes → Tool approval](/neuronai-studio/workflows/ai-nodes.md#tool-approval), and [Security & Access](/neuronai-studio/workflows/security-and-access.md#approving-sensitive-tools).

## Memory

Configure per-agent memory on the editor form (stored in `memory_config`):

| Field                       | Description                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Context window**          | Token budget for chat history. Empty inherits `NEURONAI_STUDIO_CHAT_HISTORY_CONTEXT_WINDOW`                             |
| **History driver**          | `eloquent` (persist to thread) or `in_memory` (even when a thread id exists). Empty keeps today's thread-based behavior |
| **Summarization**           | When on, over-budget history is compacted into a persisted summary message instead of silent deletes                    |
| **Summarization threshold** | Optional 0–1 fraction hint for when to compact                                                                          |
| **RAG budget**              | Optional token cap for interpolated `rag_context` (whole chunks first). Empty = no truncation                           |
| **Tool results budget**     | Optional token cap for tool results before they re-enter the prompt/history. Empty = pass-through                       |
| **State fields budget**     | Optional per-field token cap for other `{{placeholders}}`. Empty = pass-through                                         |

Agent nodes can override the same keys in the canvas inspector (`context_window`, `driver`, `summarization_enabled`, `budget_rag`, `budget_tool_results`, `budget_state`). Empty override = inherit from the agent.

Budgets are **opt-in**: with nothing configured, prompt assembly matches prior behavior. Truncations are recorded as `context` / `context_truncation` spans when native tracing is on (see [Runtime & Traces](/neuronai-studio/workflows/runtime-and-traces.md#context-truncation-spans)).

Optional dedicated cheap summarizer model (falls back to the agent's provider/model):

```env
NEURONAI_STUDIO_SUMMARIZER_PROVIDER=openai
NEURONAI_STUDIO_SUMMARIZER_MODEL=gpt-4o-mini
```

See [Playground & Threads](/neuronai-studio/agents/playground-and-threads.md) and [Configuration](/neuronai-studio/reference/configuration.md#memory--summarization).

## Output classes

Workflow **Agent** and **LLM** nodes can request typed responses using PHP output classes — the same `SchemaProperty` pattern used by NeuronAI structured output. Classes are shared between agent playground exports and workflow nodes; define them once under your export path and reference them from the canvas.

### Define a class

Place classes under `app/Neuron/Output/` (or any path listed in `structured_output_scan_paths`):

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;

class LeadProfile
{
    #[SchemaProperty(description: 'Lead email address', required: true)]
    public string $email;

    #[SchemaProperty(description: 'Lead tier', required: false)]
    public ?string $tier = null;
}
```

Requirements:

* Public properties with at least one `SchemaProperty` attribute
* Non-abstract classes only
* Namespace must match `export_namespace` when under `export_path`

The studio discovers classes via `OutputClassRegistry` and lists them in the workflow node inspector. Short names (e.g. `LeadProfile`) resolve to the full class name at runtime.

### Use in workflows

In the workflow editor, enable **Structured output** on an Agent or LLM node and pick the output class. The validated array is written to the node's `output_key` — branch on fields with dot notation in Condition nodes. See [AI Nodes — Structured output](/neuronai-studio/workflows/ai-nodes.md#structured-output) and [State & Conditions](/neuronai-studio/workflows/state-and-conditions.md#conditions-on-structured-objects).

### Export

Workflow export (`php artisan neuronai-studio:export workflow {id}`) emits `structuredInline()` calls and imports for referenced output classes. Agent export follows the same pattern when structured mode is configured on agent nodes in the graph.

When an Agent node has tool approval enabled, the exported node passes `require_tool_approval` to `runInline()` (reading `$agent->require_tool_approval` for definition-backed nodes) or applies the `ToolApproval` middleware for inline agents — so the generated workflow enforces the same approval gate.

## MCP server bindings

Agents can bind entire MCP servers. Configure MCP servers first, then add bindings in the agent form. See [Agent Binding](/neuronai-studio/mcp-servers/agent-binding.md).

## Provider configuration

Add or customize providers in `config/neuronai-studio.php`:

```php
'providers' => [
    'openai' => [
        'label' => 'OpenAI',
        'models' => ['gpt-4o', 'gpt-4o-mini'],
    ],
],
```

Set defaults with `NEURONAI_STUDIO_DEFAULT_PROVIDER` and `NEURONAI_STUDIO_DEFAULT_MODEL`.

## Export

Export the agent to a PHP class:

```bash
php artisan neuronai-studio:export agent {id}
```

See [Export & Production](/neuronai-studio/workflows/export-and-production.md).

## Next steps

* [Playground & Threads](/neuronai-studio/agents/playground-and-threads.md) — test your agent
* [Attachments](/neuronai-studio/agents/attachments.md) — multimodal messages
* [Tools Overview](/neuronai-studio/tools/overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://vibemx.gitbook.io/neuronai-studio/agents/creating-agents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.