Agents API

Dataworkz Agents API

Dataworkz Agents are powerful systems that bring together data from multiple systems via tools and leveraging a declarative mechanism to build Agents, can be used as a powerful Agentic RAG system. The API allows you to integrate Agents into any system.

Note: All API calls require an API Token. Please follow these steps to generate an API Key. The API Key has to be provided in the Authorizationheader in the format SSWS <your api key>

Concepts

Dataworkz Agents provide a stateless API that consumes the conversation history so far and responds to the user's question/text appropriately. Agents need to be built and saved in Dataworkz using the AgentBuilder. You can get the agentId from the Agent card in the product UI.

API

Get a list of all agents in this account

get

Get a list of all agents in this account - id, name, description

Authorizations

Authorization

AuthorizationstringRequired

Token

Header parameters

AuthorizationanyOptional

For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '

Responses

200

successful operation

application/json

Responsestring

get

/agents/v1/

HTTPcURLJavaScriptPython

GET /api/agents/v1/ HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*

200

successful operation

[
  {
    "createdByName": "[email protected]",
    "agentId": "47e8366d-5db8-45ae-8457-9259a46bbdad",
    "createdDate": "2025-02-17 04:45:32.593",
    "name": "Customer Support Agent",
    "description": "The agent acts as a customer support representative for users to ask questions and get help.",
    "scenariosCount": "5"
  }
]

Deprecated

[DEPRECATED] Get the agent's response to user text

post

For the given agent specified by the agentId, get the agent's response for the user's text and the conversation history.

Note: This invocation is stateless and does not integrate with Dataworkz's Conversation Store. This API is expected to be deprecated within a few releases. Look at the A2A APIs instead.

Request Body:

The request body has to be a json object with keys - conversationHistory, contextValues (optional). conversationHistory: list object to pass conversation history between user and AI. Each object in the list follows the format - { "by": "AI", "text": "Hi" } or { "by": "USER", "text": "Hi" } contextValues: Any context values if present can be passed - { "contextValueName": contextValue }

Note: This endpoint is deprecated - Take a look at 'The A2A streaming response endpoint of the Agent' for the supported way to invoke an Agent.

Authorizations

Authorization

AuthorizationstringRequired

Token

Path parameters

agentIdstringRequired

Id of the Agent in the system

Example: 3756809c-4032-4e48-b3f0-2a6d30a03a54

Query parameters

userTextstringRequired

The last text from the user. Must be url encoded.

Example: What is the status of the order?

llmProviderIdstringRequired

Id of the LLM to use for the agent. This must be one of the LLMs configured in this account. Currently, gpt-4 and llama3-70B models are supported. Id can be copied from the LLM Configuration page.

Example: 3756809c-4032-4e48-b3f0-2a6d30a03a54

propertiesstringOptional

Any additional properties to be passed to influence execution

Header parameters

AuthorizationanyOptional

For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '

Body

application/json

objectOptional

Responses

200

successful operation. The agent's response is available in 'answer'. If structuredResponse is configured then it is available in the key 'structuredResponse'. Probe is returned in the 'probe'.

application/json

Responseobject

post

/agents/v1/{agentId}/response

HTTPcURLJavaScriptPython

POST /api/agents/v1/{agentId}/response?userText=text&llmProviderId=text HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 169

{
  "conversationHistory": [
    {
      "by": "USER",
      "text": "Hi"
    },
    {
      "by": "AI",
      "text": "Hi! How can I assist you today?"
    }
  ],
  "contextValues": {
    "variable1": "value1",
    "variable2": {
      "obj": "val"
    }
  }
}

200

successful operation. The agent's response is available in 'answer'. If structuredResponse is configured then it is available in the key 'structuredResponse'. Probe is returned in the 'probe'.

{
  "status": "OK",
  "data": {
    "question": "Hi",
    "systemName": "TestAgent",
    "answer": "Hello! How can I assist you today?",
    "scenario": "Greet",
    "type": "agent",
    "questionUuid": "e9e6d058-79ff-4165-a409-d0e9a38b4802",
    "status": "COMPLETED",
    "systemId": "5ccea050-aff5-4e37-8572-d2e486987843",
    "structuredResponse": {
      "scenario": "Greet",
      "agentResponse": "Hello! How can I assist you today?",
      "responseType": "Finish",
      "structuredOutput": ""
    },
    "queryPlan": "",
    "probe": ""
  }
}

