Merge branch 'vocodedev-main'

Author: arpagon

.pre-commit-config.yaml

@@ -1,13 +1,13 @@
 repos:
--   repo: https://github.com/psf/black
-    rev: 23.1.0
-    hooks:
-    -   id: black
--   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
-    hooks:
-    -   id: mypy
-        args: [--ignore-missing-imports, ./]
-        language: system
-        pass_filenames: false
-        stages: [pre-push]
+    - repo: https://github.com/psf/black
+      rev: 24.4.2
+      hooks:
+          - id: black
+    - repo: https://github.com/pre-commit/mirrors-mypy
+      rev: v1.8.0
+      hooks:
+          - id: mypy
+            args: [--ignore-missing-imports, ./]
+            language: system
+            pass_filenames: false
+            stages: [pre-push]

apps/telephony_app/main.py

@@ -73,7 +73,6 @@
                 account_sid=os.environ["TWILIO_ACCOUNT_SID"],
                 auth_token=os.environ["TWILIO_AUTH_TOKEN"],
             ),
-            logger=logger,
         )
     ],
     agent_factory=SpellerAgentFactory(),

contributing.md

@@ -40,7 +40,7 @@ If you submit a PR, we'd love to feature your contribution on Twitter so please
 
 ## Linting and Typechecking
 
