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

# Build an Agent

> Create powerful AI agents tailored to your specific needs and workflows

## Overview

Aster Agents makes it easy to create custom AI agents that can perform specific tasks, access your data, and integrate with your workflows. Whether you need a customer support agent, data analyst, or specialized assistant, you can build exactly what your team needs.

## Getting Started

### Creating Your First Agent

<Steps>
  <Step title="Open the Agents section" icon="robot">
    Navigate to **Control Hub** → **Agents**.
  </Step>

  <Step title="Create a new agent" icon="wand-magic-sparkles">
    Click **"Create New Agent"**.
  </Step>

  <Step title="Configure the basic settings" icon="sliders">
    * **Name**: What your team will call this agent
    * **Description**: What this agent does and when to use it
    * **Stage**: Development (for testing) or Released (for team use)
  </Step>
</Steps>

### Agent Configuration

#### System Prompt

The system prompt is the foundation of your agent's behavior.

<AccordionGroup>
  <Accordion title="Start minimal, then iterate" icon="flask">
    Begin with a simple prompt using your best available model, then add instructions based on failure modes you observe during testing. Resist the urge to anticipate every edge case upfront.
  </Accordion>

  <Accordion title="Use a response framework" icon="list-check">
    Give your agent a clear process to follow (e.g., "1. Understand the request, 2. Gather context, 3. Provide solution, 4. Confirm resolution"). This creates consistency without rigid scripting.
  </Accordion>

  <Accordion title="Include canonical examples" icon="lightbulb">
    A few well-chosen examples are worth more than paragraphs of rules. Show the agent what good looks like for your most common scenarios.
  </Accordion>

  <Accordion title="Define clear escalation paths" icon="shield-halved">
    Agents perform better when they know exactly when to ask for help. Be explicit: "Escalate billing disputes over \$500" is better than "escalate complex issues."
  </Accordion>

  <Accordion title="Avoid laundry lists of edge cases" icon="circle-info">
    Stuffing your prompt with every possible rule creates confusion. Focus on general principles that help the agent reason through novel situations.
  </Accordion>

  <Accordion title="Organize longer prompts into sections" icon="file-lines">
    For complex agents, use clear headers or XML-style tags to separate concerns (role, guidelines, process, output rules). This helps the model parse your intent and makes prompts easier to maintain.
  </Accordion>

  <Accordion title="Provide context about data and systems" icon="database">
    If your agent queries databases or accesses specific tools, briefly explain what data is available and any relevant business logic. Agents perform better when they understand the context they're operating in.
  </Accordion>
</AccordionGroup>

**Include platform context.** Help your agent understand its environment—the current date, who they're talking to, and how their output is displayed. We recommend including this at the end of your system prompt:

```
The current date is {{CURRENT_DATE}} and the user is {{USER_EMAIL}}.

<aster_context>
You are an AI Agent on the Aster Agents platform. When you call tools, the user can see both your inputs and the results. Your messages are rendered using markdown, so use formatting like **bold**, *italic*, `code`, lists, and tables to organize your responses.
</aster_context>
```

#### Model Selection

Choose the AI model that powers your agent:

* **Default Models**: Use your organization's default chat model
* **Specialized Models**: Select specific models for different capabilities
* **Reasoning Models**: Use advanced models like o1 for complex problem-solving
* **Performance Models**: Balance speed and capability based on your needs

#### Prompt Variables

Customize your agent's behavior with dynamic variables (case-insensitive):

* **`{{USER_EMAIL}}`**: The current user's email address
* **`{{USER_NAME}}`**: The current user's full name
* **`{{ORG_NAME}}`**: Your organization's name
* **`{{CURRENT_DATE}}`**: The current date and time (UTC)

You can also use nested access like `{{user.email}}` or `{{org.name}}`.

### Tools & Capabilities

#### Provider Tools

When you select a model, you may see built-in tools offered by that provider (e.g., Google Search for Gemini, Web Search for OpenAI, Image Generation for GPT models). These run directly within the provider's infrastructure with no setup required.

Provider tools appear automatically based on your selected model. Just toggle them on like any other tool.

#### Default-on tools

A small set of safe, broadly useful primitives come **pre-checked when you create a new agent**, so every agent starts with a sensible baseline instead of an empty toolbox:

* **[Read File](/tools/read_file)** — open a single file the agent can already reach (sandbox, attachment, knowledge-base file, or URL) as text or vision.
* **[Run Code](/tools/execute_python)** — run code in a sandbox; pairs with attachments and knowledge-base files for parsing and transforming uploads.
* **[Load Skill](/tools/load_skill)** — read-only access to the skill channel, so an agent can pull in a packaged set of instructions by name when it needs one.

