​

Getting Started with ActionKit

ActionKit allows you to call one-off Integration Actions for your users (like Salesforce: Create Record or Google Drive: Get Files), without building and deploying specific workflows.

The ActionKit is designed to give AI agents the ability to call out to integration logic as a part of a prompt or ongoing conversation with a user. The API exposes JSON Schema and OpenAPI specs to easily provide your agent with capabilities including:

• Creating tasks in Jira based on action items an agent recognizes from a meeting transcript

• Querying real-time sales reports in Shopify when an agent is asked questions about online sales

• Creating a Google Docs draft to start a project based on a user prompt

ActionKit can also be used to allow your users to configure their own automations in your app using available Actions or to build UI components in your app powered by Actions, like displaying a table of Salesforce opportunities or a dropdown to select Jira projects.

​

Usage

There are two ways to consume the ActionKit: using the REST API or using one of our client libraries.

​

REST API

Base URL

```jsx
https://actions.useparagon.com/projects/[Project ID]
```

Authentication

To authenticate to the ActionKit, present a Bearer token with the Paragon User Token (a JWT):

```jsx
Authorization: Bearer [Paragon User Token]
```

​

TypeScript Client

Install the Actions library with:

```jsx
npm install @useparagon/actions
```

You can authenticate as a specific user using paragon.authenticate:

import paragon from "@useparagon/actions";

await paragon.authenticate("[Project ID]", "[Paragon User Token]");

​

Functions

​

List Actions

Every Connected User will have access to different Actions, depending on what Integrations you have enabled in your project and what accounts they have connected. You can list available Actions using the GET /actions endpoint.

// Fetch by category
GET /actions?format=json_schema
&categories=crm,project_management

// Or by integration
GET /actions?format=json_schema
&integrations=zendesk,slack

Parameters

​

Run Action

To run an Action, call the Run Actions endpoint with the required parameters.

POST /actions

{
	"action": "HUBSPOT_CREATE_RECORD",
	"parameters": {
		"recordType": "deals",
		"field-dealname": "New Deal"
	}
}

​

Integrating with Agents

The @useparagon/actions library provides convenience methods for adding Actions as available functions or tools to your agent, createAISDKTools and createLangChainTools.

If you are using TypeScript and either Vercel’s AI SDK or LangChain, you can use these methods to add Actions as capabilities with a few lines of code.

```javascript Using Vercel
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { createAISDKTools, paragon } from '@useparagon/actions';

// Authenticate Paragon user
await paragon.authenticate("project-id", "user-token");

// Get Paragon Actions to include
const actions = await paragon.getActions({
	format: "json_schema",
	limit_to_available: false,
	categories: [IntegrationCategory.CRM, IntegrationCategory.PROJECT_MANAGEMENT],
});

await generateText({
	model: openai('gpt-4o'),
	tools: createAISDKTools(actions),
	toolChoice: 'auto',
	temperature: 0,
	system: 'You are a helpful assistant. Be as concise as possible.',
	prompt: 'Help me create a new task in Jira.'
});
```

Other Implementations

If you’re not using TypeScript, you can pass the JSON Schema specs from the ActionKit to the request to your LLM. Here is an example in Python with OpenAI’s library:

import requests
from openai import OpenAI
client = OpenAI()

actions_url = f"https://actions.useparagon.com/projects/{project_id}/actions"
actions_auth_header = {
	"Authorization": f"Bearer {user_token}"
}
get_actions_params = {
    "format": "json_schema",
    "categories": "crm,project_management"
}

response = requests.get(actions_url, params=params, headers=actions_auth_header)
paragon_tools = response.json()

messages = [{"role": "user", "content": "Help me create a Jira ticket"}]
completion = client.chat.completions.create(
  model="gpt-4o",
  messages=messages,
  tools=paragon_tools,
  tool_choice="auto"
)

When passing the specs directly, you will also need to respond to the agent’s request to use a tool and route it to the ActionKit:

message = completion["choices"][0]["message"]

if message.get("function_call"):
    function_name = message["function_call"]["name"]
    arguments = json.loads(message["function_call"]["arguments"])
    
    # Check if this tool uses ActionKit
    if any(tool["name"] == function_name for tool in paragon_tools):
	    run_actions_body = {
		    "action": function_name,
		    "parameters": arguments
	    }

	    # Run Action
			response = requests.post(actions_url, body=run_actions_body, headers=actions_auth_header)
			result = response.json()
	    messages.append({
			    "role": "function",
			    "name": function_name,
			    "content": json.dumps(result)
			})

			# Return to chat with tool result
			completion = client.chat.completions.create(
			  model="gpt-4o",
			  messages=messages,
			  tools=paragon_tools,
			  tool_choice="auto"
			)