API Reference
Comprehensive reference for the Agentuity JavaScript SDK API
This section provides detailed documentation for the Agentuity JavaScript SDK API, including method signatures, parameters, return values, and example usage.
Table of Contents
Agent Lifecycle
The Agentuity SDK provides a structured way to define and handle agents. An agent consists of a handler function, with its configuration managed by the Agentuity CLI.
Agent Configuration
Agent configuration is managed by the Agentuity CLI and stored in the project configuration file. The AgentConfig
interface is used internally by the CLI and SDK:
Agent Handler
The AgentHandler
type defines the handler function for an agent:
Parameters
request
: AnAgentRequest
object containing the request dataresponse
: AnAgentResponse
object for creating responsescontext
: AnAgentContext
object providing access to various capabilities
Return Value
The handler function should return a Promise that resolves to an AgentResponseType
object.
Example
Storage APIs
The Agentuity SDK provides three storage APIs: Key-Value Storage, Vector Storage, and Object Storage.
Key-Value Storage
The Key-Value Storage API provides a simple way to store and retrieve data. It is accessed through the context.kv
object.
get(name: string, key: string): Promise<DataResult>
Retrieves a value from the key-value storage.
Parameters
name
: The name of the key-value storagekey
: The key to retrieve the value for
Return Value
Returns a Promise that resolves to a DataResult object. The DataResult has an exists
boolean property and a data
property containing the value if found.
Example
set(name: string, key: string, value: ArrayBuffer | string | Json, ttl?: number): Promise<void>
Stores a value in the key-value storage.
Parameters
name
: The name of the key-value storagekey
: The key to store the value undervalue
: The value to store (can be an ArrayBuffer, string, or JSON object)ttl
(optional): Time-to-live in seconds (minimum 60 seconds)
Return Value
Returns a Promise that resolves when the value has been stored.
Example
delete(name: string, key: string): Promise<void>
Deletes a value from the key-value storage.
Parameters
name
: The name of the key-value storagekey
: The key to delete
Return Value
Returns a Promise that resolves when the value has been deleted.
Example
Vector Storage
The Vector Storage API provides a way to store and search for data using vector embeddings. It is accessed through the context.vector
object.
upsert(name: string, ...documents: VectorUpsertParams[]): Promise<string[]>
Inserts or updates vectors in the vector storage.
Parameters
name
: The name of the vector storagedocuments
: One or more documents to upsert, each with either embeddings or text
Return Value
Returns a Promise that resolves to an array of string IDs for the upserted vectors.
Example
search(name: string, params: VectorSearchParams): Promise<VectorSearchResult[]>
Searches for vectors in the vector storage.
Parameters
name
: The name of the vector storageparams
: Search parameters including query, limit, similarity threshold, and metadata filters
Return Value
Returns a Promise that resolves to an array of search results, each containing an ID, metadata, and distance score.
Example
delete(name: string, key: string): Promise<number>
Deletes a vector from the vector storage.
Parameters
name
: The name of the vector storagekey
: The ID of the vector to delete
Return Value
Returns a Promise that resolves to the number of vectors that were deleted (0 or 1).
Example
Object Storage
The Object Storage API provides a way to store and retrieve objects (files, documents, media) with support for public URL generation. It is accessed through the context.objectstore
object.
get(bucket: string, key: string): Promise<DataResult>
Retrieves an object from the object storage.
Parameters
bucket
: The bucket to get the object fromkey
: The key of the object to get
Return Value
Returns a Promise that resolves to a DataResult object. The DataResult has an exists
boolean property and a data
property containing the object data if found.
Example
put(bucket: string, key: string, data: DataType, params?: ObjectStorePutParams): Promise<void>
Stores an object in the object storage.
Parameters
bucket
: The bucket to put the object intokey
: The key of the object to putdata
: The data to store (can be ArrayBuffer, string, or other DataType)params
(optional): Additional parameters for the object. The following properties map to canonical HTTP headers:contentType
(Content-Type),contentEncoding
(Content-Encoding),cacheControl
(Cache-Control),contentDisposition
(Content-Disposition), andcontentLanguage
(Content-Language). The optionalmetadata
property accepts a dictionary of arbitrary key-value pairs that will be stored as metadata with the object but not returned as part of HTTP results when the object is fetched. ThecontentType
parameter is optional - if not provided, the content type will be automatically detected based on the data type (e.g., objects will be set toapplication/json
). If the content type cannot be determined, it defaults toapplication/octet-stream
.
Return Value
Returns a Promise that resolves when the object has been stored.
Example
delete(bucket: string, key: string): Promise<boolean>
Deletes an object from the object storage.
Parameters
bucket
: The bucket to delete the object fromkey
: The key of the object to delete
Return Value
Returns a Promise that resolves to a boolean indicating whether the object was deleted (true) or didn't exist (false).
Example
createPublicURL(bucket: string, key: string, expiresDuration?: number): Promise<string>
Creates a time-limited public URL for accessing an object.
Parameters
bucket
: The bucket containing the objectkey
: The key of the objectexpiresDuration
(optional): Duration in milliseconds until the URL expires. Defaults to 1 hour (3600000ms) if not provided. Minimum value is 1 minute (60000ms) - values less than 1 minute will be set to 1 minute.
Return Value
Returns a Promise that resolves to a public URL string that can be used to access the object.
Example
Agent Communication
The Agentuity SDK allows agents to communicate with each other through the context.getAgent()
method and agent redirection.
getAgent(params: GetAgentRequestParams): Promise<RemoteAgent>
Retrieves a handle to a remote agent that can be invoked.
Parameters
params
: Parameters to identify the agent, either by ID or by name and project ID
Return Value
Returns a Promise that resolves to a RemoteAgent
object that can be used to invoke the agent.
Example
Agent Handoff
The response.handoff()
method allows an agent to handoff the request to another agent.
handoff(agent: GetAgentRequestParams, payload?: Json | ArrayBuffer | string, contentType?: string, metadata?: Record<string, Json>): AgentRedirectResponse
Redirects the current request to another agent.
Parameters
agent
: Parameters to identify the target agentpayload
(optional): The payload to send to the target agentcontentType
(optional): The content type of the payloadmetadata
(optional): Additional metadata to include with the request
Return Value
Returns an AgentRedirectResponse
object.
Examples
Response Types
The Agentuity SDK provides various methods for creating different types of responses through the response
object.
JSON Responses
json(data: Json, metadata?: Record<string, Json>): AgentResponseType
Creates a JSON response.
Parameters
data
: The JSON data to include in the responsemetadata
(optional): Additional metadata to include with the response
Return Value
Returns an AgentResponseType
object with the JSON data.
Example
Text Responses
text(data: string, metadata?: Record<string, Json>): AgentResponseType
Creates a text response.
Parameters
data
: The text to include in the responsemetadata
(optional): Additional metadata to include with the response
Return Value
Returns an AgentResponseType
object with the text data.
Example
Binary Responses
binary(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
Creates a binary response.
Parameters
data
: The binary data to include in the responsemetadata
(optional): Additional metadata to include with the response
Return Value
Returns an AgentResponseType
object with the binary data.
Example
Media Type Responses
The SDK provides specialized methods for various media types:
pdf(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
png(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
jpeg(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
gif(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
webp(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
mp3(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
mp4(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
m4a(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
m4p(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
webm(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
wav(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
ogg(data: ArrayBuffer, metadata?: Record<string, Json>): AgentResponseType
data(data: Json | ArrayBuffer | string, contentType: string, metadata?: Record<string, Json>): AgentResponseType
markdown(content: string, metadata?: Record<string, Json>): AgentResponseType
Each method works similarly to the binary()
method but sets the appropriate content type. The data
method allows setting specific data with an exact content type, while the markdown
method provides a convenient way to return markdown content.
Example
HTML Responses
html(data: string, metadata?: Record<string, Json>): AgentResponseType
Creates an HTML response.
Parameters
data
: The HTML content to include in the responsemetadata
(optional): Additional metadata to include with the response
Return Value
Returns an AgentResponseType
object with the HTML content.
Example
Empty Responses
empty(metadata?: Record<string, Json>): AgentResponseType
Creates an empty response.
Parameters
metadata
(optional): Additional metadata to include with the response
Return Value
Returns an AgentResponseType
object with no payload.
Example
Request Handling
The Agentuity SDK provides various methods for accessing request data through the request
object.
Accessing Request Data
get trigger(): string
Gets the trigger type of the request.
Return Value
Returns a string representing the trigger type (webhook, cron, manual, agent, etc.).
Example
get(key: string, defaultValue?: Json): Json
Gets a value from the request. The available properties depend on the trigger type.
Parameters
key
: The key to retrievedefaultValue
(optional): A default value to return if the key does not exist
Return Value
Returns the value for the specified key, or the default value if the key does not exist.
Trigger-specific Properties
Different trigger types provide different properties:
- Webhook: Includes a
headers
property containing the HTTP headers from the webhook request.
Example
metadata(key: string, defaultValue?: Json): Json
Note: This method is deprecated. Use get(key, defaultValue)
instead.
Gets metadata associated with the request.
Parameters
key
: The metadata key to retrievedefaultValue
(optional): A default value to return if the key does not exist
Return Value
Returns the metadata value for the specified key, or the default value if the key does not exist.
json(): Promise<Json>
Gets the payload of the request as a JSON object.
Return Value
Returns a Promise that resolves to the request payload as a JSON object.
Example
text(): Promise<string>
Gets the payload of the request as a string.
Return Value
Returns a Promise that resolves to the request payload as a string.
Example
binary(): Promise<ArrayBuffer>
Gets the payload of the request as an ArrayBuffer.
Return Value
Returns a Promise that resolves to the request payload as an ArrayBuffer.
Example
Media-Specific Methods
The SDK provides specialized methods for various media types, all of which now return Promises:
pdf(): Promise<ArrayBuffer>
png(): Promise<ArrayBuffer>
jpeg(): Promise<ArrayBuffer>
gif(): Promise<ArrayBuffer>
webp(): Promise<ArrayBuffer>
mp3(): Promise<ArrayBuffer>
mp4(): Promise<ArrayBuffer>
m4a(): Promise<ArrayBuffer>
m4p(): Promise<ArrayBuffer>
webm(): Promise<ArrayBuffer>
wav(): Promise<ArrayBuffer>
ogg(): Promise<ArrayBuffer>
email(): Promise<Email>
Each method returns a Promise that resolves to the request payload as an ArrayBuffer with the appropriate content type validation, except for email()
which returns an Email object.
Example
Email Processing
The Agentuity SDK provides an Email
class for parsing and processing inbound email data when the content type is message/rfc822
.
Email Class
The Email
class represents a parsed email message with methods to access various email properties.
date(): Date | null
Returns the date of the email.
Return Value
Returns a Date
object representing the email's date, or null
if no date is available.
Example
messageId(): string | null
Returns the message ID of the email.
Return Value
Returns a string containing the email's message ID, or null
if no message ID is available.
Example
headers(): Headers
Returns the headers of the email.
Return Value
Returns a Headers
object containing all email headers.
Example
to(): string | null
Returns the email address of the recipient(s).
Return Value
Returns a string containing the recipient email address. If there are multiple recipients, they are comma-separated. Returns null
if no recipient is available.
Example
fromEmail(): string | null
Returns the email address of the sender.
Return Value
Returns a string containing the sender's email address, or null
if no sender email is available.
Example
fromName(): string | null
Returns the name of the sender.
Return Value
Returns a string containing the sender's name, or null
if no sender name is available.
Example
subject(): string | null
Returns the subject of the email.
Return Value
Returns a string containing the email subject, or null
if no subject is available.
Example
text(): string | null
Returns the plain text body of the email.
Return Value
Returns a string containing the plain text body, or null
if no plain text body is available.
Example
html(): string | null
Returns the HTML body of the email.
Return Value
Returns a string containing the HTML body, or null
if no HTML body is available.
Example
attachments(): IncomingEmailAttachment[]
Returns the attachments of the email.
Return Value
Returns an array of IncomingEmailAttachment
objects. Returns an empty array if there are no attachments.
Example
sendReply(request, context, reply): Promise<void>
Send a reply to the incoming email using the Agentuity email API.
Parameters
request
(AgentRequest): The triggering agent request containing email-auth-token in metadatacontext
(AgentContext): The agent context providing access to email servicesreply
(EmailReply): The reply configuration object
Return Value
Returns a Promise<void>
that resolves when the reply is sent successfully.
Example
Email Interfaces
EmailReply Interface
The EmailReply
interface defines the structure for email reply configuration.
Properties
subject?
(string): The subject of the reply. If not provided, defaults to 'RE: <original subject>'text
(string): The plain text body of the replyhtml?
(string): The optional HTML body of the replyattachments?
(OutgoingEmailAttachment[]): Optional attachments to include
IncomingEmailAttachment Interface
The IncomingEmailAttachment
interface represents an attachment from an incoming email.
Properties
filename
(string): The filename of the attachmentcontentDisposition
('attachment' | 'inline'): The content disposition of the attachment
Methods
data(): Promise<Data>
Asynchronously retrieves the attachment data as a Data object. For large attachments, this uses streaming to efficiently handle the data transfer.
Example
OutgoingEmailAttachment Interface
The OutgoingEmailAttachment
interface represents an attachment to be included in an outgoing email reply.
Properties
filename
(string): The filename of the attachmentdata
(DataType): The data of the attachmentcontentDisposition?
('attachment' | 'inline'): The content disposition. Defaults to 'attachment' if not provided
Logging
The Agentuity SDK provides logging functionality through the context.logger
object.
Logger Interface
The Logger
interface defines the following methods:
Logging Methods
debug(message: string, ...args: unknown[]): void
Logs a debug message.
Parameters
message
: The message to logargs
: Additional arguments to include in the log
Example
info(message: string, ...args: unknown[]): void
Logs an informational message.
Parameters
message
: The message to logargs
: Additional arguments to include in the log
Example
warn(message: string, ...args: unknown[]): void
Logs a warning message.
Parameters
message
: The message to logargs
: Additional arguments to include in the log
Example
error(message: string, ...args: unknown[]): void
Logs an error message.
Parameters
message
: The message to logargs
: Additional arguments to include in the log
Example
Creating Child Loggers
child(opts: Record<string, unknown>): Logger
Creates a child logger with additional context.
Parameters
opts
: Additional context to include in all logs from the child logger
Return Value
Returns a new Logger
instance with the additional context.
Example
Welcome Function
The Agentuity SDK allows you to customize the initial appearance of DevMode when it starts interacting with your agents by exporting a welcome()
function. This function returns an AgentWelcomeResult
object that includes a welcome message and optional example prompts.
AgentWelcomeResult Interface
welcome()
Defines a welcome message and optional example prompts for DevMode.
Return Value
Returns an AgentWelcomeResult
object with a welcome message and optional prompts.
Example
Session
The Agentuity SDK provides a Session
interface that represents the current agent execution context.
Telemetry
The Agentuity SDK integrates with OpenTelemetry for tracing and metrics.
Tracing
The SDK provides access to OpenTelemetry tracing through the context.tracer
object.
Example
Breaking Changes
Data API
In version X.X.X, the Data API was refactored to use async methods instead of static properties to better support streaming capabilities:
Before:
After:
This change affects all methods on the Data
interface:
data.base64
→data.base64()
data.text
→data.text()
data.json
→data.json()
data.object<T>()
→data.object<T>()
data.binary
→data.binary()
data.buffer
→data.buffer()
data.stream
→data.stream()
Deprecated Features
/run/:id
Route
The /run/:id
route is now deprecated as it provides the same functionality as /:id
. Applications should update their code to use the /:id
route instead.
Need Help?
Join our Community for assistance or just to hang with other humans building agents.
Send us an email at hi@agentuity.com if you'd like to get in touch.
Please Follow us on
If you haven't already, please Signup for your free account now and start building your first agent!