> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage Agents in Tyk AI Studio
> How to create and manage Agents in Tyk AI Studio, which connect an Agent plugin to an App to make a conversational AI experience available to users.
## Availability
| Edition | Deployment Type |
| :- | :- |
| [Community](/docs/ai-management/ai-studio/overview#community-edition) & [Enterprise](/docs/ai-management/ai-studio/overview#enterprise-edition) | Self-Managed, Hybrid |
> **Experimental Feature**: Agents depend on Agent plugins, which are currently experimental. The API and behavior may change in future releases.
An **Agent** is an administrator-managed object in Tyk AI Studio. It connects an [Agent plugin](/docs/ai-management/ai-studio/plugins/studio-agent) to an [App](/docs/ai-management/ai-studio/admin-apps), and controls which Teams can use it. Once you activate an Agent, it appears as a conversational AI option for its users in the AI Portal.
This page covers the **Agent** object, managed in the **Agents** section of the AI Studio dashboard. For the plugin code that powers an Agent's conversation logic, see [AI Studio Agent Plugins](/docs/ai-management/ai-studio/plugins/studio-agent).
## Agent vs Agent Plugin
These two terms sound alike, but they refer to different things.
| Term | What It Is | Where You Manage It |
| - | - | - |
| **Agent plugin** | The gRPC plugin code that implements the conversation logic. A developer builds and deploys it. | The **Plugins** section of the AI Studio dashboard, with hook type `agent`. See [AI Studio Agent Plugins](/docs/ai-management/ai-studio/plugins/studio-agent). |
| **Agent** | A configuration object that binds an Agent plugin to an App, sets access control, and stores plugin-specific settings. An administrator creates it directly in the UI, no code required. | The **Agents** section of the AI Studio dashboard, covered on this page. |
An Agent plugin is reusable. You can create several Agents from the same plugin, each linked to a different App, configuration, and set of Teams.
## Prerequisites
Before you create an Agent, confirm that you have:
* An active Agent plugin (hook type `agent`) in the **Plugins** section of the AI Studio dashboard. See [AI Studio Agent Plugins](/docs/ai-management/ai-studio/plugins/studio-agent) to build or install one.
* An active [App](/docs/ai-management/ai-studio/admin-apps) with an active credential and at least one LLM assigned. The App supplies the LLMs, [Tools](/docs/ai-management/ai-studio/tools), and [Data Sources](/docs/ai-management/ai-studio/datasources-rag) that the Agent can use.
## Configuration
The **Create Agent** form has these fields:
* **Name**: A descriptive name for the Agent. Required.
* **Description**: An optional description of what the Agent does. Users see this description in the AI Portal.
* **Plugin**: The Agent plugin that powers this Agent's conversations. The list shows only active plugins with the `agent` hook type. Required.
* **App**: The [App](/docs/ai-management/ai-studio/admin-apps) that supplies LLMs, Tools, and Data Sources to this Agent. Required.
* **Configuration (JSON)**: Plugin-specific settings, such as a system prompt or a temperature value. AI Studio checks that this value is valid JSON before you save. It does not validate the content against the plugin's configuration schema.
* **Teams**: The [Teams](/docs/ai-management/ai-studio/teams) that can use this Agent. Leave this field empty to make the Agent available to all users. Some Agent screens label this same access control **Groups**.
* **Active**: Whether the Agent is available to users. This is on by default.
## How to Create an Agent
1. Navigate to the **Agents** section in the AI Studio dashboard.
2. Click **Create Agent**.
3. Enter a **Name** and, optionally, a **Description**.
4. Select the **Plugin** that will power the Agent's conversations.
5. Select the **App** that provides the Agent's LLMs, Tools, and Data Sources.
6. Enter any plugin-specific settings in the **Configuration (JSON)** field.
7. Optionally, restrict access by selecting one or more **Teams**. Leave this field empty for public access.
8. Click **Create** to save the Agent.
You can also create an Agent immediately after adding a new Agent plugin. The **Add Plugin** wizard detects the `agent` hook type. It then offers an optional **Agent Setup** step that opens the same form, with the new plugin already selected.
## What Happens When You Save
Only Studio Administrators can create, update, activate, deactivate, or delete Agents.
When you save an Agent, AI Studio checks that:
* The selected Plugin exists, is active, and supports the `agent` hook type.
* The selected App exists, is active, has an active credential, and has at least one LLM assigned.
If these checks pass, AI Studio creates the Agent and generates a URL-friendly slug from its name. If the Agent is active, it appears in the **Agents** section of the AI Portal, alongside Chat Rooms. Members of any Team you selected can see and use it. If you left Teams empty, every user can see and use it.
LLM calls that the Agent makes still go through the [AI Gateway](/docs/ai-management/ai-studio/proxy) and count against the App's [budgets](/docs/ai-management/ai-studio/budgeting).
## Chat API
Users open an Agent from the [Chat Interface](/docs/ai-management/ai-studio/chat-interface) at `/chat/agent/:id`. From v2.2.0, the chat front end (`CHAT_UI_V2_ENABLED`, on by default) uses the same per-turn API for Agents as for chat rooms:
| Method | Path | Purpose |
| :- | :- | :- |
| `POST` | `/common/agents/:id/sessions` | Creates an Agent session. To continue a session that is still in memory, send `{"session_id": "..."}`. |
| `POST` | `/common/agent-sessions/:session_id/runs` | Sends `{"message": "..."}` and streams the reply as an AI SDK UI message stream. Agents support new messages only. A request with `after_message_id`, `regenerate`, or `tool_results` returns `400`. |
| `POST` | `/common/agent-sessions/:session_id/cancel` | Stops the plugin stream of the current turn |
| `GET` | `/common/agent-sessions/:session_id/messages/v2` | Returns the transcript of the session: text, reasoning, tool calls, and results |
An Agent session stays in memory between turns for `CHAT_SESSION_IDLE_TTL` (default 10 minutes). The session keeps a transcript in memory. AI Studio sends the transcript to the plugin as `history` on every turn. The plugin SDK contract (`HandleAgentMessage`, `AgentMessageChunk`) did not change. The v1 SSE endpoints (`/common/agents/:id/stream` and `/common/agents/:id/message`) still work.
AI Studio maps the plugin chunks to the stream as follows:
| Plugin chunk | Stream part |
| :- | :- |
| `CONTENT` | Text |
| `THINKING` | Reasoning |
| `TOOL_CALL` | A tool call. `metadata.tool_name` is the tool, and `metadata.parameters` are the arguments. |
| `TOOL_RESULT` | The result of the most recent unanswered call with the same `tool_name` |
| `ERROR` | An error |
| `DONE`, or `is_final` | The end of the turn |
AI Studio adds a `tool_call_id` to `TOOL_CALL` and `TOOL_RESULT` chunks, so that the chat can pair them. Plugins do not need to set it.
To show specific tool calls of an Agent with a custom web component, use a plugin tool renderer. Refer to [Custom Tool Renderers From Plugins](/docs/ai-management/ai-studio/chat-interface#custom-tool-renderers-from-plugins).
## Managing Existing Agents
From the **Agents** list, you can filter by status. For each Agent, you can view its details, edit it, activate or deactivate it, or delete it.
### Agent Details
The Agent details page shows:
* **Overview**: The Agent's description, slug, and creation date.
* **Configuration**: Links to the underlying Plugin and App, and the current **Configuration (JSON)** value.
* **Available Resources**: The LLMs, Tools, and Data Sources that the Agent inherits from its App.
* **Access Control**: The Teams that can use the Agent, or **Public** if none are set.
* **Test Interface**: A built-in chat panel. Use it to send test messages to an active Agent from within the admin UI, and see its streamed response.