They're default-*on*, not forced: they behave like any other tool, so you can uncheck any of them on any agent at any time, and it stays off. The same defaults are applied when an agent is created programmatically — for example, by the **[Build Agents](/features/multi-agent-workflows)** agent via `manage_agents`, or through the API — so agents built without the form get the same baseline.

#### Built-in Tools

Give your agent access to powerful capabilities:

<CardGroup cols={2}>
  <Card title="Files & Content" icon="file-lines">
    * **Read File**: Open a sandbox file, attachment, KB file, or URL *(default-on)*
    * **URL Scraping**: Extract content from specific websites
    * **Knowledge Base Search**: Access your organization's documents
  </Card>

  <Card title="Web & Research" icon="magnifying-glass">
    * **Web Search**: Find current information online
    * **Ask Web**: Get AI-powered answers from web sources
  </Card>

  <Card title="Data & Analysis" icon="database">
    * **Run Code**: Execute code in a sandbox for data analysis and processing *(default-on)*
    * **Database Queries**: Connect to Postgres, Snowflake, and other databases
  </Card>

  <Card title="Communication & Productivity" icon="envelope">
    * **Send Email**: Automate email communications
    * **Generate PowerPoint**: Create presentations from data
    * **API Calls**: Integrate with external services
    * **Schedule Task**: Create [scheduled tasks](/features/scheduled-tasks) during conversations (e.g., "send me a daily report")
  </Card>

  <Card title="Social Media & Content" icon="comments">
    * **Reddit Search**: Research discussions and communities
    * **TikTok Search**: Find relevant video content
  </Card>
</CardGroup>

#### Multi-Agent Capabilities

Create sophisticated workflows with agent collaboration:

* **Call Agent Tool**: Let agents work together on complex tasks
* **Agent Hierarchies**: Design workflows where specialized agents handle specific parts
* **Task Delegation**: Route different types of requests to appropriate agents

#### Integrations

Connect your agent to your existing tools and data:

* **Database Connections**: Postgres, Snowflake, and more
* **Cloud Storage**: Access files and documents
* **Third-party APIs**: Connect to your business systems
* **Knowledge Bases**: Search your organization's documents

### Value & ROI (optional)

Every time an agent runs, the platform automatically estimates its **cost** (token usage × model price). The optional **Value** setting lets you put a dollar figure on the *other* side of that equation — what the agent's work is worth — so you can see **ROI**, not just spend.

It's completely optional. Leave it off (the default) and nothing changes: you'll still see cost, just no value or ROI. Turn it on with the **Value** card on the agent's configuration page and pick one of two rules:

* **When the agent runs** — every conversation the agent has is worth a set amount (e.g. "\$25 per conversation").
* **When a specific tool is used** — value is tied to an outcome, like sending an email or writing a record. You pick the tool from the ones the agent already has enabled, and choose whether it counts once per conversation or once per tool call (e.g. "\$50 per email sent").

Once set, value appears per-conversation in the **Inbox** and rolls up — alongside ROI — on the **Analytics dashboard**, both per-agent and per-user. Until an agent actually earns value, the ROI reads **N/A** rather than a misleading `$0`.

<Note>
  Value is an *estimate* you define, not booked revenue — a proxy for the outcome an agent drives. Use it to compare agents and justify spend, not as a system of record.
</Note>

## Advanced Configuration

### Agent Stages

Manage your agent development lifecycle:

* **Development**: Test and iterate on agent behavior
* **Released**: Deploy to your team for production use
* **Visual Grouping**: Development agents appear separately in selection menus

### Version History

Every time you save an agent, its configuration (system prompt, model, tools,
and connected knowledge bases, skills, and MCP servers) is captured as a
version automatically — no extra step.

* Open an agent and click **History** to see the timeline of changes, newest first.
* The version currently in use is marked **Current**.
* Click **Restore** on any earlier version to roll the agent's configuration
  back to that point. Restore takes effect immediately.

<Note>
  Save or discard any unsaved edits before restoring — restore replaces the
  agent's current configuration, so it's blocked while you have pending changes.
</Note>

Identical saves are de-duplicated, so the history only grows when something
actually changes.

### Multi-Agent Workflows

Design complex workflows with multiple specialized agents:

**Example Workflow:**

