Agents

Agent Dashboard Overview

The agent dashboard provides a list of your agents. This page helps you monitor your agent's status, usage metrics, and recent activity.

Managing an Agent

You can select a specific agent to view and manage its details. The agent detail page provides a list of the agent's inputs and outputs, recent sessions and overview of costs.

Agent Input & Output

Agents receive data from various sources and send data to various destinations (input and output, or we call it IO).

You can think of the agent as an intelligent black box that receives data from sources and responds with data which is sent to the configured destinations.

Read the Agent IO guide for more information.

You can add a new input or output by clicking the plus button in the agent IO visualization.

When you agent is invoked, it will process the data and send the output to the output destination.

The agent request object will contain a property called trigger that will contain the source that triggered the agent. You can use this to determine the source of the data and process it accordingly. This is particularly useful when you are using multiple sources to trigger the same agent.

import type { AgentContext, AgentRequest, AgentResponse } from '@agentuity/sdk';

export default async function Agent(
 req: AgentRequest,
 resp: AgentResponse,
 ctx: AgentContext
) {
  ctx.logger.info('trigger was %s', req.trigger);
  return resp.text("ok");
}

from agentuity import AgentRequest, AgentResponse, AgentContext

async def run(request: AgentRequest, response: AgentResponse, context: AgentContext):
  context.logger.info('trigger was %s', request.trigger)
  return response.text("ok")

Agent Webhook Source

To configure your agent to receive data from a webhook, you need to add a new webhook source. When receiving data from a webhook, the agent will send the data to the agent's inputs asynchronously without waiting for the agent to finish processing the data.

For Webhook sources, you can require authorization to access the webhook. This is useful if you want to protect your webhook from unauthorized access.

The following authentication methods are supported:

When using the Bearer, Basic or Header authentication methods, you can specify the authentication values for each agent.

To trigger a webhook using curl with a required Bearer token authentication, you can use the following command:

curl https://agentuity.ai/webhook/agent_1234567890abcdef \
	-H 'Authorization: Bearer <token>' \
	--json '{"some":"data"}'

The response from the webhook will contain an informational message if successful. Additionally, the Location header will contain the URL that can be used to read the agent output. This URL will block until the agent has started streaming the output response.

Agent API Source

To configure your agent to receive data as an API endpoint, you need to add a new API source. When receiving data from an API endpoint, the agent will send the data to the agent's inputs synchronously and wait for the agent to respond.

For API sources, you can require authorization to access the API. This is useful if you want to protect your API from unauthorized access.

The following authentication methods are supported:

When using the Bearer, Basic or Header authentication methods, you can specify the authentication values for each agent.

When you plan on using the API source, it is recommended that you stream data to and from the agent.

To invoke an API using curl with a required Bearer token authentication, you can use the following command:

curl https://agentuity.ai/api/agent_1234567890abcdef \
	-H 'Authorization: Bearer <token>' \
	--json '{"some":"data"}'

Agent Email Source

For Email sources, you can configure your agent at a unique agent email address. When receiving an email, the agent will send the email content to the agent's inputs asynchronously without waiting for the agent to finish processing the email.

The response from the API will contain an informational message if successful. Additionally, the Location header will contain the URL that can be used to read the agent output. This URL will block until the agent has started streaming the output response.

Agent Discord Source

For Discord sources, you can configure your agent to receive messages from a Discord server. When a user tags the bot in a Discord message, the agent will receive the message content asynchronously without waiting for the agent to finish processing the message.

Prerequisite: Connecting Your Account

Before configuring a Discord source, you must first link your personal Discord account to Agentuity. This one-time setup allows Agentuity to see your available servers.

1. Click your user profile name in the bottom-left corner of the App.
2. Select Account from the menu that appears.
3. In your Profile settings, find the Connected accounts section and click the Connect account button to add Discord.
4. Follow the authorization flow in the pop-up window to grant the requested permissions.

Configuration Steps

To set up Discord Integration:

1. Add Discord IO: Click the plus button in the agent IO visualization and select Discord
2. Select Server: Choose a Discord server from your connected servers
3. Invite Bot: If the bot isn't already in the server, use the provided invite link to add the Agentuity bot to your Discord server
4. Tag Bot: Once configured, tag the bot (@Agentuity) in Discord messages to forward them to your agent

The Discord Integration provides the following data when a message is forwarded:

• Message Content: The text content of the Discord message
• Author Information: Username and user ID of the message author
• Server Context: Guild ID and channel ID
• Message ID: Unique identifier for the Discord message

When your agent receives a Discord message, you can access the Discord-specific data through the request object:

import type { AgentContext, AgentRequest, AgentResponse } from '@agentuity/sdk';

