​
Self-hosted

You can subclass a RespondAgent to create a simple agent that can be passed into StreamingConversation has the following interface:

Here’s one that responds with the same message no matter what is said to it:

class BrokenRecordAgentConfig(AgentConfig, type="agent_broken_record"):
    message: str


class BrokenRecordAgent(RespondAgent[BrokenRecordAgentConfig]):

    # is_interrupt is True when the human has just interrupted the bot's last response
    def respond(
        self, human_input, is_interrupt: bool = False
    ) -> tuple[Optional[str], bool]:
        return self.agent_config.message

    def generate_response(
        self, human_input, is_interrupt: bool = False
    ) -> Generator[str, None, None]:
        """Returns a generator that yields the agent's response one sentence at a time."""
        yield self.agent_config.message

See our other agent implementations for more guidance!

​
Hosted (deprecated)

NOTE: The hosted RESTfulAgent is being deprecated.

Our library lets you easily host your agent so that the Vocode backend can use it to generate responses. Users will be responsible for implementing a RESTfulAgent.

​
RESTful Implementation (deprecated)

Here is an example implementation of a RESTfulAgent that just echoes back whatever input it receives. Note that the respond method is expecting a RESTfulAgentOutput return value. The conversation_id parameter lets you store state about a single conversation across multiple calls.

from vocode.streaming.user_implemented_agent.restful_agent import RESTfulAgent
from vocode.streaming.models.agent import RESTfulAgentOutput, RESTfulAgentText, RESTfulAgentEnd

class YourAgent(RESTfulAgent):

    # input: the transcript from the Conversation that the agent must respond to
    async def respond(self, input: str, conversation_id: str) -> RESTfulAgentOutput:
        if "bye" in input:
            return RESTfulAgentEnd()  ## ends the conversation
        else:
            return RESTfulAgentText(response=input)  ## responds with the input received

​
Run your agent

if __name__ == "__main__":
    agent = YourAgent()
    agent.run(port=3000)

This sets up a FastAPI with either a POST endpoint or a websocket route at /respond. We’ll use this in the next step.

​
Setting up your AgentConfig

Now that your agent is running, you’ll need to host it somewhere so that the Vocode backend can hit it. There are a variety of options to do this, here we’ll describe using ngrok since it’s the quickest. Replit is also a great option for this.

# make sure the agent from the last step is running
ngrok http 3000

...
agent_config=RESTfulUserImplementedAgentConfig(
    respond=RESTfulUserImplementedAgentConfig.EndpointConfig(
        url="<your ngrok url tunneling to localhost:3000>/respond",
    )
)
...