Get LLM providers configured in Dataworkz

get

Returns a map containing unique identifier and LLM models that have been configured

Authorizations

Authorization

AuthorizationstringRequired

Token

Header parameters

AuthorizationanyOptional

For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '

Responses

200

successful operation

application/json

Responseobject

get

/agents/v1/llm-providers

HTTPcURLJavaScriptPython

GET /api/agents/v1/llm-providers HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*

200

successful operation

{
  "47b51bb5-bdfa-413d-8bfa-ff040ab1c901": "llama-2-13b-chat"
}

Get the A2A Agent Card for a specific agent

get

Get the A2A Agent Card for a specific agent. The Agent Card details are available in the A2A specification.

Authorizations

Authorization

AuthorizationstringRequired

Token

Path parameters

agentIdstringRequired

Responses

200

OK

application/json

get

/agents/v1/a2a/{agentId}/.well-known/agent.json

HTTPcURLJavaScriptPython

GET /api/agents/v1/a2a/{agentId}/.well-known/agent.json HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*

200

OK

{
  "name": "text",
  "description": "text",
  "url": "text",
  "provider": {
    "organization": "text",
    "url": "text"
  },
  "version": "text",
  "documentationUrl": "text",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true,
    "extensions": [
      {
        "description": "text",
        "params": {},
        "required": true,
        "uri": "text"
      }
    ]
  },
  "defaultInputModes": [
    "text"
  ],
  "defaultOutputModes": [
    "text"
  ],
  "skills": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "tags": [
        "text"
      ],
      "examples": [
        "text"
      ],
      "inputModes": [
        "text"
      ],
      "outputModes": [
        "text"
      ]
    }
  ],
  "supportsAuthenticatedExtendedCard": true,
  "securitySchemes": {},
  "security": [
    {}
  ],
  "iconUrl": "text"
}

Get the A2A Agent Card for a specific agent

get

Get the A2A Agent Card for a specific agent. The Agent Card details are available in the A2A specification

Authorizations

Authorization

AuthorizationstringRequired

Token

Path parameters

agentIdstringRequired

Header parameters

AuthorizationanyOptional

For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '

Responses

200

OK

application/json

get

/agents/v1/a2a/{agentId}/.well-known/agent-card.json

HTTPcURLJavaScriptPython

GET /api/agents/v1/a2a/{agentId}/.well-known/agent-card.json HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*

200

OK

{
  "name": "text",
  "description": "text",
  "url": "text",
  "provider": {
    "organization": "text",
    "url": "text"
  },
  "version": "text",
  "documentationUrl": "text",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true,
    "extensions": [
      {
        "description": "text",
        "params": {},
        "required": true,
        "uri": "text"
      }
    ]
  },
  "defaultInputModes": [
    "text"
  ],
  "defaultOutputModes": [
    "text"
  ],
  "skills": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "tags": [
        "text"
      ],
      "examples": [
        "text"
      ],
      "inputModes": [
        "text"
      ],
      "outputModes": [
        "text"
      ]
    }
  ],
  "supportsAuthenticatedExtendedCard": true,
  "securitySchemes": {},
  "security": [
    {}
  ],
  "iconUrl": "text"
}

The A2A streaming response endpoint of the Agent

post

Sends a message to an agent to initiate/continue a task AND subscribes the client to real-time updates for that task via Server-Sent Events (SSE). Refer to the A2A specification for details.

Supported Extensions:

• Refer to this for details on how extensions are activated.

• To activate an extension you MUST send its URI in an HTTP Header named X-A2A-Extensions.

Send Context Variables

Dataworkz A2A Agents API supports an A2A extension to send context values for an agent invocation. This might change in the future as the spec evolves. To use this extension you must -

• activate this extension by sending a header in your request - X-A2A-Extensions: https://dataworkz.com/agents/ext/provided-values/v1.

• The context values should be present in the input Message in a DataPart as a Json Object with keys as the variable names and the values as their value (see example below).

• Metadata for the Part must include the URI https://dataworkz.com/agents/ext/provided-values/v1 : true

Here's an example of a Part definition for sending context values

