Integrate your agent

Once you build and deploy an agent, whether it’s based on our native studio or your external registered agent, SUPERWISE® provides an easy way to integrate your deployable agent.
Users have three out-of-the-box integration options:

📘

Notice

The supplied code snippets differ depending on whether the agent is configured to require authentication or not. Therefore, if you change your authentication settings, please make sure to update your code snippet accordingly.

SDK

If you are a Python developer, this will be the best option for you. Use our SDK to query the deployable agent.

To get started with the SDK, please visit here.

agent_response = sw.agent.ask_worker(agent_id=agent.id, input="your question here", api_token=api_token)

Context Id

To enable users to quickly analyze related agent interactions, our Ask API also accepts an optional ContextId parameter. With this, users can define a Context ID logic that will be logged into the agent logging dataset, allowing for quick analysis of related interactions under the same context

response = sw.agent.ask_worker(agent_id=agent.id, input="your question here", context_id=<CONTEXT_ID>)

Metadata

In some cases, users might want to add their own metadata about user-agent interactions to be logged into the platform's out-of-the-box logging. Such metadata may contain unique data or information about the interacting user (e.g., user ID, operating system, browser agent, etc.) or other solution-specific metadata. To achieve this, the relevant agent dataset contains a "metadata" field of type JSON. Users can pass a valid JSON object containing this information in their API call (using the API directly or via the SDK), and it will be logged accordingly. The metadata field is optional.

response = sw.agent.ask_worker(agent_id=agent.id, input="your question here", context_id=<CONTEXT_ID>. metadata={"key": "value"})

API

If you use the deployable agent as a backend service and want to develop automation based on it or build your own UI on top, and you are not a Python developer, use our REST API option. The provided code snippet includes an example of how to query the API.

def ask_agent_via_api(agent_id, user_input, api_token: str | None = None):
  endpoint_url = f"https://api.superwise.ai/v1/app-worker/{agent_id}/v1/ask"

  payload = {
    "chat_history": [],
    "input": user_input
  }
  headers = {"x-api-token": api_token} if api_token else {}
  resp = requests.post(endpoint_url, json=payload, headers=headers)
  return resp.json()

iFrame

SUPERWISE® provides an out-of-the-box chat client experience. The iframe includes a built-in UI for chatting with the deployable agent, feedback buttons, and relevant interactions to enable a good, usable generic chat experience. Simply embed the iFrame code snippet in your website, and you will get a fully functional chat experience already connected to our deployed backend.

🚧

Use in trusted domains only

Ensure that your website and the iframe are running on trusted domains to maintain the security of the API token.

💪

Give It a Try!

You can test the iframe by using the React code example and embedding it in this React playground. Just make sure to insert your Agent ID and API key.