> ## 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.
## 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
**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
Click the settings icon on your agent
View all available versions
Click the **Deploy** button next to the version you want to activate
This version becomes the "Current" version and handles all requests
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.
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.
The General tab covers the agent's identity, public access, and who is allowed to use the chatbot.
**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:
Visitors chat anonymously. Conversations are not saved.
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.
See [External Auth Setup](/documentation/studio/external-auth) 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.
When Public Access is enabled you must supply an Allowed Origin URL, otherwise external clients cannot use the agent key.
Control who inside and outside your organization can see and use the agent.
**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.
**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.
Non-owners see a read-only notice and cannot toggle these options.
Every save creates a new version, giving you full history and safe rollback.
* **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.
Deploying a version immediately affects API endpoints, embedded chatbots, and WebSocket connections. Test in the Playground first.
View usage metrics for the agent.
**Overview**
* Total Sessions
* Total Answer Generations
**Token Usage**
* Input Tokens
* Output Tokens
* Total Tokens
**Averages**
* Answers per Session
* Tokens per Session
* Tokens per Answer
Playground preview sessions are not included in these statistics.
Review every tool the agent uses and the status of its required connections.
* **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.
Connections rely on the OAuth integrations configured on the [Settings](/documentation/studio/settings) page. Tools without integration requirements show no connection status.
Schedule the agent to run automatically on a recurring or one-time basis.
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.
A label to identify the cron job (e.g. "Morning sync").
Optional notes describing what the job does.
How often the job runs: **Daily**, **Weekly**, **Monthly**, or **One Time**.
The time of day the job executes.
A valid IANA timezone (e.g. `America/Mexico_City`) used to interpret the run time.
Shown for **One Time** jobs. The single date the job runs.
Shown for **Weekly** jobs. Choose at least one weekday (Mon–Sun).
Shown for **Monthly** jobs. Day 1–31, or `-1` to run on the last day of the month.
The text sent to the agent as its input each time the job runs.
Click **New CronJob** in the Cron Jobs tab.
Choose a run frequency, time, and timezone. Fill in the frequency-specific fields (date, weekdays, or day of month).
Enter the **Agent Prompt** that will be sent to the agent on each run.
Click **Create Cron Job**. The job appears in the list and runs automatically.
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.
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:
Opens the agent in Playground with current version loaded
Edit the YAML configuration as needed
Click **Save as New Version** button (only appears when editing)
A new version is automatically created and appears in the Versions tab
The Playground shows a version dropdown when editing an agent. This lets you switch between versions to view their configurations.
## Best Practices
**Test before deploying**: Always test new versions in the Playground before deploying to production
**Keep a stable version**: Maintain one tested version as "production" while experimenting with new ones
**Monitor statistics**: Use the Statistics tab to track usage patterns and optimize performance
**Check access control**: Review who can access your agent before enabling company sharing
**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.
**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
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?
Connect your agents to applications
Embed an agent in your website
Learn complete YAML syntax
Learn about agent architectures
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.