Agents async API

This cookbook provides a step-by-step guide to use the asynchronous API for DevRev agents. It assumes you’ve already created an agent using the DevRev agent builder platform.

The DevRev async API enables you to execute agents without any execution timeout concerns. The execution occurs as an asynchronous workflow that sends events to you via webhooks. This approach ensures:

  • Agent complexity does not bring timeout concerns with it.
  • Complete execution tracking via progress events.
  • Ability to handle long-running agent tasks.

In any unlikely and unforeseen circumstances, if an individual operation of the workflow times out, you do not receive an error event right now to notify that you should not wait for any more messages. It is better to have a client side timeout for now while the issue is brainstormed and fixed for you.

Set up webhook

Before using the async API, you need to create a webhook to receive agent execution events:

$curl --location 'https://api.devrev.ai/internal/webhooks.create' \
>--header 'Content-Type: application/json' \
>--header 'Authorization: <YOUR_API_TOKEN>' \
>--data '{
>    "url": "https://your-application.com/webhook-endpoint",
>    "event_types": ["ai_agent_response"],
>    "headers": [
>      {
>        "name": "x-api-key",
>        "value": "your-secret-key"
>      }
>    ]
>}'

Save the webhook ID from the response (format: don:integration:dvrv-us-1:devo/0:webhook/auCJ7By8). You need this when making async API calls.

Make sure that your webhook endpoint can appropriately respond to the verify events sent by DevRev to verify your webhook. This verify event has a challenge string which you need to return in response. You return the response like this:

1200 OK
2{
3  "challenge": "DlrVaK7zRyZWwbJhj5dZHDlrVaK7Jhj5dZZjH"
4}

You should follow the documentation provided for webhooks here

Make async API calls

Key parameters:

  • agent: Your agent’s ID.
  • event.input_message.message: The query for your agent.
  • session_object: A unique identifier for the conversation session (maintains agent memory).
  • webhook_target.webhook: The webhook ID created earlier.

To execute an agent asynchronously:

$curl --location 'https://api.devrev.ai/internal/ai-agents.events.execute-async' \
>--header 'Content-Type: application/json' \
>--header 'Accept: application/json' \
>--header 'Authorization: <YOUR_API_KEY>' \
>--data '{
>  "agent": "don:core:dvrv-us-1:devo/0:ai_agent/1",
>  "event": {
>    "input_message": {
>      "message": "Your query to the agent"
>    }
>  },
>  "session_object": "unique_conversation_identifier",
>  "webhook_target": {
>    "webhook": "don:integration:dvrv-us-1:devo/0:webhook/auCJ7By8"
>  },
>  "client_metadata": {
>      "user_id": "12345",
>      "conversation_id": "conv-789"
>  }
>}'

The session_object parameter is critical for maintaining conversation state across multiple calls.

Handle webhook events

Your webhook endpoint receives three types of events.

Progress messages

These show which skills are being triggered and executed.

Skill triggered
1{
2  "payload": {
3    "ai_agent_response": {
4      "agent": "don:core:dvrv-us-1:devo/xyz:ai_agent/123",
5      "agent_response": "progress",
6      "client_metadata": { /* your original metadata */ },
7      "progress": {
8        "progress_state": "skill_triggered",
9        "skill_triggered": {
10          "args": { /* skill arguments */ },
11          "skill_name": "SkillName",
12          "workflow": { /* This is not populated if KnowledgeSearch skill is called */
13            "display_id": "workflow-84",
14            "id": "don:integration:dvrv-us-1:devo/xyz:workflow/84"
15          }
16        }
17      },
18      "session": "don:core:dvrv-us-1:devo/xyz:ai_agent_session/3810",
19      "session_object": "unique_conversation_identifier"
20    },
21    "type": "ai_agent_response"
22  }
23}
Skill executed
1{
2  "payload": {
3    "ai_agent_response": {
4      "agent": "don:core:dvrv-us-1:devo/xyz:ai_agent/123",
5      "agent_response": "progress",
6      "client_metadata": { /* your original metadata */ },
7      "progress": {
8        "progress_state": "skill_executed",
9        "skill_executed": {
10          "output": { /* skill output */ },
11          "skill_name": "SkillName"
12        }
13      },
14      "session": "don:core:dvrv-us-1:devo/xyz:ai_agent_session/3810",
15      "session_object": "unique_conversation_identifier"
16    },
17    "type": "ai_agent_response"
18  }
19}

