API Publishing

You may interact with the agency via Socket.IO.

Authentication

All API requests are authenticated by passing accessKey as a query parameter in the initial request.

import { io } from 'socket.io-client'
const socket = io('https://api.agencyai.gg', {
  query: {
    agencyId: 0,
    accessKey: 'your_access_key'
  }
});

Sendable Events

These are the events which can be sent through Socket.IO from the client.

newChat

This event is used to initiate a new chat. A new chatId will be echoed back to the client in the NewChatOutput event. Only chat messages associated with this chatId will be sent to the client.

type NewChatInput = {
  agencyId: number,
  userPrompt: string,
  filterOnlyManager?: ?boolean
}

Use filterOnlyManager if the client should receive message updates from only the manager agent. Otherwise, message updates from all agents will be received.

newMessage

Appends a new user message to the chat with the manager.

type NewMessageInput = {
  agencyId: number,
  chatId: string,
  userPrompt: string,
}

loadChat

Use this event to load a pre-existing chatId. It can be used to switch chats or to implement reconnection with the last known message IDs.

type LoadChatInput = {
  agencyId: number,
  chatId: string,
  lastMessageIds?: { [agentId: number]: number },
}

Each agent has its own personal message log. If lastMessageIds is provided, it should be a mapping from agentId to the last messageId in that agent's message log.

Receivable Events

These are the events which the server may send to the client.

newChat

The server sends this in response to the client sending a newChat event. It is to confirm the creation of a new chat, and it also provides the client with the new chatId to be used in subsequent requests.

type NewChatOutput = {
  agencyId: number,
  chatId: string,
  managerAgentId: number,
}

updateName

After creating a new chat, the server will automatically generate a name for this chat. This event is sent to the client to inform it of the new name.

type UpdateNameOutput = {
  agencyId: number,
  chatId: string,
  managerAgentId: number,
  name: string,
}

loadChat

The server sends this in response to the client sending a loadChat event. When the server receives loadChat from the client, it will begin sending appendMessage and updateMessage events to the client, and finally, when loading is done, it will emit this loadChat event. The client can use this to know when the loading phase is done.

type LoadChatOutput = {
  agencyId: number,
  chatId: string,
  managerAgentId: number,
}

appendMessage

If the client receives this event, it should append the message to the chat log for the agent specified by message.agentId.

type AppendMessageOutput = {
  agencyId: number,
  chatId: string,
  managerAgentId: number,
  message: FlatMessage,
}

updateMessage

If the client receives this event, it should update the message specified by message.messageId.

type UpdateMessageOutput = {
  agencyId: number,
  chatId: string,
  managerAgentId: number,
  message: FlatMessage,
}

Message Type

Here are the typings for the Message.

const MessageRole = {
  SYSTEM: 'SYSTEM',
  ASSISTANT: 'ASSISTANT',
  USER: 'USER',
}

type MessageRoleType = $Keys<typeof MessageRole>

type FlatMessage = {|
  __typename: string,
  id: string,
  messageId: number,
  agentId: number,
  agentConversationId: string,
  role: MessageRoleType,
  linkedMessageId: ?number,
  internalInstruction?: ?boolean,
  userInstruction?: ?boolean,
  correctionInstruction?: ?boolean,
  toApi: ?boolean,
  fromApi: ?boolean,
  completed: ?boolean,
  toAgentId: ?number,
  fromAgentId: ?number,
  text: string,
  dateCreated: string,
|}

The Manager Agent

One difference between the OpenAI Chat Completions API and this API is that this API is used to interact with an entire agency which is made of multiple agents. Every agency will have a single agent designated as the manager. Messages from the API will be sent to this manager agent, and the manager agent's responses will be sent back through the API. Messages cannot be sent directly to the other agents in the agency.

Error Handling

If there is an error, the server will send an error event with the following JSON data:

{
  "message": "Error message"
}

API Versioning

The API for an agency is versioned by a unique ID.

Whenever you change an agency's instructions, a new version for it is automatically created. A new version is only created when there are conversations on the latest version.

If you need to access an old version of the agency, you can do so by setting agencyId in the POST data to the ID of the old version. The agencyId of a versioned agency does not change, so old endpoints will continue to work.

Working Example

Create an account to try out the API.