<Steps>
  <Step title="Research Agent" icon="magnifying-glass">
    Gathers information from web and databases.
  </Step>

  <Step title="Analysis Agent" icon="brain">
    Processes data and identifies insights.
  </Step>

  <Step title="Presentation Agent" icon="file-lines">
    Creates formatted reports and presentations.
  </Step>

  <Step title="Review Agent" icon="list-check">
    Quality checks and finalizes deliverables.
  </Step>
</Steps>

### Knowledge Base Integration

Connect your agents to your organization's knowledge:

* **Selective Access**: Choose which knowledge bases each agent can search
* **Automatic Discovery**: Agents find relevant information during conversations
* **Context Awareness**: Search results inform agent responses naturally

### Agent Tags

Organize your agents with tags to help your team discover and select the right agent for their needs.

#### Adding Tags

Tags are created automatically when you assign them to an agent:

<Steps>
  <Step title="Find the Tags field" icon="sliders">
    In the agent editor, find the **Tags** field under **General** settings.
  </Step>

  <Step title="Add a tag" icon="wand-magic-sparkles">
    Click **"Add tag..."** to select existing tags or create new ones.
  </Step>

  <Step title="Create new tags instantly" icon="bolt">
    Type a new tag name and press Enter to create it instantly.
  </Step>

  <Step title="Categorize your agent" icon="list-check">
    Add multiple tags to categorize your agent (recommended: 1-3 tags per agent).
  </Step>
</Steps>

#### Using Tags in Chat

When starting a conversation, users can filter agents by tag:

* Click **Switch Agent** to open the agent selector
* Use the left sidebar to browse by tag category
* Select a tag to see only agents in that category
* Combine with search to find specific agents within a category

#### Tag Best Practices

<Tip>
  **Start Simple**: Begin with 3-5 broad categories (e.g., "Sales", "Support", "Analytics"), then add more specific tags as your library grows.
</Tip>

**Common Tag Categories:**

* **By Function**: Sales, Customer Support, Marketing, Data Analysis
* **By Department**: Finance, Engineering, Operations, Legal
* **By Specialty**: Technical, Creative, Research, Reporting

**Naming Tips:**

* Use clear, descriptive names (e.g., "Customer Support" not "CS")
* Keep tag names short (under 20 characters)
* Be consistent with capitalization

## Best Practices

### Tool Selection

<AccordionGroup>
  <Accordion title="Curate a minimal set" icon="screwdriver-wrench">
    If a human can't definitively say which tool should be used in a given situation, the agent won't do better. Avoid overlapping functionality.
  </Accordion>

  <Accordion title="Match tools to purpose" icon="toggle-on">
    Only enable tools your agent actually needs. Extra tools create decision overhead and can slow response time.
  </Accordion>

  <Accordion title="Keep tool guidance high-level" icon="circle-info">
    Each tool has built-in instructions explaining how to use it. Your system prompt should focus on *when* to use tools in the workflow, *which* tools to prefer for which situations, and *what not to do*—not detailed instructions that duplicate or conflict with the tool's own guidance.
  </Accordion>
</AccordionGroup>

### Long-Running Workflows

Agents that perform multi-step work (building reports, processing many files, generating complex outputs) benefit from explicit workflow structure in the system prompt.

**Save intermediate results.** When your agent builds something in stages (e.g., a multi-tab spreadsheet, a multi-section report), instruct it to save and publish each stage as a downloadable file before moving to the next. This protects against lost work and gives users visibility into progress.

```
After completing each section, save the workbook and provide a download link
before proceeding to the next section.
```

**Use auto-proceed prompts for chained work.** If your workflow has multiple sequential steps that don't need user input between them, tell the agent to proceed automatically rather than waiting for confirmation after each step.

```
Complete all four report sections sequentially in a single response.
Do not wait for confirmation between sections. Save a checkpoint after each.
```

### Knowledge Base Guidance in System Prompts

**Guide file identification in multi-entity KBs.** When a knowledge base contains documents from many similarly-named items (e.g., "Project Alpha-A", "Project Alpha-B", "Project Beta-A"), semantic search can return results from the wrong entity. Instruct your agent to filter `extracted_data.json` by exact field values rather than relying on search alone for file identification.

```
To identify files for a specific entity, load extracted_data.json and filter
by the entity name field. Do not rely on search_knowledge_base to find all
files for an entity — search results are ranked by relevance and may include
files from similarly-named entities.
```

**Tell the agent what data is already available.** Agents have access to pre-extracted content in their code sandbox (see [Run Code — Knowledge base file access](/tools/execute_python#knowledge-base-file-access)), but won't always use it unless guided. If your agent's workflow involves processing many files, your system prompt should tell it which data source to start with and when to fall back to reading raw content.