[docs sprint] Add Docs on Creating and Using External Actions #18
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
macwilk
changed the title
adnaans
reviewed
Jun 13, 2024
docs/open-source/external-action.mdx
Outdated
| External Actions allow Vocode agents to take actions outside the realm of a phone call. In particular, Vocode agents can decide to _push_ information to external systems via an API request, and _pull_ information from the API response in order to: | ||
|
|
||
| 1. change the agent’s behavior based on the pulled information | ||
| 2. give the agent context to inform the rest of the phone call |
There was a problem hiding this comment.
Add that the agent can do things outside a phone call
docs/open-source/external-action.mdx
Outdated
|
|
||
| #### Overview | ||
|
|
||
| - `processing_mode`: while it only supports `muted` right now, the intent is for this field to (in the future) enable hold music while processing the request, or to enable the agent to continue speaking until the request returns. |
docs/open-source/external-action.mdx
Outdated
| - `url`: The API request is sent to this URL in the format | ||
| defined below in [Responding to External Action API Requests](/open-source/external-action#input-schema-field) | ||
|
|
||
| - `input_schema`: A [JSON Schema](https://json-schema.org/) object that instructs how to properly form a payload to send to the External API. See the [`input_schema` field section below](/open-source/external-action#responding-to-external-action-api-requests) for more info! |
There was a problem hiding this comment.
change to "A JSON Schema for the payload to send to the external API.
docs/open-source/external-action.mdx
Outdated
Comment on lines
30
to
34
| - `speak_on_send`: if `True`, then the underlying LLM will generate a message to be spoken into the phone call as the | ||
| API request is being sent. | ||
|
|
||
| - `speak_on_receive`: if `True`, then the Vocode Agent will invoke the underlying | ||
| LLM to respond based on the result from the API Response or the Error encountered. |
There was a problem hiding this comment.
For both, say the LLM will generate a message to be spoken into the phone call
docs/open-source/external-action.mdx
Outdated
|
|
||
| #### `input_schema` Field | ||
|
|
||
| The `input_schema` field is a [JSON Schema](https://json-schema.org/) object that instructs how to properly form a payload to send to the External API. |
There was a problem hiding this comment.
"is a JSON Schema for the payload to send to the External API"
docs/open-source/external-action.mdx
Outdated
| """ | ||
| signature_secret_as_bytes = base64.b64decode(signature_secret) | ||
| decoded_digest = base64.b64decode(request_signature_value) | ||
| calculated_digest = hmac.new(signature_secret_as_bytes, payload, hashlib.sha256).digest() |
There was a problem hiding this comment.
double check but payload may need to be encoded
docs/open-source/external-action.mdx
Outdated
Comment on lines
152
to
155
| Response { | ||
| result: Any | ||
| agent_message: Optional[str] = None | ||
| } |
docs/open-source/external-action.mdx
Outdated
| ``` | ||
|
|
||
| - `result` is a payload containing the result of the action on the user’s side, and can be in any format | ||
| - `agent_message` optionally contains a message that will be synthesized into audio and sent back to the phone call (see [Configuring the External Action](/open-source/external-action#configuring-the-external-action) above for more info) |
There was a problem hiding this comment.
Does this mean the LLM isn't invoked at the end? need to clarify this
There was a problem hiding this comment.
Updated the docs accordingly then (earlier we say it always queries the LLM which is inaccurate then)
docs/open-source/external-action.mdx
Outdated
Comment on lines
188
to
192
| class Payload(BaseModel): | ||
| length: str | ||
| time: str | ||
|
|
||
| call_id: str |
docs/open-source/external-action.mdx
Outdated
Comment on lines
197
to
199
| print(f"Received request:\n{external_action_request.model_dump_json(indent=2)}") | ||
| time.sleep(3) | ||
| return {"result": {"success": True}} |
ajar98
requested changes
Jun 14, 2024
docs/open-source/external-action.mdx
Outdated
| "signature_secret": base64.b64encode(os.urandom(32)).decode(), | ||
| } | ||
|
|
||
| action = ExecuteExternalAction( |
There was a problem hiding this comment.
can we link the Action Agents doc here? this isn't how you would use the action
also - in this PR can we update the the Action Agents or the Agent Factories doc to actually show how to insert a user created action into a conversation? both of those docs are missing that
ajar98
previously approved these changes
Jun 14, 2024
ajar98
approved these changes
Jun 14, 2024
adnaans
pushed a commit
that referenced
this pull request
Jun 14, 2024
Also updated example for action agents
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds documentation on how to create and use External Actions using the OS Library.
Differs a good bit from the API version but I lifted a lot of the language from there and repurposed for Open Source.