Upsert an Agent

The Flyflow API allows you to create a new agent or update an existing agent by making a POST request to the /agent endpoint. This endpoint creates a new agent if one with the specified name doesn't exist, or updates an existing agent if one with the same name already exists.

Request

Endpoint

POST /agent

Headers

Authorization: The API key prefixed with Bearer. Example: Bearer your_api_key.
Content-Type: The content type of the request body. Must be set to application/json.

Request Body

The request body should be a JSON object containing the following properties:

name (string, required): The name of the agent. This property is used to identify the agent for upsert.
system_prompt (string, optional): The system prompt for the agent.
initial_message (string, optional): The initial message for the agent.
llm_model (string, optional): The language model to be used by the agent. Allowed values are "gpt-4o" and "flyflow-voice".
voice_id (string, optional): The identifier of the voice to be used by the agent.
webhook (string, optional): The webhook URL for the agent.
tools (array, optional): An array of tools available to the agent.
filler_words (boolean, optional): Indicates whether filler words are enabled for the agent.
filler_words_whitelist (array, optional): An array of whitelisted filler words for the agent.
actions (array, optional): An array of actions available to the agent.
voicemail_number (string, optional): The phone number to call before making the agent the AI voicemail option.
endpointing (integer, optional): The duration (in milliseconds) the agent should wait before finalizing the user's speech.
voice_optimization (integer, optional): The level of voice optimization to apply (0-4), with 4 being the fastest but lowest quality.
smart_endpointing_threshold (integer, optional): The threshold for smart endpointing.
language (string, optional): The language code for the agent (e.g., "en" for English, "es" for Spanish).
compliance_checks (array, optional): An array of compliance checks to be performed on the agent's responses.

Include all the properties you want to set or update in the request body. Omitted properties will retain their existing values or be set to their default values when creating a new agent.

cURL Example

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Name",
    "system_prompt": "You are a helpful assistant.",
    "initial_message": "Hello, how can I assist you today?",
    "llm_model": "gpt-4o",
    "voice_id": "female-young-american-warm",
    "webhook": "https://example.com/webhook",
    "filler_words": true,
    "filler_words_whitelist": ["um", "uh"],
    "actions": [
      {
        "name": "transfer",
        "instructions": "Transfer the call to a human operator",
        "forwarding_number": "+14155551234"
      }
    ],
    "voicemail_number": "+14155551234",
    "endpointing": 200,
    "voice_optimization": 2,
    "smart_endpointing_threshold": 80,
    "language": "en",
    "compliance_checks": [
      {
        "name": "Profanity Filter",
        "model": "gpt-3.5-turbo",
        "check_instructions": "Check for profanity and inappropriate language",
        "rewrite_threshold": 90
      }
    ]
  }' \
  "https://api.flyflow.dev/v1/agent"

Python Client Example

from flyflowclient import Flyflow

client = Flyflow(api_key='your_api_key')

agent = client.upsert_agent(
    name='Agent Name',
    system_prompt='You are a helpful assistant.',
    initial_message='Hello, how can I assist you today?',
    llm_model='gpt-4o',
    voice_id='female-young-american-warm',
    webhook='https://example.com/webhook',
    filler_words=True,
    filler_words_whitelist=["um", "uh"],
    actions=[
        {
            "name": "transfer",
            "instructions": "Transfer the call to a human operator",
            "forwarding_number": "+14155551234"
        }
    ],
    voicemail_number='+14155551234',
    endpointing=200,
    voice_optimization=2,
    smart_endpointing_threshold=80,
    language="en",
    compliance_checks=[
        {
            "name": "Profanity Filter",
            "model": "gpt-3.5-turbo",
            "check_instructions": "Check for profanity and inappropriate language",
            "rewrite_threshold": 90
        }
    ],
    area_code='415'
)

print(agent)

Response

Status Codes

200 OK: The agent was successfully created or updated.
400 Bad Request: The request body contains invalid data.
401 Unauthorized: The API key is missing or invalid.
500 Internal Server Error: An unexpected error occurred on the server side.

Response Body

If the agent is successfully created or updated, the response body will be a JSON object containing the details of the agent:

{
  "id": "agent_id",
  "name": "Agent Name",
  "phone_number": "+14155551234",
  "system_prompt": "You are a helpful assistant.",
  "initial_message": "Hello, how can I assist you today?",
  "llm_model": "gpt-4o",
  "voice_id": "female-young-american-warm",
  "webhook": "https://example.com/webhook",
  "tools": [],
  "filler_words": true,
  "filler_words_whitelist": ["um", "uh"],
  "actions": [
    {
      "name": "transfer",
      "instructions": "Transfer the call to a human operator",
      "forwarding_number": "+14155551234"
    }
  ],
  "voicemail_number": "+14155551234",
  "chunking": true,
  "endpointing": 200,
  "voice_optimization": 2,
  "smart_endpointing_threshold": 80,
  "language": "en",
  "compliance_checks": [
    {
      "name": "Profanity Filter",
      "model": "gpt-3.5-turbo",
      "check_instructions": "Check for profanity and inappropriate language",
      "rewrite_threshold": 90
    }
  ],
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

The response includes all the fields that were set in the request, along with additional information such as the agent's ID, phone number, and timestamps.

Error Handling

If an error occurs during the agent upsert process, the API will return an appropriate error response with a corresponding status code and error message in the response body.

For example, if the request body contains invalid data:

{
  "error": "Bad Request",
  "message": "Invalid request payload"
}

Make sure to handle errors appropriately in your application and provide the necessary authentication, valid data, and required fields (such as name and area_code when creating a new agent) in the request body.

Conclusion

Creating a new agent or updating an existing agent using the Flyflow API is a straightforward process. By making a POST request to the /agent endpoint with the agent details in the request body, you can upsert an agent associated with your account. The API will create a new agent if one with the specified name doesn't exist, or update an existing agent if one with the same name already exists. The API will return the details of the upserted agent upon success. Remember to handle errors and provide the necessary authentication, valid data, and required fields to ensure a smooth integration with the Flyflow platform.