{
  "kind": "data",
  "metadata": { "https://dataworkz.com/agents/ext/provided-values/v1": true },
  "data": {
    "context-var": "value",
    "context-var-2": { ... value ... }
  }
}

Response

Agent Response : The Agent's Response is available in an Server-Sent Event of kind : status-update where status: is of state: completed. Basically, only events that are final events can have the agent response - successful or failure. Here's an example -

{
  "jsonrpc": "2.0",
  "id": "msg-1752069031164-mzzokdfi3",
  "result": {
    "kind": "status-update",
    "taskId": "8b785e97-fbf5-4951-a09b-a70e32cd07fb",
    "status": {
      "state": "completed",
      "message": {
        "kind": "message",
        "role":  "agent",
        "parts": [
          {
            "kind": "text",
            "text": "Hello! How can I assist you today?",
            "metadata": {
              "mimetype": "text/plain"
            },
            "kind": "text"
          }
        ],
        "messageId": "49b7d288-27f6-4210-bdd8-d63fecbd0251",
        "contextId": "7c43d2c8-e111-4a57-bbeb-82e9d694a316",
        "taskId": "8b785e97-fbf5-4951-a09b-a70e32cd07fb",
        "metadata": {},
        "kind": "message"
      },
      "timestamp": "2025-08-25T10:39:40.450635"
    },
    "contextId": "7c43d2c8-e111-4a57-bbeb-82e9d694a316",
    "final": true,
    "kind": "status-update"
  }
}

Task Updates : The Agent system emits Server-Sent Events as it progresses through the Agent Execution. These are available as DataParts and they are marked with this metadata "type": "DW_STATUS_UPDATE".

{
  "jsonrpc": "2.0",
  "id": "msg-1752069031164-mzzokdfi3",
  "result": {
    "kind": "status-update",
    "taskId": "8b785e97-fbf5-4951-a09b-a70e32cd07fb",
    "status": {
      "state": "working",
      "message": {
        "kind": "message",
        "role": "agent",
        "parts": [
          {
            "kind": "data",
            "data": {
              "status": {
                "planning": {
                  "llmThought": "Scenario has no tools so generating the minimal plan.",
                  "type": "Planning",
                  "name": "Plan",
                  "metadata": {},
                  "status": "completed"
                },
                "executions": [],
                "agentResponse": {
                  "type": "Join",
                  "name": "Agent Response",
                  "metadata": {},
                  "status": "in_progress"
                },
                "type": "Iteration",
                "name": "Iteration 0",
                "metadata": {},
                "status": "in_progress"
              }
            }
          }
        ],
        "messageId": "4e307055-9754-4137-a1bb-d6aeeca1dc7e",
        "contextId": "7c43d2c8-e111-4a57-bbeb-82e9d694a316",
        "taskId": "8b785e97-fbf5-4951-a09b-a70e32cd07fb",
        "metadata": {
          "type": "DW_STATUS_UPDATE"
        }
      },
      "timestamp": "2025-08-25T10:39:38.679435"
    },
    "contextId": "7c43d2c8-e111-4a57-bbeb-82e9d694a316",
    "final": false
  }
}

Authorizations

Authorization

AuthorizationstringRequired

Token

Path parameters

agentIdstringRequired

Id of the Agent in the system

Example: 3756809c-4032-4e48-b3f0-2a6d30a03a54

Query parameters

llmIdstringOptional

Id of the LLM to use for the agent. This must be one of the LLMs configured in this account. Id can be copied from the LLM Configuration page or retrieved by a call to the llm-providers endpoint. If not provided, the llmId configured in the agent is used, if that's not present then the llm marked default in LLM Configurations is used. If not LLM Id is found, the request will fail.

Example: 3756809c-4032-4e48-b3f0-2a6d30a03a54

propertiesstringOptional

Any additional properties to be passed to influence execution

Body

application/json

jsonrpcstringOptional

idobjectOptional

methodstringOptional

paramsobjectOptional

Responses

200

OK

text/event-streamapplication/json

post

/agents/v1/a2a/{agentId}/stream

HTTPcURLJavaScriptPython

POST /api/agents/v1/a2a/{agentId}/stream HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "jsonrpc": "text",
  "id": {},
  "method": "text",
  "params": {}
}

200

OK

{
  "timeout": 1
}