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

# Agent Management

> Manage, version, and deploy your saved agents

The Agent Overview page is your control center for all saved agents. Here you can view agent performance, manage versions, and configure deployments.

![Agent Overview](https://mintcdn.com/arttacsolutions/exBco3_ad4-G0WEa/images/agent_overview.png?fit=max\&auto=format\&n=exBco3_ad4-G0WEa\&q=85\&s=f4f36d4e15c3d2727c560681f0de6582)

## Dashboard Overview

At the top, you'll see quick stats:

* **Total Agents**: Number of agents you've created
* **Active**: Agents currently deployed
* **Runs**: Total execution count
* **Total Tokens**: Cumulative token usage

## Agent List

Each agent card shows:

* Agent name and description
* Current version number
* Creation date
* Quick action buttons (Config, Settings, Delete)

### Quick Actions

**Config**: Opens the agent's current version in the Playground where you can edit the YAML configuration

**Settings**: Access general settings, access control, versions, statistics, tools & connections, and cron jobs

**Delete**: Remove the agent and all its versions permanently

## Managing Agent Versions

### Understanding Versions

Every time you save changes to an agent, a new version is created. This gives you:

* **Version history**: See all previous configurations
* **Easy rollback**: Revert to an older version if needed
* **Safe experimentation**: Test changes without losing the working version

### Version States

![Version Management](https://mintcdn.com/arttacsolutions/exBco3_ad4-G0WEa/images/agent_versions.png?fit=max\&auto=format\&n=exBco3_ad4-G0WEa\&q=85\&s=cd1335433b812ccdcc6c3b7087e51e40)

**Current Badge**: The version that's actively deployed and handles all API requests

**Historical Versions**: Previous configurations you can view or deploy

### Deploying a Version

**1. Go to Agent Settings**

Click the settings icon on your agent

**2. Navigate to Versions Tab**

View all available versions

**3. Click Deploy**

Click the **Deploy** button next to the version you want to activate

**4. Confirm**

This version becomes the "Current" version and handles all requests

> [!WARNING]
>
> Deploying a version immediately affects:
>
> * API endpoints
> * Embedded chatbots
> * WebSocket connections
>
> Test thoroughly in the Playground before deploying!

## Agent Settings

Click the **Settings** button on any agent to open the Agent Settings modal. The left sidebar groups configuration into six sections. Expand each section below to see everything you can do.

![Agent Settings modal overview](https://mintcdn.com/arttacsolutions/xwsmX3Kdmvw1ENwl/images/agent_settings_opened.PNG?fit=max\&auto=format\&n=xwsmX3Kdmvw1ENwl\&q=85\&s=ea90bb22577242774bc6adf9489ef8c6)

> [!NOTE]
>
> Most settings can only be changed by the **agent owner**. If you have access to a shared agent you didn't create, the controls appear in read-only mode.

> **General**
>
> The General tab covers the agent's identity, public access, and who is allowed to use the chatbot.
>
> ![Agent Settings General](https://mintcdn.com/arttacsolutions/xwsmX3Kdmvw1ENwl/images/agent_settings_general.png?fit=max\&auto=format\&n=xwsmX3Kdmvw1ENwl\&q=85\&s=272136ddbdcae69a5f3de44d0e995a9f)
>
> **Agent Name**
>
> * Rename the agent inline by clicking the pencil icon, editing the name, and saving.
> * Press `Enter` to save or `Escape` to cancel.
>
> **Public Access**
>
> * Toggle whether the agent is reachable from the public chatbot over WebSocket.
> * When enabled, you must provide an **Allowed Origin URL** (the exact origin external clients connect from) for security.
> * When enabled and fully configured, a banner shows the agent is freely accessible and lets you copy the **Agent Key**.
>
> **Who can use the chatbot?**
>
> After enabling Public Access, choose how visitors are authenticated:
>
> > **Everyone**
> >
> > Visitors chat anonymously. Conversations are not saved.
>
> > **Signed-in users only**
> >
> > Users sign in with your company account and keep a personal Library of their conversations.
>
> **Sign-in system (External Auth)**
>
> * When **Signed-in users only** is selected, pick the **Sign-in system** the chatbot uses to verify who is chatting.
> * These are the External Auth configurations (for example Microsoft Entra ID or OpenID Connect) set up for your company.
> * On every request, the user's token (JWT) is validated against the selected identity provider.
> * If you don't have any configurations yet, use **Configure External Auth Setup** to create one.
>
> ![Signed-in users only and sign-in system selection](https://mintcdn.com/arttacsolutions/xwsmX3Kdmvw1ENwl/images/agent_external_auth_signin.png?fit=max\&auto=format\&n=xwsmX3Kdmvw1ENwl\&q=85\&s=c425b819f005e6faeb4ad60265b561cf)
>
> > [!NOTE]
> >
> > See [External Auth Setup](https://docs.artaios.ai/amas/studio/external-auth.md) for how to create and manage sign-in systems for your company.
>
> **Agent Details**
>
> * **Agent Key**: Unique identifier for API / WebSocket connections (copyable).
>
> * **Architecture**: The agent's architecture type.
>
> * **Entry Point**: The configured entry point.
>
> * **Last Updated**: When the agent was last modified.
>
> > [!WARNING]
> >
> > When Public Access is enabled you must supply an Allowed Origin URL, otherwise external clients cannot use the agent key.

> **Access Control**
>
> Control who inside and outside your organization can see and use the agent.
>
> ![Access Control Settings](https://mintcdn.com/arttacsolutions/xwsmX3Kdmvw1ENwl/images/agent_access_control.png?fit=max\&auto=format\&n=xwsmX3Kdmvw1ENwl\&q=85\&s=456114db59bddc3aed4d6f09e64ba93e)
>
> **Share with Company**
>
> * When enabled, other users in your organization can view and use this agent in Agent Studio.
> * Only you (the owner) can modify settings or deploy versions.
>
> **Show in Artaios**
>
> * When enabled, the agent is published to **Artaios**, the end-user chat
>   product — a separate surface from Agent Studio, where non-technical
>   colleagues use finished agents without touching YAML.
>
> * Works alongside company sharing.
>
> > [!NOTE]
> >
> > **Access Control Summary**
> >
> > * **Agent Studio**: Shows your agents + shared company agents.
> > * **Artaios** (end-user chat product): Shows your agents + shared company agents that also have "Show in Artaios" enabled.
> > * **Public Chatbot**: Configured via Public Access in the General tab.
>
> > [!NOTE]
> >
> > Non-owners see a read-only notice and cannot toggle these options.

> **Versions**
>
> Every save creates a new version, giving you full history and safe rollback.
>
> ![Version Management](https://mintcdn.com/arttacsolutions/exBco3_ad4-G0WEa/images/agent_versions.png?fit=max\&auto=format\&n=exBco3_ad4-G0WEa\&q=85\&s=cd1335433b812ccdcc6c3b7087e51e40)
>
> * **View all versions**: See the complete version history with creation and update times.
>
> * **Current badge**: Highlights the version that is actively deployed and serves all requests.
>
> * **Deploy**: Activate a specific historical version, making it the new "Current" version.
>
> * **View Config**: Open that version's YAML in the Playground to inspect or edit it.
>
> > [!WARNING]
> >
> > Deploying a version immediately affects API endpoints, embedded chatbots, and WebSocket connections. Test in the Playground first.

> **Statistics**
>
> View usage metrics for the agent.
>
> ![Agent Statistics](https://mintcdn.com/arttacsolutions/exBco3_ad4-G0WEa/images/agent_statistics.png?fit=max\&auto=format\&n=exBco3_ad4-G0WEa\&q=85\&s=5b89e1b462d5e331f218614b78ad7ee4)
>
> **Overview**
>
> * Total Sessions
> * Total Answer Generations
>
> **Token Usage**
>
> * Input Tokens
> * Output Tokens
> * Total Tokens
>
> **Averages**
>
> * Answers per Session
>
> * Tokens per Session
>
> * Tokens per Answer
>
> > [!NOTE]
> >
> > Playground preview sessions are not included in these statistics.

> **Tools & Connections**
>
> Review every tool the agent uses and the status of its required connections.
>
> ![Tools & Connections](https://mintcdn.com/arttacsolutions/xwsmX3Kdmvw1ENwl/images/agent_tools_connections.png?fit=max\&auto=format\&n=xwsmX3Kdmvw1ENwl\&q=85\&s=b292a185d3510cd9a080109c7949413f)
>
> * **Grouped by toolkit**: Tools are organized under their toolkit (for example Outlook, Teams) with an icon and tool count.
>
> * **Connection status**: Each tool shows a green check when connected, or a warning when a connection is missing or has issues.
>
> * **Connect / Disconnect**: Authorize a toolkit (or an individual tool) directly from here, or disconnect an existing connection.
>
> * **Issues**: Hover the warning icon to see why a tool isn't ready (for example `No connection found`).
>
> * **Summary footer**: Shows total tools and total issues, with a **Refresh** button to re-check status.
>
> > [!NOTE]
> >
> > Connections rely on the OAuth integrations configured on the [Settings](https://docs.artaios.ai/amas/studio/settings.md) page. Tools without integration requirements show no connection status.

> **Cron Jobs**
>
> Schedule the agent to run automatically on a recurring or one-time basis.
>
> ![Cron Jobs list](https://mintcdn.com/arttacsolutions/xwsmX3Kdmvw1ENwl/images/agent_cron_jobs.png?fit=max\&auto=format\&n=xwsmX3Kdmvw1ENwl\&q=85\&s=671116b3265518655dfc9787ec98c672)
>
> Each cron job card shows its name, description, run type, run time, timezone, and an **Active / Inactive** toggle. You can edit or delete a job from its card.
>
> **Creating a cron job**
>
> Click **New CronJob** to open the configuration form.
>
> ![Create / Edit Cron Job form](https://mintcdn.com/arttacsolutions/xwsmX3Kdmvw1ENwl/images/agent_cron_job_form.png?fit=max\&auto=format\&n=xwsmX3Kdmvw1ENwl\&q=85\&s=3461e913e4ece351b6b0e9f55ffc40e2)
>
> **Name** `string` *required*
>
> A label to identify the cron job (e.g. "Morning sync").
>
> **Description** `string`
>
> Optional notes describing what the job does.
>
> **Run frequency** `enum` *required*
>
> How often the job runs: **Daily**, **Weekly**, **Monthly**, or **One Time**.
>
> **Run Time** `time` *required*
>
> The time of day the job executes.
>
> **Timezone** `string` *required*
>
> A valid IANA timezone (e.g. `America/Mexico_City`) used to interpret the run time.
>
> **Execute Date** `date`
>
> Shown for **One Time** jobs. The single date the job runs.
>
> **Weekdays** `array`
>
> Shown for **Weekly** jobs. Choose at least one weekday (Mon–Sun).
>
> **Day of month** `number`
>
> Shown for **Monthly** jobs. Day 1–31, or `-1` to run on the last day of the month.
>
> **Agent Prompt** `string` *required*
>
> The text sent to the agent as its input each time the job runs.
>
> **1. Open the form**
>
> Click **New CronJob** in the Cron Jobs tab.
>
> **2. Set the schedule**
>
> Choose a run frequency, time, and timezone. Fill in the frequency-specific fields (date, weekdays, or day of month).
>
> **3. Provide the prompt**
>
> Enter the **Agent Prompt** that will be sent to the agent on each run.
>
> **4. Create**
>
> Click **Create Cron Job**. The job appears in the list and runs automatically.
> \[!TIP] The new job shows in the list with an **Active** status.
>
> **Managing jobs**
>
> * **Activate / Deactivate**: Use the toggle on each card to pause or resume a job without deleting it.
>
> * **Edit**: Update any field via the edit (pencil) icon.
>
> * **Delete**: Permanently remove a job. This action cannot be undone.
>
> > [!TIP]
> >
> > Use the timezone field carefully — run times are interpreted in the timezone you select, not the viewer's local time.

## Creating New Versions

When you edit a saved agent in the Playground:

**1. Click Config on Agent Card**

Opens the agent in Playground with current version loaded

![Loading Agent](https://mintcdn.com/arttacsolutions/exBco3_ad4-G0WEa/images/agent_loading.png?fit=max\&auto=format\&n=exBco3_ad4-G0WEa\&q=85\&s=efb98d6d297ff9ebc9073d5cfea899f2)

**2. Make Your Changes**

Edit the YAML configuration as needed

**3. Save as New Version**

Click **Save as New Version** button (only appears when editing)

**4. Version Created**

A new version is automatically created and appears in the Versions tab

> [!NOTE]
>
> The Playground shows a version dropdown when editing an agent. This lets you switch between versions to view their configurations.

## Best Practices

> [!TIP]
>
> **Test before deploying**: Always test new versions in the Playground before deploying to production

> [!TIP]
>
> **Keep a stable version**: Maintain one tested version as "production" while experimenting with new ones

> [!TIP]
>
> **Monitor statistics**: Use the Statistics tab to track usage patterns and optimize performance

> [!TIP]
>
> **Check access control**: Review who can access your agent before enabling company sharing

> [!TIP]
>
> **Secure public agents**: When exposing an agent publicly, prefer **Signed-in users only** with an External Auth sign-in system so only verified users can chat.

> [!TIP]
>
> **Verify cron timezones**: Double-check the timezone on each cron job — run times are interpreted in the selected timezone, not your local one.

## Sharing Agents

To share an agent with your organization:

1. Click **Settings** on the agent card
2. Go to **Access Control** tab
3. Enable **Share with Company**
4. Optionally enable **Show in Artaios** to publish it to the Artaios end-user chat product

> [!NOTE]
>
> Shared agents are read-only for other users. Only the owner can modify settings or deploy versions.

## Common Questions

**Q: What happens to my API connections when I deploy a new version?**

A: They immediately start using the new version. No downtime, but behavior may change based on your config updates.

**Q: Can I restore a deleted agent?**

A: No. Deletion is permanent. Make sure you export the YAML configuration if you might need it later.

**Q: How many versions can I have?**

A: Unlimited. All versions are stored and accessible.

## What's Next?

> **[REST API Tutorial](https://docs.artaios.ai/documentation/integration/rest-api-tutorial.md)**
>
> Connect your agents to applications

> **[Chatbot Integration](https://docs.artaios.ai/documentation/integration/chatbot-integration.md)**
>
> Embed an agent in your website

> **[YAML Configuration](https://docs.artaios.ai/amas/yaml-configuration.md)**
>
> Learn complete YAML syntax

> **[Agent Types](https://docs.artaios.ai/amas/agent_config/types_config/agent-types.md)**
>
> Learn about agent architectures


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