-We use [`black`](https://black.readthedocs.io/en/stable/) for linting. If you're using VSCode, code should auto-format automatically. Otherwise, run the following script before pushing:
+We use [`black`](https://black.readthedocs.io/en/stable/) for linting. If you're using [VSCode](https://code.visualstudio.com/docs/editor/codebasics#_formatting), code should auto-format automatically. Otherwise, run the following script before pushing:
 
 ```
 make lint_diff

docs/action-triggers.mdx

@@ -0,0 +1,83 @@
+---
+title: "Action Triggers"
+description: "Configure Vocode actions to run based on different triggers"
+---
+
+# Phrase Triggers
+
+Phrase triggers allow users to more explicitly control the behavior of their agents by configuring actions to run only once a bot has spoken a particular phrase. For example, you can configure an agent to transfer a call to a human agent only after the bot has said "I will transfer now".
+
+## Creating a phrase trigger
+
+You can create a phrase trigger as follows:
+
+```python
+from vocode import (
+    PhraseBasedActionTrigger,
+    PhraseBasedActionTriggerConfig,
+    PhraseTrigger,
+)
+
+phrase_trigger = PhraseBasedActionTrigger(
+    config=PhraseBasedActionTriggerConfig(
+        phrase_triggers=[
+            PhraseTrigger(
+                phrase="I will transfer now",
+                conditions=["phrase_condition_type_contains"],
+            ),
+            PhraseTrigger(
+                phrase="You can speak to a human now",
+                conditions=["phrase_condition_type_contains"],
+            )
+        ]
+    )
+)
+```
+
+In this example, the action that this phrase trigger is attached to will fire only after the bot has spoken a turn that contains "I will transfer now" or "You can speak to a human now".
+
+`"phrase_condition_type_contains"` is the only condition type supported at this time, and does not match case, so in the above example, if the bot said "Okay, you can speak to a human now", the phrase trigger would still fire.
+
+## Configuring your action
+
+```python
+from vocode import (
+    TransferCallActionParams,
+    TransferCallConfig,
+)
+
+vocode_client.agents.update_agent(
+    actions=[
+        TransferCallActionParams(
+            type="action_transfer_call",
+            config=TransferCallConfig(
+                transfer_phone_number="<YOUR TRANSFER PHONE NUMBER>",
+            ),
+            action_trigger=phrase_trigger # from the previous code block
+        )
+    ]
+)
+```
+
+# [Default] Function Call Triggers
+
+To switch back to the default behavior, use a `FunctionCallActionTrigger`. These are open ended, meaning the
+Agent will decide when to use the action based on its prompting. Note that is is primarily achieved via the [Prompt](/prompts)
+but for [External Actions](/external-actions), it is also dependent on the description field.
+
+```python
+from vocode import FunctionCallActionTrigger
+
+function_trigger = FunctionCallActionTrigger(config={})
+vocode_client.agents.update_agent(
+    actions=[
+        TransferCallActionParams(
+            type="action_transfer_call",
+            config=TransferCallConfig(
+                transfer_phone_number="<YOUR TRANSFER PHONE NUMBER>",
+            ),
+            action_trigger=function_trigger
+        )
+    ]
+)
+```

docs/actions.mdx

@@ -0,0 +1,221 @@
+---
+title: "Actions"
+description: "Give your agents the ability to execute actions"
+---
+
+Vocode agents can decide to take actions synchronously during calls. There are two ways to configure actions:
+
+1. Phrase Triggers
+2. Function Call Triggers (default)
+
+See [Action Triggers](/action-triggers) for information on how to configure triggers. Below is the list of actions that an agent can perform:
+
+#### EndConversation
+
+`EndConversation` allows the agent to end the call, e.g. if the user says "Goodbye!"
+
+  <CodeGroup>
+
+```python Python
+vocode_client.actions.create_action(
+  request={
+      "type": "action_end_conversation",
+  }
+)
+```
+
+```typescript TypeScript
+const number = await vocode.actions.createAction({
+  type: "action_end_conversation",
+});
+```
+
+```bash cURL
+curl --request POST \
+  --url https://api.vocode.dev/v1/actions/create \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <API_KEY>'
+  --data '{
+  "type": "action_end_conversation"
+}'
+```
+
+</CodeGroup>
+
+#### DTMF
+
+`DTMF` allows the agent to hit dial tones during a call, e.g. navigating a phone tree
+
+  <CodeGroup>
+
+```python Python
+vocode_client.actions.create_action(
+  request={
+      "type":"action_dtmf",
+  }
+)
+```
+
+```typescript TypeScript
+const number = await vocode.actions.createAction({
+  type: "action_dtmf",
+});
+```
+
+```bash cURL
+curl --request POST \
+  --url https://api.vocode.dev/v1/actions/create \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <API_KEY>'
+  --data '{
+  "type": "action_dtmf"
+}'
+```
+
+</CodeGroup>
+
+#### TransferCall
+
+`TransferCall` allows the agent to transfer the call to another phone number
+
+  <CodeGroup>
+
+```python Python
+vocode_client.actions.create_action(
+  request={
+      "type":"action_transfer_call",
+      "config":{
+          "phone_number":"11234567890"
+      }
+  }
+)
+```
+
+```typescript TypeScript
+const number = await vocode.actions.createAction({
+  type: "action_transfer_call",
+  config: {
+    phoneNumber: "11234567890",
+  },
+});
+```
+
+```bash cURL
+curl --request POST \
+  --url https://api.vocode.dev/v1/actions/create \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <API_KEY>'
+  --data '{
+  "type": "action_transfer_call",
+  "config": {
+    "phone_number": "11234567890"
+  }
+}'
+```
+
+</CodeGroup>
+
+You can attach these as IDs to your phone number agent as follows:
+
+  <CodeGroup>
+
+```python Python
+from vocode import AgentUpdateParams
+
+vocode_client.numbers.update_number(
+  phone_number="11234567890",
+  inbound_agent=AgentUpdateParams(
+      actions=["<ACTION UUID>"]
+  )
+)
+```
+
+```typescript TypeScript
+vocode.numbers.updateNumber({
+  phoneNumber: "11234567890",
+  inboundAgent: {
+    actions: ["<ACTION UUID>"],
+  },
+});
+```
+
+```bash cURL
+curl --request POST \
+  --url https://api.vocode.dev/v1/numbers/update?phone_number=11234567890 \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <API_KEY>'
+  --data '{
+  "inbound_agent": {
+    "actions": ["<ACTION UUID>"]
+  }
+}'
+```
+
+</CodeGroup>
+
+You can also add these as actions as raw payloads as follows:
+
+  <CodeGroup>
+
+```python Python
+from vocode import AgentUpdateParams, TransferCallActionUpdateParams
+
+vocode_client.numbers.update_number(
+  phone_number="11234567890",
+  inbound_agent=AgentUpdateParams(
+      actions=[TransferCallActionUpdateParams(
+          type="action_transfer_call",
+          config={
+              "phone_number":"11234567890"
+          }
+      )]
+  )
+)
+```
+
+```typescript TypeScript
+vocode.numbers.updateNumber({
+  phoneNumber: "11234567890",
+  inboundAgent: {
+    actions: [
+      {
+        type: "action_transfer_call",
+        config: {
+          phoneNumber: "11234567890",
+        },
+      },
+    ],
+  },
+});
+```
+
+```bash cURL
+curl --request POST \
+  --url https://api.vocode.dev/v1/numbers/update?phone_number=11234567890 \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <API_KEY>'
+  --data '{
+  "inbound_agent": {
+    "actions": [{
+      "type": "action_transfer_call",
+      "config": {
+          "phone_number": "11234567890"
+      }
+    }]
+  }
+}'
+```
+
+</CodeGroup>
+
+#### [Beta] ExternalAction
+
+`ExternalAction` allows your agent communicate with an External API and include the response as context in the conversation.
+
+See [External Actions](/external-actions).
+
+#### [Beta] Warm Transfer
+
+Allows your agent to conference in another party into the call.
+
+See [Warm Transfer](/warm-transfer).

docs/agents.mdx

@@ -1,10 +1,34 @@
 ---
 title: "Agents"
-description: "🚧 Under construction"
+description: "Powerful AI assistants that you can control"
 ---
 
 # What are agents
 
+Vocode Agents are the core component of the Vocode API. Agents can be deployed to receive
+phone calls by attaching them to [Numbers](/numbers). Agents can also be used to make outbound calls
+via the `calls/create` endpoint.
+
+At its core, the agent is an amalgamation of everything you need to build powerful AI assistants for
+your use cases:
+
+- [Prompts](/prompts) – instructions given to the agent that control its behavior.
+- [Voices](/voices) – the synthetic voice given to your agent.
+- [Webhooks](/webhooks) – mechanism by which you can subscribe to agent events.
+- [Conversational Dials](/conversational-dials) – controls for how the agent communicates, like its interruption sensitivity.
+- [Actions](/actions) – tools available to your agent, like endint the conversation or transferring the call.
+
 # How to configure an agent
 
-# API Schema
+Agents can be configured via our [Dashboard](/dashboard) or via API. As with all of our API objects, Agents have
+`list`, `get`, `create`, and `update` endpoints that allow you to manipulate them as you see fit.
+
+In addition to the other API objects enumerated above, agents have other reference fields that can be used to control
+agent behavior:
+
+- `language` sets the agent language (for more context see [Multilingual Agents](/multilingual))
+- `initial_message` controls the agents first utterance.
+- `initial_message_delay` adds a delay to the initial message from when the call begins
+- `ask_if_human_present_on_idle` allows the agent to speak when there is more than 4s of silence on the call
+- `llm_temperature` controls the behavior of the underlying language model. Values can range from 0 to 1, with higher
+  values leading to more diverse and creative results. Lower values generate more consistent outputs.