Final message

This event contains the agent’s final response after all skills are executed.

1{
2  "payload": {
3    "ai_agent_response": {
4      "agent": "don:core:dvrv-us-1:devo/xyz:ai_agent/123",
5      "agent_response": "message",
6      "client_metadata": {
7        /* your original metadata */
8      },
9      "message": "The agent's final response message",
10      "session": "don:core:dvrv-us-1:devo/xyz:ai_agent_session/3810",
11      "session_object": "unique_conversation_identifier"
12    },
13    "type": "ai_agent_response"
14  }
15}

Error message

This event indicates an error occurred during execution.

1{
2  "payload": {
3    "ai_agent_response": {
4      "agent": "don:core:dvrv-us-1:devo/xyz:ai_agent/123",
5      "agent_response": "error",
6      "client_metadata": {
7        /* your original metadata */
8      },
9      "error": {
10        "error": "Error description"
11      },
12      "session": "don:core:dvrv-us-1:devo/xyz:ai_agent_session/3810",
13      "session_object": "unique_conversation_identifier"
14    },
15    "type": "ai_agent_response"
16  }
17}

Implementation patterns

Custom applications

This pattern is ideal for custom chat interfaces, backend systems, or any application that needs to interact with DevRev agents.

For building custom applications with the async API:

  1. Create a webhook endpoint in your application that can receive POST requests.
  2. Register this endpoint with DevRev using the webhooks.create API.
  3. Make async API calls with your agent ID and webhook ID.
  4. Process incoming webhook events to:
    • Track progress (optional).
    • Display the final agent response to the user.
    • Handle any errors.

Example flow for a chat application:

1// 1. When user sends a message
2function handleUserMessage(message) {
3  // Show loading indicator
4  displayLoadingIndicator();
5
6  // Make async API call
7  fetch("https://api.devrev.ai/internal/ai-agents.events.execute-async", {
8    method: "POST",
9    headers: {
10      "Content-Type": "application/json",
11      Authorization: "YOUR_API_KEY",
12    },
13    body: JSON.stringify({
14      agent: "your_agent_id",
15      event: {
16        input_message: {
17          message: message,
18        },
19      },
20      session_object: "conversation_" + userId,
21      webhook_target: {
22        webhook: "your_webhook_id",
23      },
24      client_metadata: {
25        conversation_id: conversationId,
26      },
27    }),
28  });
29}
30
31// 2. Webhook handler (server-side)
32app.post("/webhook-endpoint", (req, res) => {
33  const event = req.body;
34
35  // Add handling for verify events
36
37  const conversationId =
38    event.payload.ai_agent_response.client_metadata.conversation_id;
39
40  if (event.payload.ai_agent_response.agent_response === "message") {
41    // Final message
42    const message = event.payload.ai_agent_response.message;
43    sendToClient(conversationId, {
44      type: "agent_response",
45      message: message,
46    });
47  } else if (event.payload.ai_agent_response.agent_response === "error") {
48    // Error occurred
49    sendToClient(conversationId, {
50      type: "agent_error",
51      error: event.payload.ai_agent_response.error.error,
52    });
53  }
54
55  res.status(200).send("OK");
56});

Using WebSockets or Server-Sent Events can provide real-time updates to your UI as events are received.

Talk to agent node in workflows

This is in early access, please contact support to have it enabled for you.

If you’re using DevRev workflows:

The workflow engine handles the async API calls for you when using the Talk To Agent node.

  1. Add the “Talk To Agent” node to your workflow
  2. Configure it with your agent ID
  3. Connect it to response nodes to process the agent’s output
  4. The async API is used automatically by the workflow engine

Troubleshooting

Common issues and their solutions

Not receiving webhook events?

  • Verify your webhook URL is publicly accessible
  • Check that you’ve registered for the “ai_agent_response” event type
  • Ensure your server responds with a 2xx status code quickly

Execution errors?

  • Check the error message in the error event
  • Verify your agent ID is correct
  • Ensure your session_object is a valid string

Agent not responding as expected?

  • Review the skill_triggered and skill_executed events to see which skills were invoked
  • Check if any skills returned error outputs
  • Verify your agent’s configuration in the DevRev agent builder
Was this page helpful?
Built with