Agents - AgentWarden

What is an Agent?

An Agent in AgentWarden represents an AI system, bot, or automated process that performs actions on behalf of your organization. Each agent has its own set of permissions, logs, and approval workflows.

Agent Properties

Every agent in AgentWarden has the following properties:

string

required

Unique identifier for the agent (UUID format)

name

string

required

Human-readable name for the agent (e.g., “customer-support-bot”)

description

string

Optional description of what the agent does

status

string

default:"active"

Agent status: active or inactive. Inactive agents cannot perform any actions.

created_at

datetime

When the agent was created

created_by

string

User ID of who created the agent

Creating Agents

Via Dashboard

Navigate to Agents

Click Agents in the sidebar

Click Create Agent

Click the Create Agent button

Fill Form

Provide name and optional description

Save

Click Create to save

Via API

curl -X POST https://api.agentwarden.io/api/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-bot",
    "description": "Handles customer support requests and refunds"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "customer-support-bot",
  "description": "Handles customer support requests and refunds",
  "status": "active",
  "created_at": "2024-02-21T10:30:00Z"
}

Agent Lifecycle

1. Creation

Agents start as active by default and can immediately be assigned permissions.

2. Active State

While active, agents can:

Have permissions checked via SDK/API
Log actions
Trigger approval workflows

3. Inactive State

When set to inactive, agents:

Cannot perform any actions (all checks return allowed: false)
Retain all historical logs
Keep their permissions (but they’re not enforced)

4. Deletion

Deleting an agent:

Removes the agent permanently
Deletes all associated permissions
Preserves historical logs for audit purposes

Agent deletion is permanent and cannot be undone. Historical logs are preserved but the agent cannot be reactivated.

Agent Naming Best Practices

Use Descriptive Names

customer-support-bot
email-marketing-agent
billing-automation
devops-deployer
data-sync-worker

Naming Conventions

We recommend using kebab-case (lowercase with hyphens) for agent names:

✅ customer-support-bot
✅ billing-automation
❌ Customer Support Bot
❌ customerSupportBot

Include Purpose in Name

Good agent names should clearly indicate:

What the agent does
Where it operates (if multiple environments)

production-email-sender
staging-database-migrator
support-ticket-automator

Managing Multiple Agents

Organization by Function

Group agents by their primary function:

Customer-Facing
Internal Operations
DevOps

support-chat-bot
email-responder
review-moderator

data-sync-worker
report-generator
backup-automator

deployment-agent
monitoring-bot
incident-responder

Environment Separation

Consider creating separate agents for different environments:

production-deployer
staging-deployer
development-deployer

This allows you to:

Set different permissions per environment
Track actions separately
Require approvals only in production

Agent Limits by Plan

The number of agents you can create depends on your plan:

Plan	Max Agents	Best For
Free	2	Testing & small projects
Pro	10	Growing teams
Business	50	Large organizations
Enterprise	Unlimited	Enterprise deployments

Upgrade Your Plan

Need more agents? Upgrade your plan in the dashboard

Agent Permissions

Each agent has its own set of permissions that define what actions it can perform. See the Permissions guide for details.

Common Agent Types

Customer Support Agents

Handle customer interactions and basic support tasks:

# Example: Customer support bot with refund permissions
actions = [
    "stripe.refund",        # Process refunds
    "zendesk.ticket.update", # Update support tickets
    "email.send",           # Send emails
]

Data Processing Agents

Automated data pipelines and ETL jobs:

actions = [
    "database.read",
    "api.fetch",
    "s3.upload",
    "slack.notify"
]

DevOps Agents

Deployment and infrastructure automation:

actions = [
    "deploy.staging",      # Auto-deploy to staging
    "deploy.production",   # Requires approval
    "database.migrate",
    "cloudflare.purge_cache"
]

Marketing Agents

Email campaigns and social media automation:

actions = [
    "mailchimp.send_campaign",
    "twitter.post",
    "analytics.track_event"
]

Best Practices

1. One Agent Per Purpose

Create separate agents for different purposes rather than one “super agent”. This provides:

Better permission isolation
Clearer audit trails
Easier debugging

2. Use Descriptive Names

Agent names should clearly indicate their purpose. Future you (and your team) will thank you.

3. Set Status to Inactive When Not in Use

If an agent is temporarily not needed, set it to inactive instead of deleting it. This preserves:

Historical logs
Permission configurations
The ability to reactivate later

4. Document Agent Responsibilities

Use the description field to document:

What the agent does
When it runs
Who maintains it
Any special considerations

5. Review Agent Activity Regularly

Periodically review logs to ensure agents are:

Operating as expected
Not being blocked unexpectedly
Not exceeding their intended scope

Monitoring Agents

View All Agents

The Agents page shows all your agents with:

Status indicators (active/inactive)
Creation dates
Quick actions (manage, delete)

View Agent Activity

Click on any agent to see:

Assigned permissions
Recent log activity
Approval requests
Performance metrics

Alerts

Set up alerts for:

High failure rates
Unusual activity patterns
Permission violations
Approval backlogs

Alerts are available on Business and Enterprise plans. Learn more

FAQ

Can I rename an agent?

Yes! You can update an agent’s name and description at any time through the dashboard or API. The agent ID remains the same.

What happens to logs when I delete an agent?

Logs are preserved for audit purposes even after agent deletion. You can still view historical logs in the dashboard.

Can I transfer an agent to another organization?

No, agents belong to a single organization. You’ll need to recreate the agent in the destination organization.

How many actions can an agent perform?

There’s no limit on the number of actions an agent can attempt. However, your plan may limit the number of logs stored per month.

Can multiple users manage the same agent?

Yes, all users in your organization can view and manage all agents (permissions depend on their role).

Next Steps

Permissions

Learn how to define what your agents can do

Approvals

Set up human approval workflows

SDK Integration

Integrate agents into your application

View Logs

Monitor agent activity in real-time

Get Started

Core Concepts

SDK

Integration Guides

​What is an Agent?

​Agent Properties

​Creating Agents

​Via Dashboard

​Via API

​Agent Lifecycle

​1. Creation

​2. Active State

​3. Inactive State

​4. Deletion

​Agent Naming Best Practices

​Use Descriptive Names

​Naming Conventions

​Include Purpose in Name

​Managing Multiple Agents

​Organization by Function

​Environment Separation

​Agent Limits by Plan

Upgrade Your Plan

​Agent Permissions

​Common Agent Types

​Customer Support Agents

​Data Processing Agents

​DevOps Agents

​Marketing Agents

​Best Practices

​Monitoring Agents

​View All Agents

​View Agent Activity

​Alerts

​FAQ

​Next Steps

Permissions

Approvals

SDK Integration

View Logs

What is an Agent?

Agent Properties

Creating Agents

Via Dashboard

Via API

Agent Lifecycle

1. Creation

2. Active State

3. Inactive State

4. Deletion

Agent Naming Best Practices

Use Descriptive Names

Naming Conventions

Include Purpose in Name

Managing Multiple Agents

Organization by Function

Environment Separation

Agent Limits by Plan

Agent Permissions

Common Agent Types

Customer Support Agents

Data Processing Agents

DevOps Agents

Marketing Agents

Best Practices

Monitoring Agents

View All Agents

View Agent Activity

Alerts

FAQ

Next Steps