export default async function Agent(
 req: AgentRequest,
 resp: AgentResponse,
 ctx: AgentContext
) {
  // Check if this was triggered by Discord
  if (req.trigger === 'discord') {
      const messageData = await req.data.discord();
      
      ctx.logger.info('Discord message from %s: %s', 
          messageData.username, 
          messageData.content
      );
      
      // Access server and channel info
      ctx.logger.info('Guild: %s, Channel: %s, Message: %s', 
          messageData.guildId, 
          messageData.channelId,
          messageData.messageId
      );
      
      return resp.text(`Hello ${messageData.username}! I received your message.`);
  }
  
  return resp.text("Hello from Discord bot!");
}

from agentuity import AgentRequest, AgentResponse, AgentContext

async def run(request: AgentRequest, response: AgentResponse, context: AgentContext):
  # Check if this was triggered by Discord
  if request.trigger == 'discord':
      message_data = await request.data.discord()
      
      context.logger.info('Discord message from %s: %s', 
          message_data['username'], 
          message_data['content']
      )
      
      # Access server and channel info
      context.logger.info('Guild: %s, Channel: %s, Message: %s', 
          message_data['guildId'], 
          message_data['channelId'],
          message_data['messageId']
      )
      
      return response.text(f"Hello {message_data['username']}! I received your message.")
  
  return response.text("Hello from Discord bot!")

Agent SMS Source

For SMS sources, you can connect your Twilio account to allow your agent to be triggered by incoming text messages. This requires providing your Twilio API credentials.

To configure an SMS source, you will need the following credentials from your Twilio console:

• Account SID
• API SID
• API Secret

Once validated, you can select one or more of your Twilio numbers to forward incoming messages to your agent.

Agent Schedule Source

For running an agent on a schedule, you can configure your agent to use a cron source. When the agent is scheduled to run, the agent will send the data to the agent's inputs asynchronously without waiting for the agent to finish processing the data.

When creating a new schedule, you can specify the cron expression to run the agent. The cron expression is a string that represents the schedule to run the agent.

You can optionally specify a content type and payload to send to the agent when the agent is scheduled to run.

A cron source can only be triggered internally by the Agentuity Platform and not via the API. However, you can trigger a scheduled agent to run by selecting the schedule and selecting "Manual Run" in the context menu.

Agent Deployments

Agentuity supports continuous deployment using a native GitHub App integration and a GitHub Actions workflow.

GitHub App Integration

The GitHub App integration is a native integration that allows you to deploy your agents to the Agentuity Platform from your GitHub repository.

To enable the GitHub App integration, you need to provide permission for Agentuity to access your GitHub account. On your Project Settings page, you can find the GitHub App integration.

Once connected, each Project can be configured to deploy from a specific GitHub repository automatically.

When a new commit is pushed to the repository, the GitHub Actions workflow will be triggered and the agent will be deployed to the Agentuity Platform.

You can select a specific deployment to view the deployment details including logs.

When using GitHub to deploy (either the GitHub App or the GitHub Actions workflow), your GitHub commit information will be displayed in the deployment details.

You can see all the projects that are connected to your GitHub account in the Settings > Integrations section.

From here you can disconnect a specific project from your GitHub account or disconnect Agentuity from your GitHub account.

GitHub Actions Workflow

The GitHub Actions workflow is a native integration that allows you to deploy your agents to the Agentuity Platform from your GitHub repository using GitHub Actions.

You can install the GitHub Actions workflow by visiting the Agentuity GitHub Actions Marketplace and clicking the "Install" button.

You can also directly use the Agentuity GitHub Actions repository to deploy your agents to the Agentuity Platform.

Manual Deployment

You can also manually deploy your agents to the Agentuity Platform with the CLI using the following command:

agentuity deploy

By default, the CLI will use the latest tag to deploy your agents. You can specify one or more tags to deploy by using the --tag flag. The active deployment will only be used for agent requests based on the latest tag.

You can test new versions of your agents by using the --tag flag to specify a specific tag and then using the tag in either the webhook or api source.

For example, if you have a tag called v1.0.0, you can use the following command to deploy it:

agentuity deploy --tag v1.0.0

This will tag the deployment with the v1.0.0 tag but not make it the active deployment.

You can the invoke the agent with the v1.0.0 tag by using curl with the following command:

curl https://agentuity.ai/api/agent_1234567890abcdef/v1.0.0 \
	-H 'Authorization: Bearer <token>' \
	--json '{"some":"data"}'

Rollback & Delete

You can rollback to a previous deployment by using the CLI with the following command:

agentuity rollback

If you would like to delete the deployment in addition to rolling back, you can use the --delete flag.

You can select a specific deployment:

Agent Logs

You can view the logs for a specific agent by selecting the agent and then clicking the "Logs" tab.

If you select a specific log, you can view the log detail for the specific log entry.

Agent Sessions

The sessions dashboard provides a list of your agent sessions. This page helps you monitor your agent's status, usage metrics, and recent activity.

If you select a specific session, you can view the session detail for the specific session.

If you select a specific span, a session span trace detail will be displayed with specific detail about the execution of the span.

CLI

You can use the CLI to manage your agents using the following command:

agentuity agent

See the CLI documentation for more information on specific command usage and flags.