Beyond Presence Agents API
The Agents API from Beyond Presence — 2 operation(s) for agents.
OpenAPI Specification
openapi: 3.1.0
info:
title: Fast Agents API
version: 0.1.0
servers:
- url: https://api.bey.dev
tags:
- name: Agents
paths:
/v1/agents:
post:
tags:
- Agents
summary: Create Agent
description: Create agent.
operationId: create_agent_v1_agents_post
security:
- APIKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgentRequest'
responses:
'201':
description: Created Agent with ID
content:
application/json:
schema:
$ref: '#/components/schemas/AgentResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Agents
summary: List Agents
description: List agents.
operationId: list_agents_v1_agents_get
security:
- APIKeyHeader: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50
exclusiveMinimum: 0
description: Maximum number of objects to return.
default: 10
title: Limit
description: Maximum number of objects to return.
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Cursor for pagination.
title: Cursor
description: Cursor for pagination.
responses:
'200':
description: Paginated List of Agents
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/HasMorePage_AgentResponse_'
- $ref: '#/components/schemas/NoMorePage_AgentResponse_'
title: Response List Agents V1 Agents Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/{id}:
patch:
tags:
- Agents
summary: Update Agent
description: Update agent.
operationId: update_agent_v1_agents__id__patch
security:
- APIKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Agent ID.
title: Id
description: Agent ID.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAgentRequest'
responses:
'204':
description: Successful Update
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Agents
summary: Retrieve Agent
description: Retrieve agent.
operationId: get_agent_v1_agents__id__get
security:
- APIKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Agent ID.
title: Id
description: Agent ID.
responses:
'200':
description: Requested Agent
content:
application/json:
schema:
$ref: '#/components/schemas/AgentResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Agents
summary: Delete Agent
description: Delete agent.
operationId: delete_agent_v1_agents__id__delete
security:
- APIKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Agent ID.
title: Id
description: Agent ID.
responses:
'204':
description: Successful Deletion
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
AgentCapabilityList:
items:
$ref: '#/components/schemas/AgentCapability'
type: array
WebcamVisionAgentCapability:
properties:
type:
type: string
const: webcam_vision
title: Type
default: webcam_vision
type: object
title: WebcamVisionAgentCapability
description: Agent capability to see user camera feed.
AgentTts:
oneOf:
- $ref: '#/components/schemas/LivekitAgentTts'
- $ref: '#/components/schemas/ElevenlabsAgentTts'
- $ref: '#/components/schemas/DeepgramAgentTts'
- $ref: '#/components/schemas/OpenaiAgentTts'
- $ref: '#/components/schemas/GoogleAgentTts'
discriminator:
propertyName: type
mapping:
deepgram: '#/components/schemas/DeepgramAgentTts'
elevenlabs: '#/components/schemas/ElevenlabsAgentTts'
google_tts: '#/components/schemas/GoogleAgentTts'
livekit: '#/components/schemas/LivekitAgentTts'
openai_tts: '#/components/schemas/OpenaiAgentTts'
NoMorePage_AgentResponse_:
properties:
data:
items:
$ref: '#/components/schemas/AgentResponse'
type: array
title: Data
description: List of objects.
has_more:
type: boolean
const: false
title: Has More
description: Whether there are more objects to fetch.
default: false
type: object
required:
- data
title: NoMorePage[AgentResponse]
OpenaiCompatibleAgentLlm:
properties:
type:
type: string
const: openai_compatible
title: Type
default: openai_compatible
api_id:
type: string
title: Api Id
model:
type: string
title: Model
temperature:
type: number
title: Temperature
headers:
additionalProperties:
type: string
type: object
title: Headers
type: object
required:
- api_id
- model
- temperature
title: OpenaiCompatibleAgentLlm
description: 'Configuration for an LLM provided by an OpenAI-compatible API.
The notion of "OpenAI-compatible API" is somewhat fuzzy, there is no
agreed upon standard for what it means.
In practice, we care if the API is compatible with how LiveKit''s openai
plugin interacts with it, i.e. a subset of OpenAI''s API specification that
provides chat completions:
https://platform.openai.com/docs/api-reference/completions'
DeepgramAgentTts:
properties:
type:
type: string
const: deepgram
title: Type
default: deepgram
voice:
anyOf:
- type: string
- type: 'null'
title: Voice
type: object
title: DeepgramAgentTts
description: Configuration for Deepgram TTS.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Language:
type: string
enum:
- ar
- ar-SA
- bn
- bg
- zh
- cs
- da
- nl
- en
- en-AU
- en-GB
- en-US
- fi
- fr
- fr-CA
- fr-FR
- de
- el
- hi
- hu
- id
- it
- ja
- kk
- ko
- ms
- 'no'
- pl
- pt
- pt-BR
- pt-PT
- ro
- ru
- sk
- es
- sv
- tr
- uk
- ur
- vi
title: Language
description: Language for communication.
AgentResponse:
properties:
id:
type: string
title: Id
description: Unique identifier of the object in the database.
examples:
- 01234567-89ab-cdef-0123-456789abcdef
name:
type: string
maxLength: 100
minLength: 1
title: Name
description: Display name to use. Also used when addressed in conversations.
examples:
- Jarvis
- HAL 9000
avatar_id:
type: string
maxLength: 100
minLength: 1
title: Avatar Id
description: ID of avatar to use.
examples:
- 01234567-89ab-cdef-0123-456789abcdef
system_prompt:
type: string
maxLength: 10000
minLength: 1
title: System Prompt
description: System prompt to use.
examples:
- You are a helpful assistant.
language:
anyOf:
- $ref: '#/components/schemas/Language'
- type: 'null'
description: Language to use.
examples:
- en
- en-US
- de
greeting:
anyOf:
- type: string
maxLength: 1000
minLength: 1
- type: 'null'
title: Greeting
description: What to say when a call starts.
examples:
- Hello!
max_session_length_minutes:
anyOf:
- type: integer
maximum: 90.0
exclusiveMinimum: 0.0
- type: 'null'
title: Max Session Length Minutes
description: Maximum session length in minutes.
examples:
- 30
capabilities:
$ref: '#/components/schemas/AgentCapabilityList'
description: Extra capabilities to manage calls.
examples:
- - type: webcam_vision
- triggers:
- hey agent
- hi pal
type: wakeup_mode
llm:
anyOf:
- $ref: '#/components/schemas/AgentLlm'
- type: 'null'
description: Configuration for LLM to use.
examples:
- type: openai
- api_id: 01234567-89ab-cdef-0123-456789abcdef
model: gpt-4o-mini
temperature: 0.7
type: openai_compatible
tts:
anyOf:
- $ref: '#/components/schemas/AgentTts'
- type: 'null'
description: Configuration for TTS to use.
examples:
- type: elevenlabs
voice: 21m00Tcm4TlvDq8ikWAM
knowledge_file_ids:
items:
type: string
minLength: 1
type: array
uniqueItems: true
title: Knowledge File Ids
description: IDs of knowledge files to refer to.
type: object
required:
- id
- name
- avatar_id
- system_prompt
title: AgentResponse
description: Response model for an agent.
LivekitAgentTts:
properties:
type:
type: string
const: livekit
title: Type
default: livekit
model:
type: string
title: Model
voice:
type: string
title: Voice
type: object
required:
- model
- voice
title: LivekitAgentTts
description: Configuration for TTS supported via LiveKit Inference.
AgentLlm:
oneOf:
- $ref: '#/components/schemas/LivekitAgentLlm'
- $ref: '#/components/schemas/OpenaiAgentLlm'
- $ref: '#/components/schemas/OpenaiCompatibleAgentLlm'
discriminator:
propertyName: type
mapping:
livekit: '#/components/schemas/LivekitAgentLlm'
openai: '#/components/schemas/OpenaiAgentLlm'
openai_compatible: '#/components/schemas/OpenaiCompatibleAgentLlm'
UpdateAgentRequest:
properties:
name:
type: string
maxLength: 100
minLength: 1
title: Name
description: Display name to use. Also used when addressed in conversations.
examples:
- Jarvis
- HAL 9000
avatar_id:
type: string
maxLength: 100
minLength: 1
title: Avatar Id
description: ID of avatar to use.
examples:
- 01234567-89ab-cdef-0123-456789abcdef
system_prompt:
type: string
maxLength: 10000
minLength: 1
title: System Prompt
description: System prompt to use.
examples:
- You are a helpful assistant.
language:
anyOf:
- $ref: '#/components/schemas/Language'
- type: 'null'
description: Language to use.
examples:
- en
- en-US
- de
greeting:
anyOf:
- type: string
maxLength: 1000
minLength: 1
- type: 'null'
title: Greeting
description: What to say when a call starts.
examples:
- Hello!
max_session_length_minutes:
anyOf:
- type: integer
maximum: 90.0
exclusiveMinimum: 0.0
- type: 'null'
title: Max Session Length Minutes
description: Maximum session length in minutes.
examples:
- 30
capabilities:
$ref: '#/components/schemas/AgentCapabilityList'
description: Extra capabilities to manage calls.
examples:
- - type: webcam_vision
- triggers:
- hey agent
- hi pal
type: wakeup_mode
llm:
anyOf:
- $ref: '#/components/schemas/AgentLlm'
- type: 'null'
description: Configuration for LLM to use.
examples:
- type: openai
- api_id: 01234567-89ab-cdef-0123-456789abcdef
model: gpt-4o-mini
temperature: 0.7
type: openai_compatible
tts:
anyOf:
- $ref: '#/components/schemas/AgentTts'
- type: 'null'
description: Configuration for TTS to use.
examples:
- type: elevenlabs
voice: 21m00Tcm4TlvDq8ikWAM
knowledge_file_ids:
items:
type: string
minLength: 1
type: array
uniqueItems: true
title: Knowledge File Ids
description: IDs of knowledge files to refer to.
type: object
title: UpdateAgentRequest
description: Request body to update an agent. Omitted fields are unchanged.
AgentCapability:
oneOf:
- $ref: '#/components/schemas/WebcamVisionAgentCapability'
- $ref: '#/components/schemas/WakeupModeAgentCapability'
discriminator:
propertyName: type
mapping:
wakeup_mode: '#/components/schemas/WakeupModeAgentCapability'
webcam_vision: '#/components/schemas/WebcamVisionAgentCapability'
ElevenlabsAgentTts:
properties:
type:
type: string
const: elevenlabs
title: Type
default: elevenlabs
voice:
anyOf:
- type: string
- type: 'null'
title: Voice
type: object
title: ElevenlabsAgentTts
description: Configuration for Elevenlabs TTS.
WakeupModeAgentCapability:
properties:
type:
type: string
const: wakeup_mode
title: Type
default: wakeup_mode
triggers:
items:
type: string
type: array
title: Triggers
type: object
required:
- triggers
title: WakeupModeAgentCapability
description: Agent capability to wake up only on specific keywords.
OpenaiAgentLlm:
properties:
type:
type: string
const: openai
title: Type
default: openai
model:
type: string
enum:
- gpt-4.1-mini
- gpt-4.1
title: Model
default: gpt-4.1-mini
type: object
title: OpenaiAgentLlm
description: Configuration for OpenAI LLM.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
GoogleAgentTts:
properties:
type:
type: string
const: google_tts
title: Type
default: google_tts
voice:
anyOf:
- type: string
- type: 'null'
title: Voice
type: object
title: GoogleAgentTts
description: Configuration for Google TTS.
CreateAgentRequest:
properties:
name:
type: string
maxLength: 100
minLength: 1
title: Name
description: Display name to use. Also used when addressed in conversations.
examples:
- Jarvis
- HAL 9000
avatar_id:
type: string
maxLength: 100
minLength: 1
title: Avatar Id
description: ID of avatar to use.
examples:
- 01234567-89ab-cdef-0123-456789abcdef
system_prompt:
type: string
maxLength: 10000
minLength: 1
title: System Prompt
description: System prompt to use.
examples:
- You are a helpful assistant.
language:
anyOf:
- $ref: '#/components/schemas/Language'
- type: 'null'
description: Language to use.
examples:
- en
- en-US
- de
greeting:
anyOf:
- type: string
maxLength: 1000
minLength: 1
- type: 'null'
title: Greeting
description: What to say when a call starts.
examples:
- Hello!
max_session_length_minutes:
anyOf:
- type: integer
maximum: 90.0
exclusiveMinimum: 0.0
- type: 'null'
title: Max Session Length Minutes
description: Maximum session length in minutes.
examples:
- 30
capabilities:
$ref: '#/components/schemas/AgentCapabilityList'
description: Extra capabilities to manage calls.
examples:
- - type: webcam_vision
- triggers:
- hey agent
- hi pal
type: wakeup_mode
llm:
anyOf:
- $ref: '#/components/schemas/AgentLlm'
- type: 'null'
description: Configuration for LLM to use.
examples:
- type: openai
- api_id: 01234567-89ab-cdef-0123-456789abcdef
model: gpt-4o-mini
temperature: 0.7
type: openai_compatible
tts:
anyOf:
- $ref: '#/components/schemas/AgentTts'
- type: 'null'
description: Configuration for TTS to use.
examples:
- type: elevenlabs
voice: 21m00Tcm4TlvDq8ikWAM
knowledge_file_ids:
items:
type: string
minLength: 1
type: array
uniqueItems: true
title: Knowledge File Ids
description: IDs of knowledge files to refer to.
type: object
required:
- name
- avatar_id
- system_prompt
title: CreateAgentRequest
description: Request body to create an agent.
LivekitAgentLlm:
properties:
type:
type: string
const: livekit
title: Type
default: livekit
model:
type: string
title: Model
reasoning_effort:
anyOf:
- type: string
enum:
- low
- medium
- high
- xhigh
- type: 'null'
title: Reasoning Effort
type: object
required:
- model
title: LivekitAgentLlm
description: Configuration for LLMs supported via LiveKit Inference.
OpenaiAgentTts:
properties:
type:
type: string
const: openai_tts
title: Type
default: openai_tts
voice:
anyOf:
- type: string
- type: 'null'
title: Voice
type: object
title: OpenaiAgentTts
description: Configuration for OpenAI TTS.
HasMorePage_AgentResponse_:
properties:
data:
items:
$ref: '#/components/schemas/AgentResponse'
type: array
title: Data
description: List of objects.
has_more:
type: boolean
const: true
title: Has More
description: Whether there are more objects to fetch.
default: true
next_cursor:
type: string
title: Next Cursor
description: The cursor for the next page of objects.
type: object
required:
- data
- next_cursor
title: HasMorePage[AgentResponse]
securitySchemes:
APIKeyHeader:
type: apiKey
description: Your Beyond Presence API Key.
in: header
name: x-api-key